ras-stack 0.39.5 → 0.40.0

package/examples/full-stack/Dockerfile.standalone

@@ -0,0 +1,28 @@
+# syntax=docker/dockerfile:1
+ARG RUNTIME_BINARIES_IMAGE=ghcr.io/richardsolomou/ras-stack-runtime-binaries:runtime-v1.0.1@sha256:581a691b59a603685bee8ba9576e80d419b967b63017f82d778fce39ca6f0c0b
+FROM node:24-alpine AS build
+WORKDIR /app
+RUN apk add --no-cache python3 make g++
+RUN corepack enable && corepack install --global pnpm@11.15.0
+COPY . .
+RUN pnpm install --no-frozen-lockfile
+RUN pnpm build
+
+FROM ${RUNTIME_BINARIES_IMAGE} AS runtime-binaries
+
+FROM node:24-alpine
+WORKDIR /app
+RUN apk add --no-cache tini \
+    && rm -rf /usr/local/lib/node_modules/corepack /usr/local/lib/node_modules/npm /opt/yarn-v1.22.22 \
+    && rm -f /usr/local/bin/corepack /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/yarn /usr/local/bin/yarnpkg \
+    && mkdir -p /data \
+    && chown -R node:node /app /data
+COPY --from=build --chown=node:node /app/.output ./.output
+COPY --from=runtime-binaries /usr/local/bin/centrifugo /usr/local/bin/centrifugo
+COPY --from=runtime-binaries /usr/local/bin/caddy /usr/local/bin/caddy
+COPY --chown=node:node centrifugo.json ./centrifugo.json
+ENV NODE_ENV=production DATA_DIR=/data TRUST_PROXY=false CENTRIFUGO_CONFIG=/app/centrifugo.json CENTRIFUGO_API_URL=http://127.0.0.1:8100/api CENTRIFUGO_HTTP_SERVER_PORT=8100
+EXPOSE 3100
+HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=3 CMD wget -q --spider http://127.0.0.1:3100/api/ready || exit 1
+USER node
+ENTRYPOINT ["/sbin/tini", "-g", "--", "node", ".output/server/containerRuntime.mjs"]

package/examples/full-stack/centrifugo.json

@@ -0,0 +1,14 @@
+{
+  "client": {
+    "proxy": {
+      "connect": {
+        "enabled": true,
+        "endpoint": "http://127.0.0.1:3101/api/centrifugo/connect",
+        "http_headers": ["Cookie", "Origin", "X-Forwarded-Host", "X-Forwarded-Proto"],
+        "http": { "static_headers": { "X-Proxy-Secret": "${CENTRIFUGO_VAR_PROXY_SECRET}" } }
+      }
+    }
+  },
+  "channel": { "namespaces": [{ "name": "messages", "allow_subscribe_for_client": true }] },
+  "health": { "enabled": true }
+}

package/examples/full-stack/dockerignore.template

@@ -0,0 +1,8 @@
+.data
+.git
+.output
+node_modules
+test-results
+.env
+.env.*
+!.env.example

package/examples/full-stack/drizzle/0000_production_reference.sql

@@ -0,0 +1,114 @@
+CREATE TABLE `user` (
+  `id` text PRIMARY KEY NOT NULL,
+  `name` text NOT NULL,
+  `email` text NOT NULL,
+  `email_verified` integer DEFAULT false NOT NULL,
+  `image` text,
+  `created_at` integer NOT NULL,
+  `updated_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `user_email_unique` ON `user` (`email`);
+--> statement-breakpoint
+CREATE TABLE `session` (
+  `id` text PRIMARY KEY NOT NULL,
+  `expires_at` integer NOT NULL,
+  `token` text NOT NULL,
+  `created_at` integer NOT NULL,
+  `updated_at` integer NOT NULL,
+  `ip_address` text,
+  `user_agent` text,
+  `user_id` text NOT NULL,
+  FOREIGN KEY (`user_id`) REFERENCES `user`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `session_token_unique` ON `session` (`token`);
+--> statement-breakpoint
+CREATE INDEX `session_user_id_idx` ON `session` (`user_id`);
+--> statement-breakpoint
+CREATE TABLE `account` (
+  `id` text PRIMARY KEY NOT NULL,
+  `account_id` text NOT NULL,
+  `issuer` text NOT NULL,
+  `provider_id` text NOT NULL,
+  `user_id` text NOT NULL,
+  `access_token` text,
+  `refresh_token` text,
+  `id_token` text,
+  `access_token_expires_at` integer,
+  `refresh_token_expires_at` integer,
+  `scope` text,
+  `password` text,
+  `created_at` integer NOT NULL,
+  `updated_at` integer NOT NULL,
+  FOREIGN KEY (`user_id`) REFERENCES `user`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `account_user_id_idx` ON `account` (`user_id`);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `account_issuer_account_id_unique` ON `account` (`issuer`,`account_id`);
+--> statement-breakpoint
+CREATE TABLE `verification` (
+  `id` text PRIMARY KEY NOT NULL,
+  `identifier` text NOT NULL,
+  `value` text NOT NULL,
+  `expires_at` integer NOT NULL,
+  `created_at` integer NOT NULL,
+  `updated_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `verification_identifier_idx` ON `verification` (`identifier`);
+--> statement-breakpoint
+CREATE TABLE `rate_limit` (
+  `id` text PRIMARY KEY NOT NULL,
+  `key` text NOT NULL,
+  `count` integer NOT NULL,
+  `last_request` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `rate_limit_key_unique` ON `rate_limit` (`key`);
+--> statement-breakpoint
+CREATE TABLE `app_rate_limit` (
+  `key` text PRIMARY KEY NOT NULL,
+  `count` integer NOT NULL,
+  `reset_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `messages` (
+  `id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+  `author_id` text NOT NULL,
+  `author` text NOT NULL,
+  `body` text NOT NULL,
+  `created_at` integer NOT NULL,
+  FOREIGN KEY (`author_id`) REFERENCES `user`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `messages_author_id_idx` ON `messages` (`author_id`);
+--> statement-breakpoint
+CREATE TABLE `uploads` (
+  `id` text PRIMARY KEY NOT NULL,
+  `owner_id` text NOT NULL,
+  `filename` text NOT NULL,
+  `media_type` text NOT NULL,
+  `length` integer NOT NULL,
+  `offset` integer DEFAULT 0 NOT NULL,
+  `state` text DEFAULT 'active' NOT NULL,
+  `created_at` integer NOT NULL,
+  `updated_at` integer NOT NULL,
+  FOREIGN KEY (`owner_id`) REFERENCES `user`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `uploads_owner_id_state_idx` ON `uploads` (`owner_id`,`state`);
+--> statement-breakpoint
+CREATE TABLE `outbox` (
+  `id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+  `channel` text NOT NULL,
+  `payload` text NOT NULL,
+  `attempts` integer DEFAULT 0 NOT NULL,
+  `available_at` integer NOT NULL,
+  `created_at` integer NOT NULL,
+  `failed_at` integer,
+  `last_error` text
+);
+--> statement-breakpoint
+CREATE INDEX `outbox_available_at_idx` ON `outbox` (`available_at`,`id`);

package/examples/full-stack/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1787072400000,
+      "tag": "0000_production_reference",
+      "breakpoints": true
+    }
+  ]
+}

package/examples/full-stack/e2e/full-stack.spec.ts

@@ -0,0 +1,45 @@
+import { expect, test } from '@playwright/test'
+
+test('signs up, authorizes resources, persists an upload, and receives an outbox publication', async ({ browser, request }, testInfo) => {
+  const run = Date.now()
+  const firstMessage = `first message ${run}`
+  const realtimeMessage = `realtime message ${run}`
+  const origin = testInfo.project.use.baseURL!
+  expect((await request.get('/api/live')).status()).toBe(200)
+  expect((await request.get('/api/ready')).status()).toBe(200)
+  expect((await request.get('/')).headers()['x-content-type-options']).toBe('nosniff')
+  expect((await request.post('/api/uploads', { headers: { Origin: origin, 'Upload-Length': '1' } })).status()).toBe(401)
+  expect((await request.head('/api/uploads/missing')).status()).toBe(401)
+
+  const alice = await browser.newPage()
+  await alice.goto('/')
+  await signUp(alice, 'Alice', 'alice@example.test')
+  await alice.getByLabel('Message').fill(firstMessage)
+  await alice.getByRole('button', { name: 'Add message' }).click()
+  await expect(alice.getByText(`Alice: ${firstMessage}`)).toBeVisible()
+
+  await alice.getByLabel('Upload').setInputFiles({ name: 'proof.txt', mimeType: 'text/plain', buffer: Buffer.from('workspace proof') })
+  const upload = alice.getByText(/Uploaded to .*\/api\/uploads\//)
+  await expect(upload).toBeVisible()
+  const uploadUrl = (await upload.textContent())!.replace('Uploaded to ', '')
+
+  const bob = await browser.newPage()
+  await bob.goto('/')
+  await signUp(bob, 'Bob', 'bob@example.test')
+  expect(await bob.evaluate((url) => fetch(url, { method: 'HEAD' }).then((response) => response.status), uploadUrl)).toBe(404)
+  await expect(bob.getByText(`Alice: ${firstMessage}`)).toBeVisible()
+  await bob.getByLabel('Message').fill(realtimeMessage)
+  await bob.getByRole('button', { name: 'Add message' }).click()
+  await expect(alice.getByText(`Bob: ${realtimeMessage}`)).toBeVisible()
+  await alice.getByRole('button', { name: 'Sign out' }).click()
+  await expect(alice.getByRole('heading', { name: 'Create account' })).toBeVisible()
+  await alice.screenshot({ path: testInfo.outputPath('example.png'), fullPage: true })
+})
+
+async function signUp(page: import('@playwright/test').Page, name: string, email: string) {
+  await page.getByLabel('Name').fill(name)
+  await page.getByLabel('Email').fill(email)
+  await page.getByLabel('Password').fill('correct horse battery staple')
+  await page.getByRole('button', { name: 'Create account', exact: true }).click()
+  await expect(page.getByRole('heading', { name: `Hello, ${name}` })).toBeVisible()
+}

package/examples/full-stack/gitignore.template

@@ -0,0 +1,9 @@
+dist/
+node_modules/
+.data/
+.output/
+test-results/
+*.tgz
+.env
+.env.*
+!.env.example

package/examples/full-stack/oxlint.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["./node_modules/ras-stack/config/oxlint/application.json", "./node_modules/ras-stack/config/oxlint/tanstack.json"],
+  "ignorePatterns": ["src/routeTree.gen.ts", ".output/**", "node_modules/**"]
+}

package/examples/full-stack/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@ras-stack/example-full-stack",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build && node ../../dist/cli.js assets sync && esbuild scripts/containerRuntime.ts scripts/database.ts --bundle --platform=node --format=esm --target=node24 --external:better-sqlite3 --outdir=.output/server --out-extension:.js=.mjs --log-level=warning && node ../../dist/cli.js assets check",
+    "dev": "vite dev",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint --config oxlint.json --type-aware --deny-warnings .",
+    "realtime": "ras realtime --config centrifugo.json --name ras-stack-example-realtime --port 8100 --origin http://localhost:3100 --secret example-development-secret --connect-proxy-endpoint http://host.docker.internal:3100/api/centrifugo/connect",
+    "e2e": "playwright test",
+    "test": "vitest run --config vitest.config.ts",
+    "typecheck": "tsc --noEmit",
+    "db:backup": "node .output/server/database.mjs backup",
+    "db:restore": "node .output/server/database.mjs restore",
+    "check": "pnpm format:check && pnpm lint && pnpm build && pnpm typecheck && pnpm test"
+  },
+  "dependencies": {
+    "@better-auth/drizzle-adapter": "1.7.1",
+    "@opentelemetry/api-logs": "^0.221.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.221.0",
+    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-logs": "^0.221.0",
+    "@posthog/react": "^1.10.3",
+    "@tanstack/react-query": "^5.101.4",
+    "@tanstack/react-router": "^1.170.18",
+    "@tanstack/react-router-ssr-query": "^1.167.1",
+    "@tanstack/react-start": "^1.168.32",
+    "better-auth": "1.7.1",
+    "better-sqlite3": "12.11.1",
+    "centrifuge": "5.7.0",
+    "drizzle-orm": "0.45.2",
+    "nodemailer": "^9.0.3",
+    "posthog-js": "^1.414.0",
+    "posthog-node": "^5.48.1",
+    "ras-stack": "workspace:*",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tus-js-client": "^4.3.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.62.1",
+    "@types/better-sqlite3": "9.6.0",
+    "@types/node": "^26.2.0",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.5",
+    "esbuild": "0.28.2",
+    "nitro": "3.0.260610-beta",
+    "oxfmt": "^0.62.0",
+    "oxlint": "^1.74.0",
+    "typescript": "^7.0.2",
+    "vite": "8.2.1",
+    "vitest": "^4.1.10"
+  }
+}

package/examples/full-stack/playwright.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './e2e',
+  timeout: 30_000,
+  use: { ...devices['Desktop Chrome'], baseURL: process.env.EXAMPLE_BASE_URL ?? 'http://127.0.0.1:3110', trace: 'retain-on-failure' },
+})

package/examples/full-stack/pnpm-workspace.template.yaml

@@ -0,0 +1,12 @@
+packages:
+  - .
+allowBuilds:
+  better-sqlite3: true
+  core-js: false
+  esbuild: true
+  protobufjs: true
+minimumReleaseAge: 10080
+minimumReleaseAgeExclude:
+  - ras-stack
+  - better-auth
+  - '@better-auth/*'

package/examples/full-stack/ras-stack.assets.json

@@ -0,0 +1,4 @@
+{
+  "outputDirectory": ".output/server",
+  "assets": [{ "source": "drizzle", "destination": "drizzle" }]
+}

package/examples/full-stack/scripts/containerRuntime.ts

@@ -0,0 +1,29 @@
+import { runRealtimeStack } from 'ras-stack/runtime'
+
+const required = (name: string) => {
+  const value = process.env[name]?.trim()
+  if (!value) throw new Error(`${name} is required`)
+  return value
+}
+
+const apiKey = required('CENTRIFUGO_API_KEY')
+const proxySecret = required('CENTRIFUGO_PROXY_SECRET')
+const realtime: NodeJS.ProcessEnv = { ...process.env, CENTRIFUGO_VAR_PROXY_SECRET: proxySecret }
+delete realtime.CENTRIFUGO_API_KEY
+delete realtime.CENTRIFUGO_PROXY_SECRET
+delete realtime.CENTRIFUGO_API_URL
+delete realtime.CENTRIFUGO_CONFIG
+
+process.exitCode = await runRealtimeStack({
+  app: { command: process.execPath, args: ['.output/server/index.mjs'], env: { ...process.env, PORT: '3101' } },
+  centrifugo: {
+    configPath: process.env.CENTRIFUGO_CONFIG ?? '/app/centrifugo.json',
+    env: realtime,
+    environment: { apiKey, allowedOrigins: process.env.APP_URL ?? 'http://localhost:3100' },
+  },
+  caddy: {
+    configPath: '/tmp/ras-stack-example-Caddyfile',
+    env: process.env,
+    proxy: { publicPort: 3100, appPort: 3101, realtimePort: 8100 },
+  },
+})

package/examples/full-stack/scripts/database.test.ts

@@ -0,0 +1,121 @@
+import Database from 'better-sqlite3'
+import { mkdtemp, readdir, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import { runDatabaseCommand } from './database'
+
+let directory: string
+let source: string
+
+beforeEach(async () => {
+  directory = await mkdtemp(path.join(os.tmpdir(), 'ras-stack-example-backup-'))
+  source = path.join(directory, 'example.sqlite')
+  writeValue(source, 'before')
+})
+
+afterEach(async () => {
+  await rm(directory, { recursive: true, force: true })
+})
+
+it('backs up and restores a validated database', async () => {
+  const backup = path.join(directory, 'backup.sqlite')
+  await runDatabaseCommand('backup', backup, { DATA_DIR: directory })
+  writeValue(source, 'after')
+  await runDatabaseCommand('restore', backup, { DATA_DIR: directory })
+  expect(readValue(source)).toBe('before')
+})
+
+it('rejects a corrupt restore candidate without changing the source', async () => {
+  const corrupt = path.join(directory, 'corrupt.sqlite')
+  await writeFile(corrupt, 'not sqlite')
+  await expect(runDatabaseCommand('restore', corrupt, { DATA_DIR: directory })).rejects.toThrow('file is not a database')
+  expect(readValue(source)).toBe('before')
+})
+
+it('restores the original file and removes temporary state when replacement fails', async () => {
+  const backup = path.join(directory, 'backup.sqlite')
+  await runDatabaseCommand('backup', backup, { DATA_DIR: directory })
+  writeValue(source, 'current')
+  const operations = await import('node:fs/promises')
+  let renames = 0
+  const rename = vi.fn(async (from: string, to: string) => {
+    renames += 1
+    if (renames === 2) throw new Error('replacement failed')
+    await operations.rename(from, to)
+  }) as typeof operations.rename
+  await expect(runDatabaseCommand('restore', backup, { DATA_DIR: directory }, { ...operations, rename })).rejects.toThrow(
+    'replacement failed',
+  )
+  expect(readValue(source)).toBe('current')
+  expect((await readdir(directory)).some((file) => file.includes('.restore-'))).toBe(false)
+})
+
+it('restores the original file even when temporary cleanup also fails', async () => {
+  const backup = path.join(directory, 'backup.sqlite')
+  await runDatabaseCommand('backup', backup, { DATA_DIR: directory })
+  writeValue(source, 'current')
+  const operations = await import('node:fs/promises')
+  let renames = 0
+  const rename = vi.fn(async (from: string, to: string) => {
+    renames += 1
+    if (renames === 2) throw new Error('replacement failed')
+    await operations.rename(from, to)
+  }) as typeof operations.rename
+  const failure = await runDatabaseCommand(
+    'restore',
+    backup,
+    { DATA_DIR: directory },
+    {
+      ...operations,
+      rename,
+      rm: vi.fn().mockRejectedValue(new Error('cleanup failed')),
+    },
+  ).catch((error: unknown) => error)
+  expect(failure).toBeInstanceOf(AggregateError)
+  expect((failure as AggregateError).errors.map(String)).toEqual(['Error: replacement failed', 'Error: cleanup failed'])
+  expect(readValue(source)).toBe('current')
+})
+
+it('reports rollback and cleanup failures after a replacement failure', async () => {
+  const backup = path.join(directory, 'backup.sqlite')
+  await runDatabaseCommand('backup', backup, { DATA_DIR: directory })
+  const operations = await import('node:fs/promises')
+  let renames = 0
+  const rename = vi.fn(async (from: string, to: string) => {
+    renames += 1
+    if (renames === 2) throw new Error('replacement failed')
+    if (renames === 3) throw new Error('rollback failed')
+    await operations.rename(from, to)
+  }) as typeof operations.rename
+  const failure = await runDatabaseCommand(
+    'restore',
+    backup,
+    { DATA_DIR: directory },
+    {
+      ...operations,
+      rename,
+      rm: vi.fn().mockRejectedValue(new Error('cleanup failed')),
+    },
+  ).catch((error: unknown) => error)
+  expect((failure as AggregateError).errors.map(String)).toEqual([
+    'Error: replacement failed',
+    'Error: rollback failed',
+    'Error: cleanup failed',
+  ])
+  expect(rename).toHaveBeenCalledTimes(3)
+})
+
+function writeValue(file: string, value: string) {
+  const database = new Database(file)
+  database.exec('DROP TABLE IF EXISTS proof; CREATE TABLE proof (value TEXT NOT NULL)')
+  database.prepare('INSERT INTO proof (value) VALUES (?)').run(value)
+  database.close()
+}
+
+function readValue(file: string) {
+  const database = new Database(file, { readonly: true })
+  const value = database.prepare('SELECT value FROM proof').pluck().get() as string
+  database.close()
+  return value
+}

package/examples/full-stack/scripts/database.ts

@@ -0,0 +1,105 @@
+import Database from 'better-sqlite3'
+import { existsSync } from 'node:fs'
+import { copyFile, mkdir, rename, rm } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+type FileOperations = { copyFile: typeof copyFile; mkdir: typeof mkdir; rename: typeof rename; rm: typeof rm }
+const defaultFileOperations: FileOperations = { copyFile, mkdir, rename, rm }
+
+export async function runDatabaseCommand(
+  command: 'backup' | 'restore',
+  suppliedPath: string | undefined,
+  environment: NodeJS.ProcessEnv = process.env,
+  fileOperations: FileOperations = defaultFileOperations,
+) {
+  const dataDirectory = path.resolve(environment.DATA_DIR ?? '.data/example-full-stack')
+  const source = path.join(dataDirectory, 'example.sqlite')
+  if (command === 'backup') {
+    const backupDirectory = path.join(dataDirectory, 'backups')
+    await fileOperations.mkdir(backupDirectory, { recursive: true })
+    const destination = suppliedPath
+      ? path.resolve(suppliedPath)
+      : path.join(backupDirectory, `example-${new Date().toISOString().replaceAll(':', '-')}.sqlite`)
+    const database = new Database(source, { readonly: true, fileMustExist: true })
+    try {
+      integrity(database, 'source')
+      await database.backup(destination)
+      const copy = new Database(destination, { readonly: true, fileMustExist: true })
+      try {
+        integrity(copy, 'backup')
+      } finally {
+        copy.close()
+      }
+      return destination
+    } finally {
+      database.close()
+    }
+  }
+
+  if (!suppliedPath) throw new Error('restore requires a backup file')
+  const candidate = path.resolve(suppliedPath)
+  const backup = new Database(candidate, { readonly: true, fileMustExist: true })
+  try {
+    integrity(backup, 'backup')
+  } finally {
+    backup.close()
+  }
+  await fileOperations.mkdir(dataDirectory, { recursive: true })
+  for (const sidecar of [`${source}-wal`, `${source}-shm`]) {
+    if (existsSync(sidecar)) throw new Error(`Refusing to restore while SQLite sidecar exists: ${sidecar}`)
+  }
+  const temporary = `${source}.restore-${process.pid}`
+  await fileOperations.copyFile(candidate, temporary)
+  const restored = new Database(temporary, { readonly: true, fileMustExist: true })
+  try {
+    integrity(restored, 'restored')
+  } finally {
+    restored.close()
+  }
+  const previous = `${source}.before-restore-${Date.now()}`
+  const hasPrevious = existsSync(source)
+  if (hasPrevious) await fileOperations.rename(source, previous)
+  try {
+    await fileOperations.rename(temporary, source)
+  } catch (error) {
+    const failures = [error]
+    if (hasPrevious) {
+      try {
+        await fileOperations.rename(previous, source)
+      } catch (rollbackError) {
+        failures.push(rollbackError)
+      }
+    }
+    try {
+      await fileOperations.rm(temporary, { force: true })
+    } catch (cleanupError) {
+      failures.push(cleanupError)
+    }
+    if (failures.length === 1) throw error
+    const failure = new AggregateError(failures, 'Restore replacement failed and recovery was incomplete')
+    failure.cause = error
+    throw failure
+  }
+  return source
+}
+
+function integrity(database: Database.Database, label: string) {
+  const result = database.pragma('quick_check', { simple: true })
+  if (result !== 'ok') throw new Error(`${label} database failed quick_check: ${String(result)}`)
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [command, suppliedPath] = process.argv.slice(2)
+  if (command !== 'backup' && command !== 'restore') {
+    console.error('usage: database.mjs <backup [destination]|restore backup-file>')
+    process.exitCode = 2
+  } else {
+    try {
+      console.log(await runDatabaseCommand(command, suppliedPath))
+    } catch (error) {
+      console.error(error)
+      process.exitCode = 1
+    }
+  }
+}

package/examples/full-stack/src/client/auth.ts

@@ -0,0 +1,3 @@
+import { createAuthClient } from 'better-auth/react'
+
+export const authClient = createAuthClient()

package/examples/full-stack/src/client/queries.ts

@@ -0,0 +1,4 @@
+import { queryOptions } from '@tanstack/react-query'
+import { snapshot } from '../server/fns'
+
+export const snapshotQuery = () => queryOptions({ queryKey: ['example', 'snapshot'], queryFn: () => snapshot() })

package/examples/full-stack/src/client/queryClient.ts

@@ -0,0 +1 @@
+export { createStackQueryClient as createQueryClient, queryErrorMessage } from 'ras-stack/tanstack/query'

package/examples/full-stack/src/client/useRealtime.ts

@@ -0,0 +1,20 @@
+import { useQueryClient } from '@tanstack/react-query'
+import { createSameOriginRealtimeClient } from 'ras-stack/realtime/client'
+import { useConnectedRealtimeClient, useRealtimeSubscription } from 'ras-stack/realtime/react'
+import { useCallback } from 'react'
+import { snapshotQuery } from './queries'
+
+export function useRealtime(enabled: boolean) {
+  const queryClient = useQueryClient()
+  const create = useCallback(() => createSameOriginRealtimeClient({}), [])
+  const client = useConnectedRealtimeClient(create, enabled)
+  const configure = useCallback(
+    (subscription: NonNullable<ReturnType<typeof useRealtimeSubscription>>) => {
+      const refresh = () => void queryClient.invalidateQueries({ queryKey: snapshotQuery().queryKey })
+      subscription.on('publication', refresh)
+      return () => subscription.off('publication', refresh)
+    },
+    [queryClient],
+  )
+  useRealtimeSubscription({ client, channel: 'messages:all', enabled, configure })
+}

package/examples/full-stack/src/posthog.ts

@@ -0,0 +1,17 @@
+import { definePostHogCoverage } from 'ras-stack/posthog'
+
+export const postHogCoverage = definePostHogCoverage({
+  browser: {
+    analytics: true,
+    errorTracking: true,
+    identity: true,
+    sessionReplay: { disabled: 'The example does not handle user data worth replaying' },
+    featureFlags: { disabled: 'The example has no rollout-controlled behavior' },
+  },
+  server: {
+    analytics: true,
+    errorTracking: true,
+    logs: true,
+  },
+  sourceMaps: { disabled: 'The example is not deployed as a user-facing application' },
+})