@archlast/server 0.0.1 → 0.1.1

package/README.md

@@ -1,32 +1,959 @@
 # @archlast/server
 
-Archlast server library exports (schema, functions, types) plus Docker
-runtime metadata and templates.
+Type-safe server definitions and runtime helpers for Archlast. This package provides schema definition with validators, function definitions (query, mutation, action, http, webhook, rpc), background job scheduling, and shared types. The runtime server is delivered via Docker image.
 
-## Install
+## Table of Contents
+
+- [Installation](#installation)
+- [Library vs Runtime](#library-vs-runtime)
+- [Schema Definition](#schema-definition)
+  - [Field Types (Validators)](#field-types-validators)
+  - [Field Modifiers](#field-modifiers)
+  - [Relationships](#relationships)
+  - [Indexes](#indexes)
+- [Function Definitions](#function-definitions)
+  - [Query](#query)
+  - [Mutation](#mutation)
+  - [Action](#action)
+  - [HTTP Routes](#http-routes)
+  - [Webhooks](#webhooks)
+  - [RPC (tRPC-style)](#rpc-trpc-style)
+- [Context Objects](#context-objects)
+- [Authentication & Permissions](#authentication--permissions)
+- [Background Jobs](#background-jobs)
+- [Storage Types](#storage-types)
+- [Subpath Exports](#subpath-exports)
+- [Environment Variables](#environment-variables)
+- [Docker Templates](#docker-templates)
+
+## Installation
+
+```bash
+npm install -D @archlast/server
+
+# Or with other package managers
+pnpm add -D @archlast/server
+yarn add -D @archlast/server
+bun add -D @archlast/server
+```
+
+## Library vs Runtime
+
+This package is a **dev-time library** for schema and function definitions. The actual server runtime is delivered via Docker and managed by the CLI:
 
 ```bash
-npm install @archlast/server --save-dev
+# Use the CLI to run the server
+archlast start
+
+# The Docker image contains the full runtime
+docker pull archlast/server:latest
 ```
 
-## Library usage
+---
+
+## Schema Definition
+
+Define your data model in `src/schema.ts`:
 
 ```ts
 import { defineSchema, defineTable, v } from "@archlast/server/schema/definition";
 
 export default defineSchema({
   tasks: defineTable({
-    id: v.id(),
+    _id: v.id().primaryKey(),
     text: v.string(),
+    completed: v.boolean().default(false),
+    priority: v.string().default("medium"),
+    createdAt: v.number().createdNow(),
+    updatedAt: v.number().updateNow().optional(),
+  }),
+
+  users: defineTable({
+    _id: v.id().primaryKey(),
+    email: v.string().unique(),
+    name: v.string(),
+    role: v.string().default("user"),
+  }),
+});
+```
+
+### Field Types (Validators)
+
+The `v` object provides all available field types:
+
+| Validator | TypeScript Type | Description |
+|-----------|-----------------|-------------|
+| `v.id()` | `string` | CUID2 identifier (auto-generated) |
+| `v.uuid()` | `string` | UUID v4 identifier |
+| `v.objectId()` | `string` | MongoDB-style ObjectId |
+| `v.string()` | `string` | Text field |
+| `v.number()` | `number` | Numeric field (integer or float) |
+| `v.boolean()` | `boolean` | True/false field |
+| `v.date()` | `Date` | Date object |
+| `v.datetime()` | `Date` | Date with time |
+| `v.bytes()` | `Uint8Array` | Binary data |
+| `v.json()` | `unknown` | Arbitrary JSON |
+| `v.any()` | `any` | Any type (use sparingly) |
+| `v.object(shape)` | `object` | Nested object with schema |
+| `v.array(schema)` | `T[]` | Array of items |
+| `v.optional(type)` | `T \| undefined` | Optional wrapper |
+
+### Examples
+
+```ts
+import { v } from "@archlast/server/schema/validators";
+
+// Basic types
+v.string()              // string
+v.number()              // number
+v.boolean()             // boolean
+
+// IDs
+v.id()                  // CUID2: "clxxxx..."
+v.uuid()                // UUID: "550e8400-e29b-41d4-a716-446655440000"
+v.objectId()            // ObjectId: "507f1f77bcf86cd799439011"
+
+// Dates
+v.date()                // Date object (date only)
+v.datetime()            // Date object (with time)
+
+// Complex types
+v.json()                // Any JSON-serializable value
+v.bytes()               // Binary data as Uint8Array
+
+// Nested object
+v.object({
+  street: v.string(),
+  city: v.string(),
+  zip: v.string(),
+})
+
+// Array
+v.array(v.string())           // string[]
+v.array(v.object({            // Array of objects
+  name: v.string(),
+  score: v.number(),
+}))
+```
+
+### Field Modifiers
+
+Chain modifiers to add constraints and behaviors:
+
+| Modifier | Description |
+|----------|-------------|
+| `.primaryKey()` | Mark as primary key (auto-generates if not provided) |
+| `.unique()` | Unique constraint |
+| `.index()` | Create index for faster queries |
+| `.searchable()` | Enable full-text search |
+| `.optional()` | Make field nullable (TypeScript: `T \| undefined`) |
+| `.default(value)` | Default value on insert |
+| `.createdNow()` | Auto-set to `Date.now()` on insert |
+| `.updateNow()` | Auto-set to `Date.now()` on every update |
+| `.foreignKey(table, field, options)` | Foreign key reference |
+
+### Examples
+
+```ts
+defineTable({
+  // Primary key with auto-generation
+  _id: v.id().primaryKey(),
+
+  // Unique constraint
+  email: v.string().unique(),
+
+  // Indexed for fast lookups
+  slug: v.string().index(),
+
+  // Full-text searchable
+  content: v.string().searchable(),
+
+  // Optional field
+  bio: v.string().optional(),
+
+  // Default values
+  role: v.string().default("user"),
+  count: v.number().default(0),
+  active: v.boolean().default(true),
+
+  // Automatic timestamps
+  createdAt: v.number().createdNow(),
+  updatedAt: v.number().updateNow().optional(),
+
+  // Foreign key
+  authorId: v.id().foreignKey("users", "_id", {
+    onDelete: "cascade",
+    onUpdate: "cascade",
+  }),
+})
+```
+
+### Relationships
+
+Define relationships in the second argument of `defineTable`:
+
+```ts
+import {
+  defineTable,
+  hasOne,
+  hasMany,
+  belongsTo,
+  manyToMany
+} from "@archlast/server/schema/definition";
+
+export default defineSchema({
+  users: defineTable(
+    {
+      _id: v.id().primaryKey(),
+      name: v.string(),
+    },
+    {
+      relationships: {
+        // User has many tasks
+        tasks: hasMany("tasks", "authorId"),
+
+        // User has one profile
+        profile: hasOne("profiles", "userId"),
+      },
+    }
+  ),
+
+  tasks: defineTable(
+    {
+      _id: v.id().primaryKey(),
+      text: v.string(),
+      authorId: v.id(),
+    },
+    {
+      relationships: {
+        // Task belongs to user
+        author: belongsTo("users", "authorId"),
+
+        // Task has many subtasks
+        subtasks: hasMany("subtasks", "taskId"),
+      },
+    }
+  ),
+
+  tags: defineTable(
+    {
+      _id: v.id().primaryKey(),
+      name: v.string(),
+    },
+    {
+      relationships: {
+        // Many-to-many through junction table
+        tasks: manyToMany("tasks", "task_tags", "tagId", "taskId"),
+      },
+    }
+  ),
+});
+```
+
+### Indexes
+
+Create composite indexes for complex queries:
+
+```ts
+defineTable(
+  {
+    _id: v.id().primaryKey(),
+    completed: v.boolean(),
+    priority: v.string(),
+    createdAt: v.number(),
+  },
+  {
+    indexes: [
+      // Composite index
+      { fields: ["completed", "createdAt"], name: "idx_tasks_status" },
+
+      // Single field index
+      { fields: ["priority"], name: "idx_tasks_priority" },
+    ],
+  }
+)
+```
+
+---
+
+## Function Definitions
+
+Functions are the API of your Archlast application. Import from `@archlast/server/functions/definition`.
+
+### Query
+
+Read-only operations. Results are cached and reactive.
+
+```ts
+import { query } from "@archlast/server/functions/definition";
+
+// Simple query
+export const list = query(async (ctx) => {
+  return ctx.db.query("tasks").findMany();
+});
+
+// Query with arguments
+export const get = query({
+  args: { id: v.string().zodSchema },
+  handler: async (ctx, args) => {
+    return ctx.db.get("tasks", args.id);
+  },
+});
+
+// Query with filtering
+export const listByStatus = query({
+  args: {
+    completed: v.boolean().zodSchema,
+    limit: v.number().optional().zodSchema,
+  },
+  handler: async (ctx, args) => {
+    return ctx.db
+      .query("tasks")
+      .where({ completed: args.completed })
+      .take(args.limit ?? 10)
+      .findMany();
+  },
+});
+```
+
+### Mutation
+
+Write operations. Automatically invalidate related caches.
+
+```ts
+import { mutation } from "@archlast/server/functions/definition";
+
+export const create = mutation({
+  args: {
+    text: v.string().zodSchema,
+    priority: v.string().optional().zodSchema,
+  },
+  handler: async (ctx, args) => {
+    return ctx.db.insert("tasks", {
+      text: args.text,
+      priority: args.priority ?? "medium",
+      completed: false,
+    });
+  },
+});
+
+export const update = mutation({
+  args: {
+    id: v.string().zodSchema,
+    text: v.string().optional().zodSchema,
+    completed: v.boolean().optional().zodSchema,
+  },
+  handler: async (ctx, args) => {
+    const { id, ...data } = args;
+    return ctx.db.update("tasks", id, data);
+  },
+});
+
+export const remove = mutation({
+  args: { id: v.string().zodSchema },
+  handler: async (ctx, args) => {
+    await ctx.db.delete("tasks", args.id);
+    return { success: true };
+  },
+});
+```
+
+### Action
+
+Long-running operations, side effects, external API calls.
+
+```ts
+import { action } from "@archlast/server/functions/definition";
+
+export const sendEmail = action({
+  args: {
+    to: v.string().zodSchema,
+    subject: v.string().zodSchema,
+    body: v.string().zodSchema,
+  },
+  handler: async (ctx, args) => {
+    // Call external email service
+    const response = await fetch("https://api.sendgrid.com/v3/mail/send", {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${process.env.SENDGRID_API_KEY}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        personalizations: [{ to: [{ email: args.to }] }],
+        from: { email: "noreply@myapp.com" },
+        subject: args.subject,
+        content: [{ type: "text/plain", value: args.body }],
+      }),
+    });
+
+    return { sent: response.ok };
+  },
+});
+
+export const processImage = action({
+  args: { storageId: v.string().zodSchema },
+  handler: async (ctx, args) => {
+    const file = await ctx.storage.get(args.storageId);
+    // Process image...
+    const processedId = await ctx.storage.store("processed", processedBuffer);
+    return { processedId };
+  },
+});
+```
+
+### HTTP Routes
+
+Explicit HTTP endpoints with full control over request/response.
+
+```ts
+import { http } from "@archlast/server/http/definition";
+
+// GET route
+export const health = http.get({
+  path: "/health",
+  handler: async (ctx) => {
+    return new Response("ok", { status: 200 });
+  },
+});
+
+// POST route with body parsing
+export const createWebhook = http.post({
+  path: "/api/webhooks",
+  handler: async (ctx) => {
+    const body = await ctx.req.json();
+    // Process webhook...
+    return Response.json({ received: true });
+  },
+});
+
+// Route with path parameters
+export const getUser = http.get({
+  path: "/api/users/:id",
+  handler: async (ctx) => {
+    const userId = ctx.req.params.id;
+    const user = await ctx.server.db.get("users", userId);
+    if (!user) {
+      return new Response("Not found", { status: 404 });
+    }
+    return Response.json(user);
+  },
+});
+
+// Other methods
+export const updateResource = http.put({
+  path: "/api/resource/:id",
+  handler: async (ctx) => {
+    const id = ctx.req.params.id;
+    const data = await ctx.req.json();
+    // Update resource...
+    return Response.json({ success: true });
+  },
+});
+
+export const patchResource = http.patch({
+  path: "/api/resource/:id",
+  handler: async (ctx) => { /* ... */ return Response.json({ success: true }); },
+});
+
+export const deleteResource = http.delete({
+  path: "/api/resource/:id",
+  handler: async (ctx) => { /* ... */ return new Response(null, { status: 204 }); },
+});
+
+export const optionsResource = http.options({
+  path: "/api/resource",
+  handler: async (ctx) => { return new Response(null, { status: 204 }); },
+});
+```
+
+### Webhooks
+
+Webhook handlers with custom security guards.
+
+```ts
+import { webhook } from "@archlast/server/webhook/definition";
+import { createSignatureGuard } from "@archlast/server/webhook/guard";
+
+// Stripe webhook with signature verification
+export const stripeWebhook = webhook({
+  path: "/webhooks/stripe",
+  method: "POST",
+  guards: [
+    createSignatureGuard({
+      secret: process.env.STRIPE_WEBHOOK_SECRET!,
+      header: "stripe-signature",
+      algorithm: "sha256",
+    }),
+  ],
+  handler: async (ctx, event) => {
+    switch (event.type) {
+      case "checkout.session.completed":
+        await ctx.db.insert("orders", { userId: event.data.customer });
+        break;
+      case "customer.subscription.deleted":
+        await ctx.db.update("users", event.data.customer, { subscribed: false });
+        break;
+    }
+    return { received: true };
+  },
+});
+
+// GitHub webhook with signature verification
+export const githubWebhook = webhook({
+  path: "/webhooks/github",
+  guards: [
+    createSignatureGuard({
+      secret: process.env.GITHUB_WEBHOOK_SECRET!,
+      header: "X-Hub-Signature-256",
+      algorithm: "sha256",
+    }),
+  ],
+  handler: async (ctx, payload) => {
+    ctx.logger.info("GitHub event received", { action: payload.action });
+    return { ok: true };
+  },
+});
+```
+
+### RPC (tRPC-style)
+
+Type-safe RPC procedures with automatic router generation.
+
+```ts
+import { rpc } from "@archlast/server/functions/definition";
+import { z } from "zod";
+
+// RPC query
+export const getTasks = rpc.query({
+  args: z.object({
+    completed: z.boolean().optional(),
   }),
+  handler: async (ctx, args) => {
+    const query = ctx.db.query("tasks");
+    if (args.completed !== undefined) {
+      query.where({ completed: args.completed });
+    }
+    return query.findMany();
+  },
+});
+
+// RPC mutation
+export const createTask = rpc.mutation({
+  args: z.object({
+    text: z.string(),
+  }),
+  handler: async (ctx, args) => {
+    return ctx.db.insert("tasks", { text: args.text, completed: false });
+  },
+});
+```
+
+---
+
+## Context Objects
+
+Each function receives a context object with available services.
+
+### QueryCtx (for queries)
+
+```ts
+interface QueryCtx {
+  db: GenericDatabaseReader<DataModel>;
+  auth: AuthContext;
+  repository: RepositoryMap<DataModel>;
+  logger: LogService;
+}
+```
+
+### MutationCtx (for mutations)
+
+```ts
+interface MutationCtx extends QueryCtx {
+  db: GenericDatabaseWriter<DataModel>;
+  scheduler: JobScheduler;
+}
+```
+
+### ActionCtx (for actions)
+
+```ts
+interface ActionCtx extends MutationCtx {
+  storage: StorageClient;
+}
+```
+
+### AuthContext
+
+The auth context is populated from Better-Auth session data:
+
+```ts
+interface AuthContext {
+  // User ID from Better-Auth session
+  userId: string | null;
+
+  // Session ID from Better-Auth
+  sessionId: string | null;
+
+  // Whether the request is authenticated
+  isAuthenticated: boolean;
+
+  // Better-Auth user object
+  user: {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name?: string;
+    image?: string;
+    role?: string;        // "user", "admin", "super-admin"
+    banned?: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+  } | null;
+
+  // Tenant/Organization info (if using organizations)
+  tenant?: {
+    id: string;
+    name: string;
+    ownerId: string;
+  } | null;
+
+  // Membership info
+  membership?: {
+    role: string;
+    permissions: string[];
+  } | null;
+}
+```
+
+**Note:** Better-Auth stores users in `system_auth_user` collection with the `id` field (not `_id`). The adapter handles mapping automatically.
+
+### Usage Examples
+
+```ts
+export const myQuery = query(async (ctx) => {
+  // Database access
+  const tasks = await ctx.db.query("tasks").findMany();
+
+  // LINQ-style repository
+  const data = await ctx.repository.tasks
+    .Where({ completed: false })
+    .OrderBy({ createdAt: "desc" })
+    .Take(10)
+    .ToArrayAsync();
+
+  // Auth info
+  if (ctx.auth.isAuthenticated) {
+    console.log("User:", ctx.auth.userId);
+  }
+
+  // Logging
+  ctx.logger.info("Query executed", { count: tasks.length });
+
+  return tasks;
+});
+
+export const myMutation = mutation(async (ctx) => {
+  // Schedule background job
+  await ctx.scheduler.schedule({
+    name: "sendNotification",
+    preset: SchedulePreset.RunNow,
+    payload: { userId: ctx.auth.userId },
+  });
+});
+
+export const myAction = action(async (ctx) => {
+  // File storage
+  const file = await ctx.storage.get("file_id");
+  const newId = await ctx.storage.store("bucket", buffer);
+});
+```
+
+---
+
+## Authentication & Permissions
+
+Archlast uses [Better-Auth](https://www.better-auth.com/) for authentication. The server mounts Better-Auth at `/api/auth/*` and includes these plugins:
+
+- **Email/Password**: Standard credential authentication via `signIn.email()`
+- **Username**: Username-based sign-in via `signIn.username()`
+- **Anonymous**: Guest user support via `signIn.anonymous()`
+- **Admin**: User management, roles, bans, impersonation
+- **API Key**: Programmatic access with `arch_` prefixed keys
+- **Organization**: Multi-tenancy support
+
+### Sign-In Methods
+
+```ts
+// Email-based sign-in (web app pattern)
+await authClient.signIn.email({ email: "user@example.com", password: "..." });
+
+// Username-based sign-in (dashboard pattern)
+await authClient.signIn.username({ username: "admin", password: "..." });
+
+// Anonymous/guest sign-in
+await authClient.signIn.anonymous();
+```
+
+### Better-Auth Configuration
+
+Better-Auth is configured in the server with these features:
+
+```ts
+// Environment variables for Better-Auth
+BETTER_AUTH_SECRET=your-32-char-secret    // Required in production
+APP_URL=https://your-app.com               // Base URL for redirects
+ARCHLAST_ALLOWED_ORIGINS=http://localhost:3000  // Trusted origins (CSV)
+```
+
+### Auth Modes
+
+All functions default to requiring authentication. Override with `auth` option:
+
+```ts
+// Required (default) - must be authenticated via Better-Auth
+export const privateQuery = query({
+  handler: async (ctx) => {
+    // ctx.auth.userId is guaranteed to exist
+    // ctx.auth.user contains Better-Auth user object
+  },
+});
+
+// Optional - authentication checked but not required
+export const optionalAuth = query({
+  auth: "optional",
+  handler: async (ctx) => {
+    if (ctx.auth.isAuthenticated) {
+      // Authenticated user via Better-Auth
+    } else {
+      // Anonymous/guest user
+    }
+  },
+});
+
+// Public - no authentication required
+export const publicQuery = query({
+  auth: "public",
+  handler: async (ctx) => {
+    // Anyone can access
+  },
+});
+```
+
+### Permissions
+
+Add permission checks for role-based access:
+
+```ts
+export const adminOnly = query({
+  permissions: ["admin"],
+  handler: async (ctx) => {
+    // Only users with "admin" permission
+  },
+});
+
+export const moderatorOrAdmin = mutation({
+  permissions: ["admin", "moderator"],
+  handler: async (ctx) => {
+    // Users with either permission
+  },
 });
 ```
 
-## Docker templates
+---
+
+## Background Jobs
+
+Schedule background tasks using the job scheduler.
+
+```ts
+import { SchedulePreset } from "@archlast/server/jobs";
+
+export const scheduleCleanup = mutation(async (ctx) => {
+  // Run immediately
+  await ctx.scheduler.schedule({
+    name: "cleanupOldRecords",
+    preset: SchedulePreset.RunNow,
+    payload: { olderThanDays: 30 },
+  });
+
+  // Run every 5 minutes
+  await ctx.scheduler.schedule({
+    name: "sendReminder",
+    preset: SchedulePreset.Every5Minutes,
+    payload: { userId: ctx.auth.userId },
+  });
+
+  // Run every 10 minutes
+  await ctx.scheduler.schedule({
+    name: "syncData",
+    preset: SchedulePreset.Every10Minutes,
+    payload: {},
+  });
+
+  // Recurring with cron
+  await ctx.scheduler.schedule({
+    name: "dailyReport",
+    cron: "0 9 * * *", // Every day at 9 AM
+    payload: {},
+  });
+});
+```
+
+### Schedule Presets
+
+| Preset | Cron Expression | Description |
+|--------|-----------------|-------------|
+| `RunNow` | (immediate) | Execute immediately |
+| `EveryMinute` | `* * * * *` | Run every minute |
+| `Every5Minutes` | `*/5 * * * *` | Run every 5 minutes |
+| `Every10Minutes` | `*/10 * * * *` | Run every 10 minutes |
+| `Every30Minutes` | `*/30 * * * *` | Run every 30 minutes |
+| `Hourly` | `0 * * * *` | Run every hour |
+| `Every8Hours` | `0 */8 * * *` | Run every 8 hours |
+| `Every16Hours` | `0 */16 * * *` | Run every 16 hours |
+| `DailyMidnight` | `0 0 * * *` | Daily at midnight UTC |
+| `Weekly` | `0 0 * * 0` | Weekly on Sunday midnight |
+| `Monthly` | `0 0 1 * *` | Monthly on the 1st |
+| `Quarterly` | `0 0 1 */3 *` | Quarterly (every 3 months) |
+
+You can also use custom cron expressions:
+
+```ts
+await ctx.scheduler.schedule({
+  name: "customJob",
+  cron: "0 9 * * 1-5", // Weekdays at 9 AM
+  payload: {},
+});
+```
+
+---
+
+## Storage Types
+
+File storage type definitions.
+
+```ts
+import type { StorageFile, StorageMetadata } from "@archlast/server/storage/types";
+
+interface StorageFile {
+  id: string;
+  bucket: string;
+  filename: string;
+  contentType: string;
+  size: number;
+  createdAt: Date;
+}
+
+interface StorageMetadata {
+  filename: string;
+  contentType: string;
+  size: number;
+  bucket: string;
+  createdAt: Date;
+  url?: string;
+}
+```
+
+---
+
+## Subpath Exports
+
+Import only what you need:
+
+| Import | Description |
+|--------|-------------|
+| `@archlast/server/schema/definition` | `defineSchema`, `defineTable`, relationship helpers |
+| `@archlast/server/schema/validators` | `v` validator object |
+| `@archlast/server/functions/definition` | `query`, `mutation`, `action`, `rpc` |
+| `@archlast/server/functions/types` | Context types, function types |
+| `@archlast/server/http/definition` | `http` route builder |
+| `@archlast/server/http/router` | HTTP router utilities |
+| `@archlast/server/http` | HTTP utilities |
+| `@archlast/server/webhook/definition` | `webhook` function builder |
+| `@archlast/server/webhook/guard` | Webhook guard utilities |
+| `@archlast/server/webhook/verifier` | Signature verification |
+| `@archlast/server/webhook` | Webhook utilities |
+| `@archlast/server/jobs` | `SchedulePreset`, `Scheduler`, `JobQueue` |
+| `@archlast/server/jobs/scheduler` | Scheduler class and presets |
+| `@archlast/server/jobs/queue` | Job queue implementation |
+| `@archlast/server/storage/types` | Storage type definitions |
+| `@archlast/server/context` | Server context exports |
+| `@archlast/server/db/interfaces` | Database interface types |
+| `@archlast/server/auth/interfaces` | Auth interface types |
+| `@archlast/server/repository/interfaces` | Repository interface types |
+| `@archlast/server/repository/factory` | Repository factory |
+| `@archlast/server/di/decorators` | DI decorators |
+| `@archlast/server/di/container` | DI container |
+| `@archlast/server/logging/logger` | Logger service |
+| `@archlast/server/docker` | Docker utilities |
+
+---
+
+## Environment Variables
+
+Key variables used by the server runtime:
+
+### Better-Auth Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BETTER_AUTH_SECRET` | - | **Required in production.** Secret for signing tokens |
+| `APP_URL` | `http://localhost:4000` | Base URL for auth redirects |
+| `BETTER_AUTH_DEBUG` | `false` | Enable debug logging |
+
+### Server Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `4000` | HTTP server port |
+| `NODE_ENV` | `development` | Environment mode |
+| `ARCHLAST_DB_ROOT` | `./data` | Database file directory |
+| `ARCHLAST_ALLOWED_ORIGINS` | - | CORS allowed origins (CSV) |
+| `ARCHLAST_CORS_ALLOW_CREDENTIALS` | `false` | Allow credentials in CORS |
+
+### Storage Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STORAGE_ROOT` | `./storage` | Local file storage directory |
+| `STORAGE_SIGNING_SECRET` | - | Secret for signed URLs |
+| `S3_ENABLED` | `false` | Enable S3 storage |
+| `S3_BUCKET` | - | S3 bucket name |
+| `S3_REGION` | `us-east-1` | S3 region |
+| `AWS_ACCESS_KEY_ID` | - | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | - | AWS secret key |
+
+### Dashboard & Store Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ARCHLAST_DASHBOARD_DIR` | - | Dashboard static files path |
+| `ARCHLAST_DASHBOARD_URL` | - | Dashboard proxy URL |
+| `ARCHLAST_STORE_PORT` | `7001` | Document store port |
+| `ARCHLAST_STORE_HOST` | `127.0.0.1` | Document store host |
+| `ARCHLAST_STORE_NO_TLS` | `false` | Disable TLS for document store |
+
+---
+
+## Docker Templates
+
+Templates for Docker deployment are included in `templates/`:
+
+- `docker-compose.yml` - Base compose file
+- `docker-compose.dev.yml` - Development overrides
+- `docker-compose.prod.yml` - Production configuration
+- `.env.example` - Example environment variables
+- `archlast.config.js` - CLI configuration template
+
+The CLI uses these templates when running `archlast start`.
+
+---
+
+## Keywords
 
-Docker compose templates and configuration examples are available under
-`templates/` in this package.
+archlast, server, backend, reactive, real-time, websocket, typescript, api, baas
 
-## Publishing (maintainers)
+## License
 
-See `docs/npm-publishing.md` for release and publish steps.
+MIT

package/docker/README.md

@@ -1,5 +1,11 @@
 # Archlast Docker Assets
 
 This folder is reserved for Docker build assets distributed with the
-@archlast/server package. The production Dockerfile and service scripts
-are defined in the repository root under `docker/`.
+`@archlast/server` package. The production Dockerfile and s6 service
+definitions live in the repository root under `docker/`.
+
+If you are packaging a runtime image, use the root `docker/Dockerfile` and the
+service definitions in `docker/s6-rc.d/*`.
+
+For local runtime via the CLI, use the templates bundled in
+`packages/server/templates/`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@archlast/server",
-    "version": "0.0.1",
+    "version": "0.1.1",
     "description": "Archlast server library exports and Docker templates",
     "license": "MIT",
     "repository": {