sovrium 0.1.0 → 0.2.0

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <h1 align="center">Sovrium</h1>
+</p>
+
 <h3 align="center">Build business apps with config. Own your data forever.</h3>
 
 <p align="center">
@@ -7,7 +11,6 @@
 
 <p align="center">
   <a href="https://github.com/sovrium/sovrium/blob/main/LICENSE.md"><img src="https://img.shields.io/badge/license-BSL--1.1-blue" alt="License" /></a>
-  <a href="SPEC-PROGRESS.md"><img src="https://img.shields.io/badge/specs-99%25_passing-brightgreen" alt="Specs" /></a>
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun_1.3-f472b6" alt="Bun" /></a>
   <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5.9-3178c6" alt="TypeScript" /></a>
   <a href="https://www.npmjs.com/package/sovrium"><img src="https://img.shields.io/npm/v/sovrium" alt="npm" /></a>
@@ -15,21 +18,22 @@
 </p>
 
 <p align="center">
+  <a href="https://sovrium.com">Website</a> &middot;
   <a href="VISION.md">Vision</a> &middot;
   <a href="SPEC-PROGRESS.md">Roadmap</a> &middot;
   <a href="CLAUDE.md">Docs</a> &middot;
   <a href="https://github.com/sovrium/sovrium/issues">Issues</a>
 </p>
 
+<!-- TODO: Add a product screenshot or demo GIF here (recommended: 1200x800px). -->
+
 ---
 
 ## What is Sovrium?
 
-Sovrium turns **configuration files** into full-featured web applications -- database, auth, API, and UI included.
-
-No code generation. No external services. Just config and `sovrium start`.
+Sovrium turns a **configuration file** into a complete web application — database, authentication, API, and pages included.
 
-**Choose your format** -- YAML for readability, TypeScript for type safety:
+No code generation. No external services. Write a config file, run one command, and your app is live.
 
 ```yaml
 # sovrium.yaml
@@ -60,11 +64,15 @@ pages:
         content: Welcome to My CRM
 ```
 
+```bash
+sovrium start sovrium.yaml
+# -> http://localhost:3000
+```
+
 <details>
-<summary>Or use TypeScript for IDE completion</summary>
+<summary>Prefer TypeScript? Use it for autocompletion and type checking.</summary>
 
 ```typescript
-// app.ts
 import { start } from 'sovrium'
 
 await start({
@@ -93,229 +101,101 @@ await start({
 
 </details>
 
-```bash
-sovrium start sovrium.yaml   # Run with YAML
-bun run app.ts               # Or run with TypeScript
-# -> http://localhost:3000
-```
-
----
-
-## Why Sovrium?
-
-**The problem**: Organizations pay $10k+/month for 20+ SaaS tools, with data scattered everywhere and zero control.
-
-**The solution**: One self-hosted platform that does what you need, configured in files you own.
-
-|                     |     Sovrium     |  SaaS Tools  |
-| ------------------- | :-------------: | :----------: |
-| **Data ownership**  |  Your servers   | Vendor cloud |
-| **Monthly cost**    | $0 (infra only) | $20-50/user  |
-| **Vendor lock-in**  |      None       |   Complete   |
-| **Customization**   |    Unlimited    |   Limited    |
-| **Version control** |   Git-native    |     None     |
-
 ---
 
-## Quick Start
+## 🚀 Quick Start
 
-**Requirements**: [Bun](https://bun.sh) 1.3+ and [PostgreSQL](https://www.postgresql.org/) 15+
+**You need**: [Bun](https://bun.sh) 1.3+ and [PostgreSQL](https://www.postgresql.org/) 15+
 
 ```bash
-# Install
 bun add sovrium
-
-# Create config
-cat > sovrium.yaml << EOF
-name: my-app
-pages:
-  - name: home
-    path: /
-    sections:
-      - type: h1
-        content: Hello World
-EOF
-
-# Run
 sovrium start sovrium.yaml
-
-# Or use environment variable (JSON, YAML, or URL)
-APP_SCHEMA='{"name":"my-app"}' sovrium start
-APP_SCHEMA='name: my-app' sovrium start
-APP_SCHEMA='https://example.com/app.yaml' sovrium start
 ```
 
----
-
-## Features
-
-### Database & Tables
-
-Define your data model in config. Sovrium creates PostgreSQL tables, handles migrations, and exposes a full REST API automatically.
-
-- **40 field types** -- text, numeric, date/time, selection, media, relational, user tracking, and advanced types (formula, JSON, geolocation, barcode, autonumber, and more)
-- **Relationships** -- one-to-many and many-to-many with lookup and rollup fields
-- **Views** -- filtered, sorted, and grouped views with field-level visibility
-- **Indexes and constraints** -- primary keys, unique constraints, check constraints
-- **Soft delete** -- built-in trash with restore capability
-- **Permissions** -- role-based table and field-level access control
-- **Schema evolution** -- migration system for safe schema changes
+Your app is running at `http://localhost:3000`.
 
-### REST API
-
-Every table gets a full CRUD API with no additional code.
-
-- **Records** -- create, read, update, delete with field validation
-- **Batch operations** -- bulk create, update, and upsert
-- **Filtering and sorting** -- query records with field-based filters
-- **Pagination** -- cursor and offset-based pagination
-- **Activity logs** -- audit trail for all record changes
-- **Rate limiting** -- configurable per-endpoint rate limits
-
-### Authentication
-
-Production-ready auth out of the box.
-
-- **Email/password** -- sign up, sign in, email verification, password reset
-- **Magic link** -- passwordless email authentication
-- **Two-factor** -- TOTP-based 2FA
-- **OAuth** -- social login providers
-- **Roles** -- admin, member, viewer with custom roles
-- **Admin plugin** -- user management, banning, impersonation
-- **Session management** -- list, revoke, and manage active sessions
-
-### Pages & UI
-
-Server-rendered pages with a component-based system.
-
-- **Dynamic routing** -- path-based page routing
-- **Sections** -- composable content sections with theming support
-- **Reusable components** -- define once with `$ref`, customize with `$vars`
-- **SEO metadata** -- title, description, Open Graph, structured data
-- **Scripts** -- custom head and body scripts per page
-
-### Theming
+---
 
-Design system configuration for consistent styling.
+## ✨ Features
 
-- **Colors** -- primary, secondary, accent, and semantic color tokens
-- **Fonts** -- custom font families with Google Fonts support
-- **Spacing, shadows, border-radius** -- design tokens applied globally
-- **Animations** -- configurable keyframe animations
-- **Breakpoints** -- responsive design breakpoints
+|     | Feature            | What you get                                                                                                                            |
+| :-- | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| 🗄️  | **Tables**         | 40 field types including formulas, lookups, and rollups. Views with filtering and sorting. Trash with restore. Granular access control. |
+| 🔌  | **Automatic API**  | Every table gets its own API. Filter, sort, paginate, and track changes — no code needed.                                               |
+| 🔐  | **Authentication** | Email/password, magic link, two-factor, social login. Built-in roles (admin, member, viewer) and user management.                       |
+| 🖥️  | **Pages**          | Build pages from reusable sections. Define once, customize with variables. SEO-ready out of the box.                                    |
+| 🎨  | **Theming**        | Colors, fonts, spacing, shadows, animations, and responsive breakpoints — all defined in your config file.                              |
+| 🌐  | **Multi-language** | Built-in translation system with browser language detection and user preference memory.                                                 |
+| ⌨️  | **CLI**            | `sovrium start` to run your app. `sovrium build` to export a static site. Supports YAML, JSON, and TypeScript.                          |
 
-### Internationalization
+---
 
-Multi-language support built in.
+## 💡 Why Sovrium?
 
-- **Language configuration** -- define supported languages and default
-- **Translation tokens** -- `$t:` syntax for referencing translations in pages
-- **Browser detection** -- automatic language detection
-- **Persistence** -- remember user language preference
+Organizations pay **$10k+/month** for 20+ SaaS tools, with data scattered everywhere and zero control.
 
-### CLI
+Sovrium is **one self-hosted platform** that does what you need, configured in files you own.
 
-- `sovrium start` -- run the application from a config file
-- `sovrium build` -- generate a static site from config
-- Supports YAML, JSON, and TypeScript config files
+|                     |     Sovrium     |  SaaS Tools  |
+| ------------------- | :-------------: | :----------: |
+| **Data ownership**  |  Your servers   | Vendor cloud |
+| **Monthly cost**    | $0 (infra only) | $20-50/user  |
+| **Vendor lock-in**  |      None       |   Complete   |
+| **Customization**   |    Unlimited    |   Limited    |
+| **Version control** |   Git-native    |     None     |
 
 ---
 
-## Architecture
+## 📊 Status
 
-```
-Config File (YAML/JSON/TS)
-    |
-    v
-Effect Schema (validation)
-    |
-    v
-Sovrium Runtime
-    |
-    +---> PostgreSQL (tables, records, migrations)
-    +---> Hono (REST API + SSR)
-    +---> Better Auth (sessions, OAuth, 2FA)
-    +---> React + Tailwind (server-rendered UI)
-```
+Sovrium is under **active development**. The core feature set — tables, API, authentication, pages, theming, and i18n — is defined and tested across 272 user stories. Implementation is ongoing with automated pipelines.
 
-### Stack
-
-|                                           |                |
-| :---------------------------------------- | :------------- |
-| [Bun](https://bun.sh)                     | Runtime        |
-| [Hono](https://hono.dev)                  | Web framework  |
-| [Drizzle](https://orm.drizzle.team)       | Database ORM   |
-| [Effect](https://effect.website)          | Type-safe FP   |
-| [React 19](https://react.dev)             | UI (SSR)       |
-| [Tailwind CSS 4](https://tailwindcss.com) | Styling        |
-| [Better Auth](https://better-auth.com)    | Authentication |
-
-### Project Structure
-
-```
-src/
-  domain/          # Business logic, Effect Schema models
-    models/app/    # App configuration schema (tables, auth, pages, theme, ...)
-    models/api/    # API contracts (Zod schemas for OpenAPI)
-  application/     # Use cases, Effect programs
-  infrastructure/  # Database, auth, CSS compiler, email, logging
-  presentation/    # API routes, CLI, React components, styling
-specs/             # 2,200+ E2E tests (Playwright)
-docs/              # Architecture and infrastructure documentation
-```
+📋 [See the full roadmap →](SPEC-PROGRESS.md)
 
 ---
 
-## Status
+## 🤝 Contributing
 
-**Sovrium is under active development.**
+We welcome contributions of all kinds!
 
-The specification and testing phase is nearly complete: **2,270 out of 2,283 E2E tests are passing** across 225 spec files, covering 272 user stories with 2,394 acceptance criteria. A TDD automation pipeline handles test implementation, averaging 15+ specs fixed per day.
-
-| Domain     | Spec Files | Tests | Status |
-| ---------- | ---------: | ----: | ------ |
-| API        |         67 |   627 | 100%   |
-| App Schema |        131 | 1,398 | 99%    |
-| CLI        |          9 |   108 | 100%   |
-| Migrations |         17 |   139 | 100%   |
-| Templates  |          1 |    11 | 100%   |
+```bash
+git clone https://github.com/sovrium/sovrium
+cd sovrium && bun install
+bun run start
+```
 
-Track progress in detail: [SPEC-PROGRESS.md](SPEC-PROGRESS.md)
+📖 See [CLAUDE.md](CLAUDE.md) for coding standards and architecture details.
 
 ---
 
-## Development
+## 💬 Community & Support
 
-```bash
-bun install                   # Install dependencies
-bun run start                 # Run application
-bun run quality --skip-e2e    # Lint, format, typecheck, unit tests
-bun test:unit                 # Unit tests only
-bun test:e2e:regression       # E2E regression tests
-bun run progress              # Spec analysis and progress report
-```
+- [GitHub Issues](https://github.com/sovrium/sovrium/issues) — Bug reports and feature requests
+- [GitHub Discussions](https://github.com/sovrium/sovrium/discussions) — Questions, ideas, and general chat
+- [Vision](VISION.md) — Where Sovrium is headed
 
 ---
 
-## Contributing
+<details>
+<summary>🛠️ Built with</summary>
+<br />
 
-We welcome contributions! See [CLAUDE.md](CLAUDE.md) for coding standards and architecture details.
+[Bun](https://bun.sh) · [Hono](https://hono.dev) · [Drizzle ORM](https://orm.drizzle.team) · [Effect](https://effect.website) · [React 19](https://react.dev) · [Tailwind CSS 4](https://tailwindcss.com) · [Better Auth](https://better-auth.com)
 
-```bash
-git clone https://github.com/sovrium/sovrium
-cd sovrium && bun install
-```
+See [CLAUDE.md](CLAUDE.md) for the full architecture and project structure.
+
+</details>
 
 ---
 
-## License
+## 📄 License
 
-[BSL-1.1](LICENSE.md) -- Free for internal and non-commercial use. Becomes Apache 2.0 on January 1, 2029.
+[BSL-1.1](LICENSE.md) — Free for internal and non-commercial use. Automatically converts to **Apache 2.0** on January 1, 2029.
 
 ---
 
 <p align="center">
-  <sub><strong>Own your data. Own your tools. Own your future.</strong></sub>
+  <strong>Own your data. Own your tools. Own your future.</strong>
 </p>
 
 <p align="center">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sovrium",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "packageManager": "bun@1.3.10",
   "description": "Configuration-driven web application platform built with Bun, Effect, React, and Tailwind CSS",
   "module": "src/index.ts",
@@ -48,8 +48,6 @@
   ],
   "files": [
     "drizzle/**",
-    "schemas/**",
-    "!schemas/development/**",
     "src/**/*.ts",
     "src/**/*.tsx",
     "src/**/*.css",
@@ -137,6 +135,7 @@
     "globals": "^17.4.0",
     "knip": "^5.85.0",
     "otplib": "^13.3.0",
+    "pagefind": "^1.4.0",
     "pg": "^8.19.0",
     "playwright": "^1.58.2",
     "prettier-plugin-tailwindcss": "^0.7.2",
@@ -147,19 +146,20 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "@better-auth/drizzle-adapter": "^1.5.3",
     "@effect/experimental": "^0.58.0",
     "@hono/zod-openapi": "^1.2.2",
     "@hono/zod-validator": "^0.7.6",
     "@hookform/resolvers": "^5.2.2",
-    "@scalar/hono-api-reference": "^0.9.47",
+    "@scalar/hono-api-reference": "^0.9.48",
     "@tailwindcss/postcss": "^4.2.1",
     "@tanstack/react-query": "^5.90.21",
     "@tanstack/react-table": "^8.21.3",
-    "better-auth": "^1.5.2",
+    "better-auth": "^1.5.3",
     "dompurify": "^3.3.1",
     "drizzle-orm": "^0.45.1",
     "effect": "^3.19.19",
-    "hono": "^4.12.3",
+    "hono": "^4.12.4",
     "js-yaml": "^4.1.1",
     "lucide-react": "^0.575.0",
     "nanoid": "^5.1.6",

package/src/application/use-cases/server/static-content-generators.ts

@@ -17,18 +17,34 @@ export interface HreflangConfig {
   readonly defaultLanguage: string
 }
 
+/**
+ * Repair whitespace inside <pre> tags that Prettier's HTML formatter damages.
+ *
+ * Prettier adds a newline + indentation after the opening `>` of `<pre>` tags.
+ * Because `<pre>` renders whitespace literally (CSS `white-space: pre`), this
+ * introduces a visible blank first line in code blocks.
+ *
+ * This function strips the newline and any spaces immediately after `<pre ...>`.
+ */
+const repairPreWhitespace = (html: string): string => html.replace(/(<pre[^>]*>)\n[ ]*/g, '$1')
+
 /**
  * Format HTML with Prettier for professional formatting
- * Loads Prettier config and formats HTML using the HTML parser
+ * Loads Prettier config and formats HTML using the HTML parser.
+ *
+ * After formatting, repairs `<pre>` whitespace that Prettier damages
+ * (leading newline + indentation, trailing whitespace).
  */
 export const formatHtmlWithPrettier = async (html: string): Promise<string> => {
   const prettier = await import('prettier')
   const config = await prettier.resolveConfig(process.cwd())
 
-  return await prettier.format(html, {
+  const formatted = await prettier.format(html, {
     ...config,
     parser: 'html',
   })
+
+  return repairPreWhitespace(formatted)
 }
 
 /**

package/src/domain/models/api/activity.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 { z } from 'zod'
+
+// ============================================================================
+// Activity Log Schemas
+// ============================================================================
+
+/**
+ * Activity log user reference schema
+ */
+export const activityLogUserSchema = z.object({
+  id: z.string().describe('User identifier'),
+  name: z.string().describe('User display name'),
+  email: z.string().describe('User email address'),
+})
+
+/**
+ * Activity log entry schema (list view)
+ */
+export const activityLogSchema = z.object({
+  id: z.string().describe('Activity log identifier'),
+  createdAt: z.string().describe('ISO 8601 timestamp of the activity'),
+  userId: z.string().optional().describe('User who performed the action'),
+  action: z.enum(['create', 'update', 'delete', 'restore']).describe('Action type'),
+  tableName: z.string().describe('Name of the affected table'),
+  recordId: z.union([z.string(), z.number()]).describe('ID of the affected record'),
+  user: activityLogUserSchema.nullable().describe('User details (null for system activities)'),
+})
+
+/**
+ * Activity log detail schema (single view, includes changes)
+ */
+export const activityLogDetailSchema = activityLogSchema.extend({
+  changes: z
+    .record(z.string(), z.unknown())
+    .nullable()
+    .describe('Field changes (null for delete actions)'),
+})
+
+/**
+ * Activity log pagination schema
+ */
+export const activityPaginationSchema = z.object({
+  total: z.number().int().describe('Total count of activities'),
+  page: z.number().int().describe('Current page number'),
+  pageSize: z.number().int().describe('Items per page'),
+  totalPages: z.number().int().describe('Total number of pages'),
+})
+
+// ============================================================================
+// Activity Log Response Schemas
+// ============================================================================
+
+/**
+ * List activity logs response schema
+ *
+ * GET /api/activity
+ */
+export const listActivityLogsResponseSchema = z.object({
+  activities: z.array(activityLogSchema).describe('List of activity log entries'),
+  pagination: activityPaginationSchema.describe('Pagination metadata'),
+})
+
+/**
+ * Get activity log detail response schema
+ *
+ * GET /api/activity/:activityId
+ */
+export const getActivityLogResponseSchema = activityLogDetailSchema.describe(
+  'Single activity log entry with change details'
+)
+
+// ============================================================================
+// TypeScript Types
+// ============================================================================
+
+export type ActivityLogUser = z.infer<typeof activityLogUserSchema>
+export type ActivityLog = z.infer<typeof activityLogSchema>
+export type ActivityLogDetail = z.infer<typeof activityLogDetailSchema>
+export type ListActivityLogsResponse = z.infer<typeof listActivityLogsResponseSchema>
+export type GetActivityLogResponse = z.infer<typeof getActivityLogResponseSchema>

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

@@ -0,0 +1,131 @@
+/**
+ * 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'
+
+// ============================================================================
+// Comment Schemas
+// ============================================================================
+
+/**
+ * Comment user metadata schema
+ */
+export const commentUserSchema = z.object({
+  id: z.string().describe('User identifier'),
+  name: z.string().describe('User display name'),
+  email: z.string().describe('User email address'),
+  image: z.string().nullable().optional().describe('User avatar URL'),
+})
+
+/**
+ * Comment response schema
+ */
+export const commentSchema = z.object({
+  id: z.string().describe('Comment identifier'),
+  content: z.string().describe('Comment content'),
+  userId: z.string().describe('Author user ID'),
+  recordId: z.union([z.string(), z.number()]).describe('Parent record ID'),
+  tableId: z.union([z.string(), z.number()]).describe('Parent table ID'),
+  createdAt: z.string().describe('ISO 8601 creation timestamp'),
+  updatedAt: z.string().describe('ISO 8601 last update timestamp'),
+  user: commentUserSchema.describe('Comment author details'),
+})
+
+/**
+ * Comment pagination schema
+ */
+export const commentPaginationSchema = z.object({
+  total: z.number().int().describe('Total count of comments'),
+  limit: z.number().int().describe('Items returned'),
+  offset: z.number().int().describe('Items skipped'),
+  hasMore: z.boolean().describe('Whether more results exist'),
+})
+
+/**
+ * List comments response schema
+ *
+ * GET /api/tables/:tableId/records/:recordId/comments
+ */
+export const listCommentsResponseSchema = z.object({
+  comments: z.array(commentSchema).describe('List of comments'),
+  pagination: commentPaginationSchema.describe('Pagination metadata'),
+})
+
+/**
+ * Get single comment response schema
+ *
+ * GET /api/tables/:tableId/records/:recordId/comments/:commentId
+ */
+export const getCommentResponseSchema = commentSchema.describe('Single comment details')
+
+/**
+ * Create comment response schema
+ *
+ * POST /api/tables/:tableId/records/:recordId/comments
+ */
+export const createCommentResponseSchema = z.object({
+  comment: commentSchema.describe('Created comment'),
+})
+
+/**
+ * Update comment response schema
+ *
+ * PATCH /api/tables/:tableId/records/:recordId/comments/:commentId
+ */
+export const updateCommentResponseSchema = commentSchema.describe('Updated comment details')
+
+// ============================================================================
+// Record History Schemas
+// ============================================================================
+
+/**
+ * Record history entry schema
+ */
+export const recordHistoryEntrySchema = z.object({
+  id: z.string().describe('Activity log identifier'),
+  userId: z.string().optional().describe('User who performed the action'),
+  action: z.enum(['create', 'update', 'delete', 'restore']).describe('Action type'),
+  tableName: z.string().describe('Name of the affected table'),
+  recordId: z.union([z.string(), z.number()]).describe('ID of the affected record'),
+  changes: z
+    .record(z.string(), z.unknown())
+    .nullable()
+    .describe('Field changes (null for delete/restore)'),
+  createdAt: z.string().describe('ISO 8601 timestamp'),
+  user: z
+    .object({
+      id: z.string().describe('User identifier'),
+      name: z.string().describe('User display name'),
+      email: z.string().describe('User email address'),
+    })
+    .nullable()
+    .describe('User details (null for system activities)'),
+})
+
+/**
+ * Get record history response schema
+ *
+ * GET /api/tables/:tableId/records/:recordId/history
+ */
+export const getRecordHistoryResponseSchema = z.object({
+  history: z.array(recordHistoryEntrySchema).describe('List of history entries'),
+  pagination: z
+    .object({
+      total: z.number().int().describe('Total activity count'),
+      limit: z.number().int().describe('Items returned'),
+      offset: z.number().int().describe('Items skipped'),
+    })
+    .optional()
+    .describe('Pagination metadata'),
+})
+
+// ============================================================================
+// TypeScript Types
+// ============================================================================
+
+export type Comment = z.infer<typeof commentSchema>
+export type RecordHistoryEntry = z.infer<typeof recordHistoryEntrySchema>

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

@@ -20,6 +20,9 @@
  * - request: Request input validation
  */
 
+// Activity log schemas
+export * from './activity'
+
 // Analytics schemas
 export * from './analytics'
 
@@ -35,8 +38,14 @@ export * from './health'
 // Authentication schemas
 export * from './auth'
 
+// Comment and history schemas
+export * from './comments'
+
 // Table and record schemas
 export * from './tables'
 
+// OpenAPI parameter schemas
+export * from './params'
+
 // Request schemas (input validation)
 export * from './request'