@facetlayer/prism-framework 0.4.0 → 0.4.1

package/docs/launch-configuration.md

@@ -0,0 +1,223 @@
+---
+name: launch-configuration
+description: How to configure Prism Framework for different execution contexts
+---
+
+# Launch Configuration
+
+The launch configuration system is a crucial feature that allows the same code to work in both backend (Express.js) and desktop (Electron) contexts.
+
+## Why Launch Configuration?
+
+Different execution contexts need different configurations:
+- **Backend server**: Database files on disk, specific logging configuration
+- **Electron desktop app**: Database files in user data directory, different SQLite loader
+
+The `setLaunchConfig()` function centralizes this configuration and must be called **before** any services access databases or logging.
+
+## Basic Setup
+
+```typescript
+import { setLaunchConfig } from '@facetlayer/prism-framework';
+
+setLaunchConfig({
+  logging: {
+    databaseFilename: '/path/to/logs.db',
+    enableConsoleLogging: true,
+    loadDatabase: await loadBetterSqlite(),
+  },
+  database: {
+    user: {
+      migrationBehavior: 'safe-upgrades',
+      databasePath: '/path/to/databases',
+      services: ALL_SERVICES,
+      loadDatabase: await loadBetterSqlite(),
+    },
+  },
+});
+```
+
+## Configuration Structure
+
+### Logging Configuration
+
+```typescript
+interface LoggingSettings {
+  databaseFilename: string;        // Path to logging database
+  enableConsoleLogging: boolean;   // Also log to console
+  loadDatabase: LoadDatabaseFn;    // Database loader function
+}
+```
+
+### Database Configuration
+
+```typescript
+interface DatabaseInitializationOptions {
+  migrationBehavior: MigrationBehavior;  // How to handle schema changes
+  databasePath: string;                  // Directory for database files
+  services: ServiceDefinition[];         // Services to include schemas from
+  loadDatabase: LoadDatabaseFn;          // Database loader function
+}
+```
+
+### Migration Behavior
+
+```typescript
+type MigrationBehavior =
+  | 'safe-upgrades'      // Only allow adding columns/tables
+  | 'rebuild'            // Drop and recreate on mismatch
+  | 'error-on-mismatch'; // Throw error on schema mismatch
+```
+
+## Backend Server Example
+
+```typescript
+// main.ts (backend server)
+import { setLaunchConfig, startServer, App } from '@facetlayer/prism-framework';
+import { loadBetterSqlite } from '@facetlayer/sqlite-wrapper';
+import path from 'path';
+import fs from 'fs';
+
+async function main() {
+  const databasePath = process.env.SQLITE_DATABASE_PATH || './databases';
+
+  // Ensure directory exists
+  if (!fs.existsSync(databasePath)) {
+    fs.mkdirSync(databasePath, { recursive: true });
+  }
+
+  // Configure for backend
+  setLaunchConfig({
+    logging: {
+      databaseFilename: path.join(databasePath, 'logs.db'),
+      enableConsoleLogging: true,
+      loadDatabase: await loadBetterSqlite(),
+    },
+    database: {
+      user: {
+        migrationBehavior: 'safe-upgrades',
+        databasePath,
+        services: ALL_SERVICES,
+        loadDatabase: await loadBetterSqlite(),
+      },
+    },
+  });
+
+  // Start server (see server-setup doc for full startServer options)
+  const app = new App({ services: ALL_SERVICES });
+  await startServer({ app, port: parseInt(process.env.PRISM_API_PORT!, 10) });
+}
+
+main().catch(console.error);
+```
+
+## Electron Desktop App Example
+
+```typescript
+// main.ts (Electron main process)
+import { app } from 'electron';
+import { setLaunchConfig } from '@facetlayer/prism-framework';
+import { getSqliteLoader } from './database-helper';
+import path from 'path';
+
+async function initializeApp() {
+  await app.whenReady();
+
+  const userDataPath = app.getPath('userData');
+  const databasePath = path.join(userDataPath, 'databases');
+
+  // Get Electron-compatible SQLite loader
+  const loadDatabase = await getSqliteLoader();
+
+  // Configure for Electron
+  setLaunchConfig({
+    logging: {
+      databaseFilename: path.join(databasePath, 'logs.db'),
+      enableConsoleLogging: true,
+      loadDatabase,
+    },
+    database: {
+      'desktop-app': {
+        migrationBehavior: 'safe-upgrades',
+        databasePath,
+        services: ALL_SERVICES,
+        loadDatabase,
+      },
+    },
+  });
+
+  // Continue with Electron app initialization...
+}
+```
+
+## Accessing Configuration
+
+Services and framework code can access the configuration:
+
+```typescript
+import {
+  getLaunchConfig,
+  getDatabaseConfig,
+  getLoggingConfig
+} from '@facetlayer/prism-framework';
+
+// Get full config
+const config = getLaunchConfig();
+
+// Get database config for a specific database
+const userDbConfig = getDatabaseConfig('user');
+
+// Get logging config
+const loggingConfig = getLoggingConfig();
+```
+
+## Multiple Databases
+
+You can configure multiple databases:
+
+```typescript
+setLaunchConfig({
+  logging: { /* ... */ },
+  database: {
+    user: {
+      migrationBehavior: 'safe-upgrades',
+      databasePath: '/path/to/databases',
+      services: ALL_SERVICES.filter(s => s.databases?.user),
+      loadDatabase: await loadBetterSqlite(),
+    },
+    project: {
+      migrationBehavior: 'safe-upgrades',
+      databasePath: '/path/to/databases',
+      services: ALL_SERVICES.filter(s => s.databases?.project),
+      loadDatabase: await loadBetterSqlite(),
+    },
+    'desktop-app': {
+      migrationBehavior: 'rebuild',
+      databasePath: '/path/to/databases',
+      services: ALL_SERVICES.filter(s => s.databases?.['desktop-app']),
+      loadDatabase: await loadBetterSqlite(),
+    },
+  },
+});
+```
+
+## Database Statements Collection
+
+The framework automatically collects SQL statements from all services:
+
+```typescript
+import { getStatementsForDatabase } from '@facetlayer/prism-framework';
+
+const statements = getStatementsForDatabase('user', ALL_SERVICES);
+// Returns all SQL statements from services that define databases.user
+```
+
+This is used internally when initializing databases with `@facetlayer/sqlite-wrapper`.
+
+## Best Practices
+
+1. **Call setLaunchConfig early** - Before any database or logging operations
+2. **Call it only once** - The function throws if called multiple times
+3. **Use environment variables** - Make paths configurable
+4. **Ensure directories exist** - Create database directories before setting config
+5. **Use appropriate migration behavior** - `safe-upgrades` for production, `rebuild` for development

package/docs/overview.md

@@ -0,0 +1,62 @@
+---
+name: overview
+description: Introduction to Prism Framework and its core concepts
+---
+
+# Prism Framework Overview
+
+Prism Framework is a TypeScript framework for building web-based SaaS applications and desktop Electron apps. It provides a unified approach to creating applications that can run in both backend (Express.js) and desktop (Electron) contexts.
+
+## Key Features
+
+1. **Service-Based Architecture** - Organize your application into self-contained services
+2. **Type-Safe Endpoints** - Define endpoints with Zod schemas for request/response validation
+3. **Launch Configuration** - Single configuration system that works for both web and desktop
+4. **Database Management** - Integration with `@facetlayer/sqlite-wrapper` for database operations
+5. **Request Context** - AsyncLocalStorage-based request context tracking
+6. **Authorization** - Built-in authorization system with resources and auth sources
+7. **Metrics** - Prometheus metrics integration
+8. **SSE Support** - Server-Sent Events for real-time communication
+9. **Error Handling** - Comprehensive HTTP error classes
+
+## Core Concepts
+
+### Services
+
+A service is a self-contained module that can include API endpoints, middleware, database schemas, and background jobs. Services are the building blocks of a Prism application.
+
+See the `creating-services` doc for the full `ServiceDefinition` interface and examples.
+
+### Launch Configuration
+
+The launch configuration system allows the same code to work in different contexts (backend server, Electron desktop app). Call `setLaunchConfig()` early in your app to configure logging and database settings.
+
+See the `launch-configuration` doc for setup details and examples.
+
+### Request Context
+
+Every request has an associated context (via AsyncLocalStorage) that flows through all async operations. Access it with `getCurrentRequestContext()` to get request ID, auth info, and more.
+
+See the `authorization` doc for how auth integrates with request context.
+
+### Error Handling
+
+The framework provides built-in HTTP error classes (`BadRequestError`, `NotFoundError`, `ForbiddenError`, etc.) that automatically map to the correct status codes.
+
+See the `error-handling` doc for available error classes and usage patterns.
+
+## Project Structure
+
+See the `source-directory-organization` doc for the recommended directory layout and conventions.
+
+## Getting Started
+
+1. Install the framework (requires **Zod v4** — Zod v3 is not compatible):
+```bash
+pnpm add @facetlayer/prism-framework zod@^4
+```
+
+2. Set up environment variables (see `env-files` doc)
+3. Create your first service (see `creating-services` doc)
+4. Set up the launch configuration (see `launch-configuration` doc)
+5. Start the server (see `server-setup` doc)

package/docs/server-setup.md

@@ -0,0 +1,144 @@
+---
+name: server-setup
+description: How to set up and start an Express.js server using Prism Framework
+---
+
+# Server Setup
+
+This guide explains how to set up and start an Express.js server using Prism Framework.
+
+## Quick Outline
+
+Brief summary of the steps to setup a Prism server:
+
+ - Use the `@facetlayer/prism-framework` library
+ - Create an instance of `App` and use `startServer`
+ - API endpoints are automatically mounted at `/api/`
+ - Optionally serve web files (HTML/JS/CSS) from the same server
+ - Use the env var `PRISM_API_PORT` as the service port.
+
+## Server Setup Example
+
+### API-only server
+
+```typescript
+import { App, startServer } from '@facetlayer/prism-framework';
+
+const app = new App({ services: ALL_SERVICES });
+
+await startServer({
+  app,
+  port: parseInt(process.env.PRISM_API_PORT || '4000', 10),
+  openapiConfig: {
+    enable: true,
+    enableSwagger: true,
+  },
+});
+```
+
+All endpoints are mounted under `/api/`. For example, an endpoint defined with
+`path: '/users'` is accessible at `GET /api/users`.
+
+### Unified server with web files
+
+To serve both API and web pages from a single process on one port, add the
+`web` config option:
+
+```typescript
+import { App, startServer } from '@facetlayer/prism-framework';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const app = new App({ services: ALL_SERVICES });
+
+await startServer({
+  app,
+  port: parseInt(process.env.PRISM_API_PORT || '4000', 10),
+  openapiConfig: {
+    enable: true,
+    enableSwagger: true,
+  },
+  web: {
+    dir: join(__dirname, '..', 'web'),
+  },
+});
+```
+
+When `web` is configured:
+ - API endpoints are served under `/api/` (e.g. `/api/users`, `/api/health`)
+ - Web files are served from the specified directory at the root path (`/`)
+ - In development: uses Vite dev server middleware if `vite` is installed (for HMR)
+ - In production: serves static files from `web/dist/` (or `web/` if no dist folder)
+ - SPA fallback: unmatched GET requests serve `index.html`
+
+### Available framework endpoints
+
+These are automatically available under `/api/`:
+
+| Path | Description |
+|------|-------------|
+| `/api/health` | Health check (localhost only) |
+| `/api/metrics` | Prometheus metrics (localhost only) |
+| `/api/endpoints` | HTML endpoint listing |
+| `/api/endpoints.json` | JSON endpoint listing |
+| `/api/openapi.json` | OpenAPI schema (if enabled) |
+| `/api/swagger` | Swagger UI (if enabled) |
+
+## Launching with Candle
+
+Use the `candle` process manager to run the server:
+
+### Setup
+
+Register the service in your `.candle.json`:
+
+```json
+{
+  "services": [
+    {
+      "name": "my-app",
+      "shell": "node src/main.ts"
+    }
+  ]
+}
+```
+
+### Usage
+
+```bash
+# Start the service
+candle start my-app
+
+# Check status
+candle ls
+
+# View logs
+candle logs my-app
+
+# Restart after changes
+candle restart my-app
+```
+
+### Recommended .env setup
+
+```bash
+PRISM_API_PORT=4000
+```
+
+## Vite Integration
+
+To use Vite for frontend development with HMR:
+
+1. Install `vite` as a dependency in your project
+2. Place your web files in a `web/` directory with an `index.html`
+3. Pass `web: { dir: './web' }` to `startServer`
+
+In development mode, Vite's dev server middleware handles all non-API requests,
+providing hot module replacement. In production, the built static files from
+`web/dist/` are served.
+
+## Testing
+
+Run `prism list-endpoints` to check that the local server is running and the endpoint listing is working.

package/docs/source-directory-organization.md

@@ -0,0 +1,115 @@
+---
+name: source-directory-organization
+description: Recommended directory structure for organizing Prism API source code
+---
+
+# Source Directory Organization
+
+This document describes the recommended directory structure for organizing your Prism API source code. Following this pattern ensures consistency across projects and makes navigation intuitive.
+
+## Directory Structure
+
+```
+src/
+├── _main/              # Main application bootstrap
+│   ├── api.ts          # Entry point - starts the server
+│   └── services.ts     # Exports ALL_SERVICES array
+├── <service-name>/     # One folder per service
+│   ├── index.ts        # Service definition export
+│   └── ...             # Additional service files
+├── <service-name>/
+│   └── index.ts
+└── <shared-resource>/  # Shared resources (databases, utils)
+    └── ...
+```
+
+## Key Principles
+
+### 1. The `_main` Folder
+
+The `_main` folder contains the application entry point and service aggregation. The underscore prefix ensures it sorts to the top of the directory listing.
+
+**`_main/api.ts`** - The main entry point. Loads environment variables, creates the App, and starts the server. See the `server-setup` doc for full `startServer` examples and the `env-files` doc for environment configuration.
+
+**`_main/services.ts`** - Aggregates all services:
+
+```typescript
+import { type ServiceDefinition } from '@facetlayer/prism-framework';
+import { definition as usersDefinition } from '../users/index.ts';
+import { definition as projectsDefinition } from '../projects/index.ts';
+
+export const ALL_SERVICES: ServiceDefinition[] = [
+  usersDefinition,
+  projectsDefinition,
+];
+```
+
+### 2. Service Folders
+
+Each service lives in its own top-level folder named after the service. The folder contains an `index.ts` that exports the service definition.
+
+**Example: `users/index.ts`**
+
+```typescript
+import { createEndpoint, type ServiceDefinition } from '@facetlayer/prism-framework';
+import { z } from 'zod';
+
+const getUserEndpoint = createEndpoint({
+  method: 'GET',
+  path: '/api/users/:id',
+  requestSchema: z.object({ id: z.string() }),
+  responseSchema: z.object({ id: z.string(), email: z.string() }),
+  handler: async (input) => {
+    // Implementation
+  },
+});
+
+export const definition: ServiceDefinition = {
+  name: 'users',
+  endpoints: [getUserEndpoint],
+};
+```
+
+### 3. No `services` Directory
+
+Services should NOT be placed in a `services/` subdirectory. Each service folder exists at the top level of `src/`:
+
+**Correct:**
+```
+src/
+├── _main/
+├── users/
+├── projects/
+└── billing/
+```
+
+**Incorrect:**
+```
+src/
+├── index.ts
+└── services/
+    ├── users.ts
+    ├── projects.ts
+    └── billing.ts
+```
+
+### 4. Shared Resources
+
+Non-service folders (databases, utilities) can also exist at the top level:
+
+```
+src/
+├── _main/
+├── users/
+├── projects/
+└── user-database/      # Shared database module
+    └── db.ts
+```
+
+## Benefits
+
+1. **Discoverability** - The `_main` folder clearly identifies the entry point
+2. **Modularity** - Each service is self-contained in its own folder
+3. **Scalability** - Adding services means adding folders, not modifying existing structure
+4. **Consistency** - All projects follow the same pattern
+5. **Clarity** - The `ALL_SERVICES` array provides a single source of truth for what services exist