sovrium 0.0.2

package/src/domain/models/app/theme/spacing.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 { Schema } from 'effect'
+
+/**
+ * Spacing Configuration
+ *
+ * Spacing design tokens for consistent layout. Supports both Tailwind utility
+ * classes (py-16, px-4) and raw CSS values (4rem, 16px, 1.5em).
+ *
+ * **Behavior Specifications**:
+ * - Validates Tailwind spacing utilities (py-16, px-4, gap-6, etc.)
+ * - Validates responsive spacing with Tailwind breakpoints (py-16 sm:py-20)
+ * - Validates centering and width constraints (max-w-7xl mx-auto px-4)
+ * - Validates consistent spacing scale (gap-small, gap, gap-large)
+ * - Validates custom CSS spacing values (2rem, 16px, 1.5em)
+ * - Supports hierarchical content width constraints (container, container-small, container-xsmall)
+ *
+ * **Token Categories**:
+ * - Section spacing: Vertical rhythm for page sections (py-16 sm:py-20)
+ * - Container spacing: Width constraints and centering (max-w-7xl mx-auto px-4)
+ * - Gap spacing: Space between flex/grid items (gap-6)
+ * - Padding spacing: Internal component spacing (p-6, p-4, p-8)
+ * - Margin spacing: External component spacing (m-6, m-4, m-8)
+ *
+ * @example
+ * ```typescript
+ * // Complete spacing system
+ * const spacing = {
+ *   section: 'py-16 sm:py-20',
+ *   container: 'max-w-7xl mx-auto px-4',
+ *   'container-small': 'max-w-4xl mx-auto px-4',
+ *   'container-xsmall': 'max-w-2xl mx-auto px-4',
+ *   gap: 'gap-6',
+ *   'gap-small': 'gap-4',
+ *   'gap-large': 'gap-8',
+ *   padding: 'p-6',
+ *   'padding-small': 'p-4',
+ *   'padding-large': 'p-8',
+ *   margin: 'm-6',
+ *   'margin-small': 'm-4',
+ *   'margin-large': 'm-8'
+ * }
+ * ```
+ *
+ * @see specs/app/theme/spacing/spacing.schema.json
+ */
+export const SpacingConfigSchema = Schema.Record({
+  key: Schema.String.pipe(
+    Schema.pattern(/^[a-z]+(-[a-z]+)*$/, {
+      message: () => 'Spacing key must use kebab-case (e.g., container-small, not containerSmall)',
+    }),
+    Schema.annotations({
+      title: 'Spacing Token Name',
+      description: 'Kebab-case name for spacing token (e.g., container-small, not containerSmall)',
+      examples: [
+        'section',
+        'container',
+        'container-small',
+        'gap',
+        'gap-small',
+        'padding',
+        'margin',
+      ],
+    })
+  ),
+  value: Schema.String.pipe(
+    Schema.annotations({
+      title: 'Spacing Value',
+      description:
+        'Spacing value as Tailwind utility classes or CSS values (rem, px, em, %). Supports responsive variants (sm:, md:, lg:) and multiple classes.',
+      examples: [
+        'py-16',
+        'px-4',
+        'py-16 sm:py-20',
+        'max-w-7xl mx-auto px-4',
+        'gap-6',
+        'p-6',
+        'm-6',
+        '4rem',
+        '16px',
+        '1.5em',
+      ],
+    })
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'Spacing Configuration',
+    description: 'Spacing design tokens for consistent layout',
+    examples: [
+      {
+        section: 'py-16 sm:py-20',
+        container: 'max-w-7xl mx-auto px-4',
+        'container-small': 'max-w-4xl mx-auto px-4',
+        'container-xsmall': 'max-w-2xl mx-auto px-4',
+        gap: 'gap-6',
+        'gap-small': 'gap-4',
+        'gap-large': 'gap-8',
+        padding: 'p-6',
+        'padding-small': 'p-4',
+        'padding-large': 'p-8',
+        margin: 'm-6',
+        'margin-small': 'm-4',
+        'margin-large': 'm-8',
+      },
+    ],
+  })
+)
+
+export type SpacingConfig = Schema.Schema.Type<typeof SpacingConfigSchema>

package/src/domain/models/app/theme.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 { Schema } from 'effect'
+import { AnimationsConfigSchema } from './theme/animations'
+import { BorderRadiusConfigSchema } from './theme/border-radius'
+import { BreakpointsConfigSchema } from './theme/breakpoints'
+import { ColorsConfigSchema } from './theme/colors'
+import { FontsConfigSchema } from './theme/fonts'
+import { ShadowsConfigSchema } from './theme/shadows'
+import { SpacingConfigSchema } from './theme/spacing'
+
+/**
+ * Theme configuration orchestrating all design token categories
+ *
+ * Provides a unified design system by composing:
+ * - colors: Visual identity and branding
+ * - fonts: Typography system
+ * - spacing: Layout rhythm and whitespace
+ * - animations: Motion design library
+ * - breakpoints: Responsive system thresholds
+ * - shadows: Elevation and depth
+ * - borderRadius: Corner styling
+ *
+ * All properties are optional, allowing minimal themes (colors-only)
+ * or comprehensive design systems (all 7 categories).
+ *
+ * @example
+ * ```typescript
+ * const minimalTheme = {
+ *   colors: { primary: '#007bff' }
+ * }
+ *
+ * const completeTheme = {
+ *   colors: { primary: '#007bff' },
+ *   fonts: { body: { family: 'Inter' } },
+ *   spacing: { section: '4rem' },
+ *   animations: { fadeIn: true },
+ *   breakpoints: { md: '768px' },
+ *   shadows: { md: '0 4px 6px -1px rgb(0 0 0 / 0.1)' },
+ *   borderRadius: { md: '0.375rem' }
+ * }
+ * ```
+ *
+ * @see specs/app/theme/theme.schema.json
+ */
+export const ThemeSchema = Schema.Struct({
+  colors: Schema.optional(ColorsConfigSchema),
+  fonts: Schema.optional(FontsConfigSchema),
+  spacing: Schema.optional(SpacingConfigSchema),
+  animations: Schema.optional(AnimationsConfigSchema),
+  breakpoints: Schema.optional(BreakpointsConfigSchema),
+  shadows: Schema.optional(ShadowsConfigSchema),
+  borderRadius: Schema.optional(BorderRadiusConfigSchema),
+}).pipe(
+  Schema.annotations({
+    title: 'Theme Configuration',
+    description: 'Design tokens for colors, typography, spacing, and animations',
+  })
+)
+
+export type Theme = Schema.Schema.Type<typeof ThemeSchema>

package/src/domain/models/app/version.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 { Schema } from 'effect'
+
+/**
+ * VersionSchema defines validation rules for application versions.
+ *
+ * Application versions must follow Semantic Versioning (SemVer) 2.0.0 specification:
+ * - Format: MAJOR.MINOR.PATCH (e.g., 1.0.0)
+ * - Each component must be a non-negative integer without leading zeros
+ * - Optional pre-release identifiers after hyphen (e.g., 1.0.0-alpha, 1.0.0-beta.1)
+ * - Optional build metadata after plus sign (e.g., 1.0.0+build.123)
+ *
+ * Valid version format:
+ * - MAJOR version: Incremented for incompatible API changes
+ * - MINOR version: Incremented for backwards-compatible functionality additions
+ * - PATCH version: Incremented for backwards-compatible bug fixes
+ * - Pre-release: Hyphen followed by dot-separated identifiers (alphanumeric + hyphen)
+ * - Build metadata: Plus sign followed by dot-separated identifiers (alphanumeric + hyphen)
+ *
+ * @see https://semver.org/
+ *
+ * @example
+ * ```typescript
+ * // Valid versions
+ * const version1 = '1.0.0'
+ * const version2 = '0.0.1'
+ * const version3 = '1.2.3'
+ * const version4 = '1.0.0-alpha'
+ * const version5 = '1.0.0-beta.1'
+ * const version6 = '2.0.0-rc.1'
+ * const version7 = '1.0.0+build.123'
+ * const version8 = '1.0.0-alpha+001'
+ *
+ * // Validate version
+ * const validated = Schema.decodeUnknownSync(VersionSchema)(version1)
+ * ```
+ */
+export const VersionSchema = Schema.String.pipe(
+  Schema.minLength(5, { message: () => 'Version must not be empty (minimum format: 0.0.0)' }),
+  Schema.pattern(
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/,
+    {
+      message: () =>
+        'Version must follow Semantic Versioning format (MAJOR.MINOR.PATCH, e.g., 1.0.0). No leading zeros allowed. Optional pre-release (-alpha) and build metadata (+build.123) are supported.',
+    }
+  ),
+  Schema.annotations({
+    title: 'Application Version',
+    description:
+      'The version of the application following Semantic Versioning (SemVer) 2.0.0 specification',
+    examples: [
+      '1.0.0',
+      '0.0.1',
+      '1.2.3',
+      '1.0.0-alpha',
+      '1.0.0-beta.1',
+      '2.0.0-rc.1',
+      '1.0.0+build.123',
+      '1.0.0-alpha+001',
+    ],
+  })
+)
+
+/**
+ * TypeScript type inferred from VersionSchema.
+ *
+ * Use this type for type-safe access to validated version strings.
+ *
+ * @example
+ * ```typescript
+ * const version: Version = '1.0.0'
+ * ```
+ */
+export type Version = Schema.Schema.Type<typeof VersionSchema>
+
+/**
+ * Encoded type of VersionSchema (what goes in).
+ *
+ * In this case, it's the same as Version since we don't use transformations.
+ */
+export type VersionEncoded = Schema.Schema.Encoded<typeof VersionSchema>

package/src/domain/models/record-comment.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 { Schema } from 'effect'
+
+/**
+ * Record Comment Domain Model
+ *
+ * Represents a comment on a table record with:
+ * - Content validation (non-empty, max 10,000 chars)
+ * - Support for @mentions stored as @[user_id]
+ * - Auto-injected user_id from session
+ * - Timestamps for audit trail
+ */
+
+/**
+ * Comment ID - UUID string
+ */
+export const CommentIdSchema = Schema.String.pipe(
+  Schema.pattern(/^[a-f0-9-]+$/, {
+    message: () => 'Comment ID must be a valid UUID',
+  }),
+  Schema.brand('CommentId')
+)
+
+export type CommentId = typeof CommentIdSchema.Type
+
+/**
+ * Comment Content - non-empty, max 10,000 characters
+ * Supports @mentions as @[user_id] format
+ */
+export const CommentContentSchema = Schema.String.pipe(
+  Schema.minLength(1, { message: () => 'Comment content cannot be empty' }),
+  Schema.maxLength(10_000, {
+    message: () => 'Comment content cannot exceed 10,000 characters',
+  })
+)
+
+export type CommentContent = typeof CommentContentSchema.Type
+
+/**
+ * Record Comment Schema
+ */
+export const RecordCommentSchema = Schema.Struct({
+  id: CommentIdSchema,
+  recordId: Schema.String,
+  tableId: Schema.String,
+  userId: Schema.String,
+  content: CommentContentSchema,
+  createdAt: Schema.Date,
+  updatedAt: Schema.optionalWith(Schema.Date, { nullable: true }),
+  deletedAt: Schema.optionalWith(Schema.Date, { nullable: true }),
+})
+
+export type RecordComment = typeof RecordCommentSchema.Type
+
+/**
+ * Create Comment Input - content only (other fields auto-injected)
+ */
+export const CreateCommentInputSchema = Schema.Struct({
+  content: CommentContentSchema,
+})
+
+export type CreateCommentInput = typeof CreateCommentInputSchema.Type
+
+/**
+ * Comment with User Metadata (for API responses)
+ */
+export const CommentWithUserSchema = Schema.Struct({
+  id: CommentIdSchema,
+  recordId: Schema.String,
+  tableId: Schema.String,
+  userId: Schema.String,
+  content: CommentContentSchema,
+  createdAt: Schema.Date,
+  user: Schema.optionalWith(
+    Schema.Struct({
+      id: Schema.String,
+      name: Schema.String,
+      email: Schema.String,
+      image: Schema.optionalWith(Schema.String, { nullable: true }),
+    }),
+    { nullable: true }
+  ),
+})
+
+export type CommentWithUser = typeof CommentWithUserSchema.Type

package/src/domain/utils/content-parsing.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+
+/**
+ * Content Parsing - Pure Functions
+ *
+ * Domain layer utilities for parsing schema content.
+ * These are pure functions with no side effects.
+ */
+
+import { load as parseYaml } from 'js-yaml'
+import type { SchemaFormat } from './format-detection'
+import type { AppEncoded } from '@/domain/models/app'
+
+/**
+ * Parse JSON content to AppEncoded
+ */
+export const parseJsonContent = (content: string): AppEncoded => JSON.parse(content) as AppEncoded
+
+/**
+ * Parse YAML content to AppEncoded
+ */
+export const parseYamlContent = (content: string): AppEncoded => parseYaml(content) as AppEncoded
+
+/**
+ * Parse schema content based on detected format
+ * Falls back to trying JSON first, then YAML if format is undefined
+ */
+export const parseSchemaContent = (
+  content: string,
+  format: SchemaFormat | undefined
+): AppEncoded => {
+  if (format === 'json') {
+    return parseJsonContent(content)
+  }
+  if (format === 'yaml') {
+    return parseYamlContent(content)
+  }
+  // Last fallback: try JSON first, then YAML
+  try {
+    return parseJsonContent(content)
+  } catch {
+    return parseYamlContent(content)
+  }
+}

package/src/domain/utils/format-detection.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.
+ */
+
+/**
+ * Format Detection - Pure Functions
+ *
+ * Domain layer utilities for detecting schema file formats.
+ * These are pure functions with no side effects.
+ */
+
+/** Supported schema formats */
+export type SchemaFormat = 'json' | 'yaml'
+
+/** Format detection result */
+export type FormatDetectionResult = SchemaFormat | 'unsupported'
+
+/**
+ * Detect file format from file extension
+ */
+export const detectFormat = (filePath: string): FormatDetectionResult => {
+  const lowerPath = filePath.toLowerCase()
+  if (lowerPath.endsWith('.json')) return 'json'
+  if (lowerPath.endsWith('.yaml') || lowerPath.endsWith('.yml')) return 'yaml'
+  return 'unsupported'
+}
+
+/**
+ * Extract file extension from path
+ */
+export const getFileExtension = (filePath: string): string => {
+  const match = filePath.match(/\.([^.]+)$/)
+  return match?.[1] ?? ''
+}
+
+/**
+ * Detect format from Content-Type header
+ */
+export const detectFormatFromContentType = (contentType: string): SchemaFormat | undefined => {
+  if (contentType.includes('application/json')) return 'json'
+  if (contentType.includes('application/x-yaml') || contentType.includes('text/yaml')) return 'yaml'
+  return undefined
+}
+
+/**
+ * Detect format from URL file extension
+ */
+export const detectFormatFromUrl = (url: string): SchemaFormat | undefined => {
+  const urlLower = url.toLowerCase()
+  if (urlLower.endsWith('.json')) return 'json'
+  if (urlLower.endsWith('.yaml') || urlLower.endsWith('.yml')) return 'yaml'
+  return undefined
+}
+
+/**
+ * Check if a string value looks like inline JSON
+ */
+export const isInlineJson = (value: string): boolean => value.trim().startsWith('{')
+
+/**
+ * Check if a string value is a URL
+ */
+export const isUrl = (value: string): boolean => {
+  const trimmed = value.trim()
+  return trimmed.startsWith('http://') || trimmed.startsWith('https://')
+}

package/src/domain/utils/index.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 * from './format-detection'
+export * from './content-parsing'

package/src/domain/utils/route-matcher.ts

@@ -0,0 +1,184 @@
+/**
+ * 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.
+ */
+
+/**
+ * Route parameters extracted from a dynamic path
+ *
+ * @example
+ * ```typescript
+ * const params = { slug: 'hello-world', id: '123' }
+ * ```
+ */
+export type RouteParams = Readonly<Record<string, string>>
+
+/**
+ * Result of matching a URL against a route pattern
+ */
+export type RouteMatch = {
+  readonly matched: boolean
+  readonly params: RouteParams
+}
+
+/**
+ * Converts a route pattern with dynamic segments into a regular expression
+ *
+ * Dynamic segments are defined with a colon prefix (e.g., :id, :slug)
+ *
+ * @param pattern - Route pattern (e.g., '/blog/:slug', '/products/:id')
+ * @returns Regular expression to match URLs and capture parameters
+ *
+ * @example
+ * ```typescript
+ * const regex = patternToRegex('/blog/:slug')
+ * // Returns: /^\/blog\/([^/]+)$/
+ *
+ * const regex2 = patternToRegex('/users/:userId/posts/:postId')
+ * // Returns: /^\/users\/([^/]+)\/posts\/([^/]+)$/
+ * ```
+ */
+function patternToRegex(pattern: string): Readonly<RegExp> {
+  // Escape forward slashes and convert :param to capture groups
+  const regexPattern = pattern
+    .split('/')
+    .map((segment) => {
+      if (segment.startsWith(':')) {
+        // Dynamic segment - capture any characters except forward slash
+        return '([^/]+)'
+      }
+      // Static segment - escape special regex characters
+      return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    })
+    .join('/')
+
+  return new RegExp(`^${regexPattern}$`)
+}
+
+/**
+ * Extracts parameter names from a route pattern
+ *
+ * @param pattern - Route pattern (e.g., '/blog/:slug')
+ * @returns Array of parameter names (e.g., ['slug'])
+ *
+ * @example
+ * ```typescript
+ * const params = extractParamNames('/blog/:slug')
+ * // Returns: ['slug']
+ *
+ * const params2 = extractParamNames('/users/:userId/posts/:postId')
+ * // Returns: ['userId', 'postId']
+ * ```
+ */
+function extractParamNames(pattern: string): readonly string[] {
+  return pattern
+    .split('/')
+    .filter((segment) => segment.startsWith(':'))
+    .map((segment) => segment.slice(1)) // Remove colon prefix
+}
+
+/**
+ * Matches a URL path against a route pattern and extracts parameters
+ *
+ * Pure function with no side effects
+ *
+ * @param pattern - Route pattern with optional dynamic segments (e.g., '/blog/:slug')
+ * @param urlPath - Actual URL path to match (e.g., '/blog/hello-world')
+ * @returns Match result with extracted parameters
+ *
+ * @example
+ * ```typescript
+ * // Static route
+ * matchRoute('/about', '/about')
+ * // Returns: { matched: true, params: {} }
+ *
+ * // Dynamic route with single parameter
+ * matchRoute('/blog/:slug', '/blog/hello-world')
+ * // Returns: { matched: true, params: { slug: 'hello-world' } }
+ *
+ * // Dynamic route with multiple parameters
+ * matchRoute('/users/:userId/posts/:postId', '/users/123/posts/456')
+ * // Returns: { matched: true, params: { userId: '123', postId: '456' } }
+ *
+ * // No match
+ * matchRoute('/blog/:slug', '/products/123')
+ * // Returns: { matched: false, params: {} }
+ * ```
+ */
+export function matchRoute(pattern: string, urlPath: string): RouteMatch {
+  // Static route - exact match
+  if (!pattern.includes(':')) {
+    return {
+      matched: pattern === urlPath,
+      params: {},
+    }
+  }
+
+  // Dynamic route - use regex matching
+  const regex = patternToRegex(pattern)
+  const match = urlPath.match(regex)
+
+  if (!match) {
+    return {
+      matched: false,
+      params: {},
+    }
+  }
+
+  // Extract parameter names and values
+  const paramNames = extractParamNames(pattern)
+  const paramValues = match.slice(1) // Remove full match, keep capture groups
+
+  // Use reduce to build params object functionally (no mutation)
+  const params = paramNames.reduce<Record<string, string>>((acc, name, i) => {
+    const value = paramValues[i]
+    if (name && value) {
+      return { ...acc, [name]: value }
+    }
+    return acc
+  }, {})
+
+  return {
+    matched: true,
+    params,
+  }
+}
+
+/**
+ * Finds the first matching route from a list of patterns
+ *
+ * Pure function with no side effects
+ *
+ * @param patterns - Array of route patterns to try
+ * @param urlPath - URL path to match
+ * @returns Index of matched pattern and extracted parameters, or undefined if no match
+ *
+ * @example
+ * ```typescript
+ * const patterns = ['/about', '/blog/:slug', '/products/:id']
+ * const result = findMatchingRoute(patterns, '/blog/hello-world')
+ * // Returns: { index: 1, params: { slug: 'hello-world' } }
+ *
+ * const result2 = findMatchingRoute(patterns, '/not-found')
+ * // Returns: undefined
+ * ```
+ */
+export function findMatchingRoute(
+  patterns: readonly string[],
+  urlPath: string
+): { readonly index: number; readonly params: RouteParams } | undefined {
+  // Use findIndex + map to avoid imperative loop
+  const matchResult = patterns
+    .map((pattern, index) => ({ pattern, index }))
+    .filter(({ pattern }) => pattern !== undefined && pattern !== '')
+    .find(({ pattern }) => matchRoute(pattern, urlPath).matched)
+
+  if (!matchResult) {
+    return undefined
+  }
+
+  const match = matchRoute(matchResult.pattern, urlPath)
+  return { index: matchResult.index, params: match.params }
+}