@archlast/server 0.1.1 → 0.1.2

package/README.md

@@ -1,959 +1,100 @@
 # @archlast/server
 
-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.
+Type-safe server definitions and runtime helpers for Archlast. This package is
+used to define schema, functions, and shared types, and it ships Docker
+templates for runtime deployment.
 
-## 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
+## Install
 
 ```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
-# Use the CLI to run the server
-archlast start
-
-# The Docker image contains the full runtime
-docker pull archlast/server:latest
-```
+## Library vs runtime
 
----
+This package is a dev-time library for schema and function definitions. The
+runtime server is delivered via the Docker image (`algochad/archlast-server`) and managed
+by the CLI (`archlast start`).
 
-## Schema Definition
-
-Define your data model in `src/schema.ts`:
+## Schema
 
 ```ts
 import { defineSchema, defineTable, v } from "@archlast/server/schema/definition";
 
 export default defineSchema({
   tasks: defineTable({
-    _id: v.id().primaryKey(),
+    id: v.id(),
     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.
+## Functions
 
 ```ts
-import { rpc } from "@archlast/server/functions/definition";
+import { query, mutation } 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();
-  },
+export const list = query({
+  handler: async (ctx) => ctx.db.table("tasks").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);
+export const create = mutation({
+  args: { text: z.string() },
+  handler: async (ctx, args) => ctx.db.table("tasks").insert({ text: args.text }),
 });
 ```
 
----
-
-## 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();
-```
+Other function types:
+- `action` for long running tasks
+- `http` for explicit HTTP routes
+- `webhook` for signed incoming events
+- `rpc` for tRPC-style public procedures
 
-### Better-Auth Configuration
+## Auth and permissions
 
-Better-Auth is configured in the server with these features:
+All functions default to `auth: "required"`. You can mark functions public or
+optional, and attach permissions.
 
 ```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({
+export const publicPing = 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
-  },
-});
-```
-
----
-
-## 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: {},
+  handler: async () => "pong",
 });
 ```
 
----
-
-## Storage Types
+## Runtime exports
 
-File storage type definitions.
+Common entry points:
+- `@archlast/server/schema/definition` and `@archlast/server/schema/validators`
+- `@archlast/server/functions/definition` and `@archlast/server/functions/types`
+- `@archlast/server/http` and `@archlast/server/webhook`
+- `@archlast/server/jobs`
+- `@archlast/server/storage/types`
+- `@archlast/server/context`
 
-```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;
-}
-```
+## Docker templates
 
----
+Templates live under `templates/` in this package:
+- `docker-compose.yml`, `docker-compose.dev.yml`, `docker-compose.prod.yml`
+- `.env.example`
+- `archlast.config.js`
 
-## Subpath Exports
+The CLI uses these templates to generate a local Docker setup.
 
-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
+## Environment configuration
 
 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
-
-archlast, server, backend, reactive, real-time, websocket, typescript, api, baas
-
-## License
-
-MIT
+- `PORT` (default: 4000)
+- `ARCHLAST_DB_ROOT` (default: `./data`)
+- `ARCHLAST_ALLOWED_ORIGINS` (CSV)
+- `ARCHLAST_CORS_ALLOW_CREDENTIALS` (`true` or `false`)
+- `STORAGE_ROOT` and `STORAGE_SIGNING_SECRET`
+- `S3_ENABLED`, `S3_BUCKET`, `S3_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
+- `ARCHLAST_ADMIN_TOKEN` (deprecated), `ARCHLAST_AUTH_TOKEN_PEPPER`
+- `ARCHLAST_DASHBOARD_DIR` or `ARCHLAST_DASHBOARD_URL`
+- `ARCHLAST_STORE_PORT`, `ARCHLAST_STORE_NO_TLS`
+
+## Publishing (maintainers)
+
+See `docs/npm-publishing.md` for release and publish steps.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@archlast/server",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "description": "Archlast server library exports and Docker templates",
     "license": "MIT",
     "repository": {
@@ -150,7 +150,7 @@
         "LICENSE"
     ],
     "archlast": {
-        "dockerImage": "archlast/server",
+        "dockerImage": "algochad/archlast-server",
         "defaultTag": "latest",
         "minDockerVersion": "24.0.0"
     },

package/templates/archlast.config.js

@@ -8,7 +8,7 @@ module.exports = {
     },
     docker: {
         // Docker image to run.
-        image: "archlast/server",
+        image: "algochad/archlast-server",
         tag: "latest",
         containerName: "archlast-server",
         volumeName: "archlast-data",

package/templates/docker-compose.yml

@@ -2,7 +2,7 @@ version: "3.8"
 
 services:
   archlast:
-    image: archlast/server:${ARCHLAST_VERSION:-latest}
+    image: algochad/archlast-server:${ARCHLAST_VERSION:-latest}
     container_name: ${ARCHLAST_CONTAINER_NAME:-archlast-server}
     restart: unless-stopped
     ports: