maxibase 0.0.0-stage → 1.0.0

package/layers/base/server/utils/ip.ts

@@ -0,0 +1,15 @@
+import type { H3Event } from 'h3'
+
+export function getClientIP(event: H3Event): string {
+  const { trustedProxies } = useRuntimeConfig().rateLimit
+
+  // A client can send any x-forwarded-for it likes, so only the entries appended by our own
+  // proxies can be trusted. Those are the rightmost ones: count back past them to the real client.
+  if (trustedProxies > 0) {
+    const forwarded = (getRequestHeader(event, 'x-forwarded-for') || '').split(',')
+    const clientIP = forwarded[forwarded.length - trustedProxies]?.trim()
+    if (clientIP) return clientIP
+  }
+
+  return event.node.req.socket?.remoteAddress || 'unknown'
+}

package/layers/base/server/utils/log.ts

@@ -0,0 +1,31 @@
+import { logs } from '#server/database/schema'
+import { lt } from 'drizzle-orm/sql/expressions/conditions'
+
+export async function log(
+  summary: string,
+  data?: any,
+  origin?: string,
+  type?: string,
+  event?: any,
+) {
+  const session = event ? await getUserSession(event) : null
+  const userAgent = event?.node?.req?.headers['user-agent']
+
+  await db.insert(logs).values({
+    userId: session?.user?.id,
+    type,
+    origin: origin || event?.path + ' ' + event?.node?.req?.method,
+    summary,
+    data,
+    ipAddress: event ? getClientIP(event) : null,
+    userAgent,
+  })
+}
+
+export async function cleanLogs() {
+  const config = useRuntimeConfig()
+  const retentionMS = daysToMilliseconds(config.logs.retentionDays)
+  const cutoffDate = new Date(Date.now() - retentionMS)
+
+  await db.delete(logs).where(lt(logs.time, cutoffDate))
+}

package/layers/base/server/utils/rateLimit.ts

@@ -0,0 +1,69 @@
+import type { H3Event } from 'h3'
+
+export interface RateLimitRule {
+  limit: number // max requests per window
+  window: number // window duration in seconds
+}
+
+interface RateLimitEntry {
+  count: number
+  resetAt: number
+  bannedUntil: number
+}
+
+const entries = new Map<string, RateLimitEntry>()
+
+const SWEEP_INTERVAL = 10 * 60 * 1000
+setInterval(() => {
+  const now = Date.now()
+  for (const [key, entry] of entries) {
+    if (now > entry.resetAt && now > entry.bannedUntil) entries.delete(key)
+  }
+}, SWEEP_INTERVAL).unref?.()
+
+async function getId(event: H3Event): Promise<string> {
+  const { user } = await getUserSession(event)
+  if (user) return user.id
+  return getClientIP(event)
+}
+
+export async function enforceRateLimit(event: H3Event, route: string, rule: RateLimitRule) {
+  const config = useRuntimeConfig()
+  const id = await getId(event)
+  const key = `${route}:${id}`
+  const now = Date.now()
+
+  let entry = entries.get(key)
+
+  if (entry && entry.bannedUntil > now) {
+    throw tooManyRequests(event, entry.bannedUntil - now)
+  }
+
+  if (!entry || now > entry.resetAt) {
+    entry = { count: 0, resetAt: now + rule.window * 1000, bannedUntil: 0 }
+    entries.set(key, entry)
+  }
+
+  entry.count++
+  if (entry.count <= rule.limit) return
+
+  if (entry.count === rule.limit * config.rateLimit.banMultiplier) {
+    entry.bannedUntil = now + config.rateLimit.banSeconds * 1000
+    await log('Rate limit ban', undefined, route, 'security', event).catch(() => {})
+    throw tooManyRequests(event, entry.bannedUntil - now)
+  }
+
+  if (entry.count === rule.limit + 1) {
+    await log('Rate limit exceeded', undefined, route, 'security', event).catch(() => {})
+  }
+
+  throw tooManyRequests(event, entry.resetAt - now)
+}
+
+function tooManyRequests(event: H3Event, retryAfterMS: number) {
+  setResponseHeader(event, 'Retry-After', Math.ceil(retryAfterMS / 1000))
+  return createError({
+    status: 429,
+    message: 'Too many requests',
+  })
+}

package/layers/base/server/utils/schemas.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+export const emailSchema = z.string().trim().toLowerCase().pipe(z.email())
+
+export const passwordSchema = () => {
+  const { min, max } = useRuntimeConfig().public.password
+  return z.string().trim().min(min).max(max)
+}

package/layers/base/server/utils/text.ts

@@ -0,0 +1,4 @@
+export function prepareStringForSearch(text?: string) {
+  if (!text) return
+  return `%${text.replace(/[%_]/g, '\\$&')}%`
+}

package/layers/base/server/utils/time.ts

@@ -0,0 +1,3 @@
+export function daysToMilliseconds(days: number) {
+  return days * 24 * 60 * 60 * 1000
+}

package/layers/base/shared/types/auth.d.ts

@@ -0,0 +1,22 @@
+declare module '#auth-utils' {
+  interface User {
+    id: string
+    email?: string
+    role: 'admin' | 'user'
+    isAnonymous?: boolean
+    requiresMfaSetup?: boolean
+  }
+
+  interface UserSession {
+    expiresAt?: number
+    authenticatedAt: number
+  }
+}
+
+declare module 'h3' {
+  interface SessionConfig {
+    unique?: boolean
+  }
+}
+
+export {}

package/layers/base/shared/utils/logs.ts

@@ -0,0 +1,9 @@
+export const logTypes = [
+  { value: 'info', label: 'Info', color: 'primary-text' },
+  { value: 'warn', label: 'Warn', color: 'warning-text' },
+  { value: 'error', label: 'Error', color: 'danger-text' },
+  { value: 'debug', label: 'Debug', color: 'muted-text' },
+  { value: 'security', label: 'Security', color: 'secondary-text' },
+] as const
+
+export const logTypeValues = logTypes.map((logType) => logType.value)

package/layers/base/shared/utils/url.ts

@@ -0,0 +1,5 @@
+export function safePath(value: unknown, fallback = '/') {
+  if (typeof value !== 'string' || !value.startsWith('/')) return fallback
+  if (value.startsWith('//') || value.startsWith('/\\')) return fallback
+  return value
+}

package/locales/en.json

@@ -0,0 +1,33 @@
+{
+  "add": "Add",
+  "areYouSure": "Are you sure?",
+  "cancel": "Cancel",
+  "confirm": "Confirm",
+  "continue": "Continue",
+  "copied": "Copied",
+  "delete": "Delete",
+  "deleted": "Deleted",
+  "description": "Website",
+  "disable": "Disable",
+  "email": "Email",
+  "enable": "Enable",
+  "formatFailed": "Could not format or upload {files}",
+  "language": "Language | Languages",
+  "paste": "Paste",
+  "rename": "Rename",
+  "retry": "Retry",
+  "save": "Save",
+  "saved": "Saved",
+  "settings": "Settings",
+  "signout": "Sign Out",
+  "upload": "Upload",
+  "authCheck": {
+    "authenticatorCode": "Authenticator code",
+    "clipboardPermission": "Please allow clipboard access to paste",
+    "code": "Code",
+    "getCode": "Get code",
+    "otpSent": "Code sent to {email}",
+    "password": "Password",
+    "signin": "Sign In"
+  }
+}

package/locales/fr.json

@@ -0,0 +1,33 @@
+{
+  "add": "Ajouter",
+  "areYouSure": "Êtes-vous sûr ?",
+  "cancel": "Annuler",
+  "confirm": "Confirmer",
+  "continue": "Continuer",
+  "copied": "Copié",
+  "delete": "Supprimer",
+  "deleted": "Supprimé",
+  "description": "Site web",
+  "disable": "Désactiver",
+  "email": "Email",
+  "enable": "Activer",
+  "formatFailed": "Impossible de formater ou téléverser {files}",
+  "language": "Langue | Langues",
+  "paste": "Coller",
+  "rename": "Renommer",
+  "retry": "Réessayer",
+  "save": "Enregistrer",
+  "saved": "Enregistré",
+  "settings": "Paramètres",
+  "signout": "Se déconnecter",
+  "upload": "Téléverser",
+  "authCheck": {
+    "authenticatorCode": "Code de l'application d'authentification",
+    "clipboardPermission": "Veuillez autoriser l'accès au presse-papiers pour coller",
+    "code": "Code",
+    "getCode": "Demander le code",
+    "otpSent": "Code envoyé à {email}",
+    "password": "Mot de passe",
+    "signin": "Se connecter"
+  }
+}

package/locales/pages/admin-logs/en.json

@@ -0,0 +1 @@
+{}

package/locales/pages/admin-logs/fr.json

@@ -0,0 +1 @@
+{}

package/locales/pages/index/en.json

@@ -0,0 +1 @@
+{}

package/locales/pages/index/fr.json

@@ -0,0 +1 @@
+{}

package/locales/pages/signin/en.json

@@ -0,0 +1,5 @@
+{
+  "continueAsGuest": "Continue as Guest",
+  "or": "or",
+  "signinWith": "Sign in with"
+}

package/locales/pages/signin/fr.json

@@ -0,0 +1,5 @@
+{
+  "continueAsGuest": "Continuer en tant qu'invité",
+  "or": "ou",
+  "signinWith": "Se connecter avec"
+}

package/locales/pages/user-auth/en.json

@@ -0,0 +1,22 @@
+{
+  "2fa": "Two-Factor Authentication",
+  "authentication": "Authentication",
+  "authenticatorApp": "Authenticator app",
+  "changeEmail": "Change email address",
+  "changePassword": "Change password",
+  "code": "Code",
+  "codeInvalid": "Code invalid",
+  "deleteRefreshTokens": "Sign out from all devices",
+  "disableTOTP": "Do you really want to disable your authenticator?",
+  "lastFactor": "Keep at least one second factor.",
+  "emailChangeCodeSent": "Code sent to {email}",
+  "mfaRequired": "Two-factor authentication required",
+  "mfaRequiredDescription": "Set up a passkey or an authenticator app to finish signing in.",
+  "passkeyLimit": "Up to 4 passkeys",
+  "password": "Password",
+  "passwordPolicy": "At least {count} characters",
+  "registerPasskey": "Add a passkey",
+  "settings": "Settings",
+  "setupTotp": "Use an authenticator app",
+  "totpSecret": "Scan this QR code with your authenticator app or copy the code manually."
+}

package/locales/pages/user-auth/fr.json

@@ -0,0 +1,22 @@
+{
+  "2fa": "Authentification à deux facteurs",
+  "authentication": "Authentification",
+  "authenticatorApp": "Application d'authentification",
+  "changeEmail": "Modifier l'adresse email",
+  "changePassword": "Modifier le mot de passe",
+  "code": "Code",
+  "codeInvalid": "Code invalide",
+  "deleteRefreshTokens": "Se déconnecter de tous les appareils",
+  "disableTOTP": "Voulez-vous vraiment désactiver vos code temporaire ?",
+  "lastFactor": "Conservez au moins un second facteur.",
+  "emailChangeCodeSent": "Code envoyé à {email}",
+  "mfaRequired": "Authentification à deux facteurs requise",
+  "mfaRequiredDescription": "Configurez une passkey ou une application d'authentification pour terminer la connexion.",
+  "passkeyLimit": "Jusqu'à 4 passkeys",
+  "password": "Mot de passe",
+  "passwordPolicy": "Au moins {count} caractères",
+  "registerPasskey": "Ajouter une passkey",
+  "settings": "Paramètres",
+  "setupTotp": "Utiliser une application d'authentification",
+  "totpSecret": "Scannez ce code QR avec votre application d'authentification ou copiez le code manuellement."
+}

package/nuxt.config.ts

@@ -0,0 +1,54 @@
+// https://nuxt.com/docs/api/configuration/nuxt-config
+const privateRoute = { ssr: false, headers: { 'X-Robots-Tag': 'noindex' } }
+
+export default defineNuxtConfig({
+  routeRules: {
+    '/signin': { ssr: false },
+    '/user/**': { ...privateRoute, appMiddleware: 'authenticated' },
+    '/admin/**': { ...privateRoute, appMiddleware: 'admin' },
+  },
+  app: {
+    head: {
+      htmlAttrs: {
+        lang: 'en',
+      },
+      title: process.env.NUXT_PUBLIC_NAME,
+      link: [],
+      meta: [{ name: 'theme-color', content: '#000000' }],
+    },
+  },
+  runtimeConfig: {
+    public: {
+      url: 'http://localhost:3000',
+      name: 'Nuxt base',
+      logo: 'https://placehold.co/200x100?text=logo',
+    },
+    rateLimit: {
+      routes: {
+        // limit: max requests per IP, window: in seconds
+        '/api/log': { limit: 30, window: 60 },
+        '/api/auth/password': { limit: 5, window: 60 },
+        '/api/auth/otp/get': { limit: 5, window: 900 },
+        '/api/auth/email/get': { limit: 5, window: 900 },
+        '/api/auth/email/verify': { limit: 10, window: 60 },
+        '/api/auth/otp/verify': { limit: 10, window: 60 },
+        '/api/auth/totp/verify': { limit: 10, window: 60 },
+        '/api/auth/webauthn/authenticate': { limit: 10, window: 60 },
+        '/api/auth/anonymous': { limit: 5, window: 3600 },
+      },
+    },
+  },
+  i18n: {
+    locales: [
+      { code: 'en', iso: 'en-US' },
+      { code: 'fr', iso: 'fr-FR' },
+    ],
+    defaultLocale: 'en',
+    translationDir: 'locales',
+  },
+  css: ['~/assets/css/index.css'],
+  compatibilityDate: '2025-07-15',
+  devtools: { enabled: true },
+  srcDir: 'app/',
+  extends: ['./layers/base'],
+})

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "maxibase",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Nuxt layer with auth, files, logs and backups",
+  "keywords": [
+    "nuxt",
+    "nuxt-layer",
+    "auth",
+    "webauthn",
+    "drizzle"
+  ],
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "files": [
+    "docker",
+    "layers/base",
+    "locales",
+    "scripts",
+    "server/assets",
+    "nuxt.config.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maxirozay/nuxt-base.git"
+  },
+  "homepage": "https://github.com/maxirozay/nuxt-base#readme",
+  "bugs": {
+    "url": "https://github.com/maxirozay/nuxt-base/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@12.4.2+sha512.08adc6613180275c7c9edada39dcf08c9c61ad4e7eaf330a4f3461f102b0f907423454d117f98e72d47fef0616070644d7bffc973a6a57f5090a6d7c368b07c9",
+  "scripts": {
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "prod": "./scripts/deploy.sh",
+    "rollback": "./scripts/rollback.sh",
+    "db:seed": "npx jiti ./server/database/seed.ts",
+    "db:generate": "drizzle-kit generate",
+    "db:push": "drizzle-kit push",
+    "db:push-server": "./scripts/db/push-server.sh",
+    "db:restore": "./scripts/db/restore.sh",
+    "db:migrate": "npx jiti ./scripts/db/migrate.ts",
+    "db:studio": "drizzle-kit studio",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "typecheck": "nuxt typecheck",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm lint && pnpm fmt:check && pnpm typecheck && pnpm test"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1146.0",
+    "@aws-sdk/s3-request-presigner": "^3.1146.0",
+    "@iconify-json/lucide": "^1.2.140",
+    "@nuxt/hints": "^1.1.4",
+    "@nuxt/icon": "^2.5.1",
+    "@pinia/nuxt": "^1.0.2",
+    "@simplewebauthn/browser": "^11.0.0",
+    "@simplewebauthn/server": "^11.0.0",
+    "@types/nodemailer": "^8.0.2",
+    "@types/pg": "^8.23.1",
+    "@types/qrcode": "^1.5.6",
+    "drizzle-orm": "1.0.0-rc.3",
+    "goku-css": "^9.0.8",
+    "nodemailer": "^9.1.1",
+    "nuxt-auth-utils": "^0.5.30",
+    "nuxt-i18n-micro": "^3.30.0",
+    "otplib": "^13.5.0",
+    "pg": "^8.23.1",
+    "pinia": "^4.0.3",
+    "qrcode": "^1.5.4",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "drizzle-kit": "1.0.0-rc.3",
+    "drizzle-seed": "1.0.0-rc.3",
+    "maxibase": "link:.",
+    "nuxt": "^4.6.0",
+    "oxfmt": "^0.72.0",
+    "oxlint": "^1.87.0",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.3",
+    "vue-tsc": "^3.3.12"
+  }
+}

package/scripts/db/migrate.ts

@@ -0,0 +1,9 @@
+import { migrate } from 'drizzle-orm/node-postgres/migrator'
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { existsSync } from 'node:fs'
+
+// NUXT_DB from the project's .env, a variable already set in the environment wins
+if (existsSync('.env')) process.loadEnvFile()
+
+const db = drizzle(process.env.NUXT_DB!)
+migrate(db, { migrationsFolder: './server/database/migrations' })

package/scripts/db/push-server.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+set -eo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "$SCRIPT_DIR/../env.sh"
+
+LOCAL_PORT=5433
+REMOTE_PORT=5432
+SSH_KEY="$HOME/.ssh/$SSH_KEY_NAME"
+CONTROL_SOCKET="/tmp/.${PROJECT_NAME}-db-tunnel.$$"
+
+# Master connection, reused for both the tunnel and the credential read, so this
+# authenticates once. -f backgrounds it, -N runs no remote command.
+ssh -M -S "$CONTROL_SOCKET" -f -N -L "$LOCAL_PORT:localhost:$REMOTE_PORT" -i "$SSH_KEY" "$SERVER_URL"
+trap 'ssh -S "$CONTROL_SOCKET" -O exit "$SERVER_URL" 2>/dev/null || true' EXIT
+
+# The app's own connection string is the single source of truth, so there is no second
+# copy of the credentials to keep in sync. Only that one line crosses the wire, and it
+# is never written to disk locally.
+# -n: read no stdin, so this cannot swallow keystrokes meant for drizzle-kit's prompts.
+REMOTE_LINE=$(ssh -n -S "$CONTROL_SOCKET" "$SERVER_URL" "grep -m1 '^NUXT_DB=' $REMOTE_PATH/.env" | tr -d '\r')
+
+if [ -z "$REMOTE_LINE" ]; then
+  echo "No NUXT_DB found in $REMOTE_PATH/.env on $SERVER_URL" >&2
+  exit 1
+fi
+
+# Repoint whatever host the server uses at the local end of the tunnel, leaving the
+# credentials byte-for-byte as the server has them.
+TUNNELED_DB=$(REMOTE_LINE="$REMOTE_LINE" LOCAL_PORT="$LOCAL_PORT" node -p '
+  const raw = process.env.REMOTE_LINE.replace(/^NUXT_DB=/, "").trim().replace(/^["\x27]|["\x27]$/g, "")
+  new URL(raw) // the validation pg-connection-string applies; throws on a malformed URL
+  const m = raw.match(/^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)(.*)$/)
+  const end = m[2].search(/[/?#]/)
+  const authority = end === -1 ? m[2] : m[2].slice(0, end)
+  const tail = end === -1 ? "" : m[2].slice(end)
+  const at = authority.lastIndexOf("@")
+  process.stderr.write(`Pushing schema to ${authority.slice(at + 1)}${tail.split("?")[0]} on ${process.env.SERVER_URL}\n`)
+  if (/ssl/i.test(tail)) process.stderr.write("Note: the connection string sets SSL options, but through the tunnel the host is localhost, so certificate verification may fail. The tunnel is already encrypted.\n")
+  m[1] + authority.slice(0, at + 1) + "localhost:" + process.env.LOCAL_PORT + tail
+')
+
+NUXT_DB="$TUNNELED_DB" pnpm drizzle-kit push
+
+echo "Migration complete!"

package/scripts/db/restore.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -eo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "$SCRIPT_DIR/../env.sh"
+
+BACKUP_PATH="$1"
+if [ -z "$BACKUP_PATH" ]; then
+  echo "Usage: $0 <backup-file> [age-identity-file]"
+  echo "  .age backups need the private key, either as the 2nd argument or in AGE_IDENTITY_FILE."
+  exit 1
+fi
+
+if [[ "$BACKUP_PATH" == *.age ]]; then
+  AGE_IDENTITY_FILE="${2:-$AGE_IDENTITY_FILE}"
+  if [ -z "$AGE_IDENTITY_FILE" ]; then
+    echo "$BACKUP_PATH is encrypted: pass the age identity file (the key.txt holding age-secret-key-...)" >&2
+    exit 1
+  fi
+  # Decrypt straight into pg_restore so the plaintext dump is never written to disk.
+  age -d -i "$AGE_IDENTITY_FILE" "$BACKUP_PATH" | pg_restore --disable-triggers -d "$NUXT_DB"
+else
+  pg_restore --disable-triggers -d "$NUXT_DB" "$BACKUP_PATH"
+fi
+
+echo "Restore complete!"

package/scripts/deploy.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "$SCRIPT_DIR/env.sh"
+
+NAME=$PROJECT_NAME
+SSH_KEY="$HOME/.ssh/$SSH_KEY_NAME"
+TAG="$(date -u +%Y%m%d-%H%M%S)-$(git rev-parse --short HEAD)"
+git diff --quiet HEAD || TAG="$TAG-dirty"
+IMAGE_NAME="$NAME:$TAG"
+
+echo $TAG
+
+# The project's own Dockerfile and compose.yaml, else the package's. The package's Dockerfile
+# brings its own Dockerfile.dockerignore, a project Dockerfile uses the project's .dockerignore.
+DOCKERFILE=Dockerfile
+[ -f "$DOCKERFILE" ] || DOCKERFILE="$SCRIPT_DIR/../docker/Dockerfile"
+COMPOSE=compose.yaml
+[ -f "$COMPOSE" ] || COMPOSE="$SCRIPT_DIR/../docker/compose.yaml"
+
+docker build --platform linux/amd64 -f "$DOCKERFILE" -t $IMAGE_NAME .
+docker save $IMAGE_NAME > $NAME.tar
+
+scp -i $SSH_KEY $NAME.tar "$COMPOSE" $SERVER_URL:$REMOTE_PATH
+scp -i $SSH_KEY "$SCRIPT_DIR/remote/switch.sh" $SERVER_URL:$REMOTE_PATH/switch.sh
+ssh -i $SSH_KEY $SERVER_URL "
+  cd $REMOTE_PATH && \
+  sudo docker load < $NAME.tar && \
+  rm -f $NAME.tar && \
+  bash switch.sh $NAME $TAG
+"
+rm -f $NAME.tar
+docker rmi $IMAGE_NAME

package/scripts/env.sh

@@ -0,0 +1,20 @@
+ROOT_DIR=$(pwd)
+ENV_FILE="$ROOT_DIR/.env"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -e|--env)
+      ENV_FILE="$ROOT_DIR/$2"
+      shift 2
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+set -a
+if [ -f "$ENV_FILE" ]; then
+  . "$ENV_FILE"
+fi
+set +a

package/scripts/remote/switch.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Runs on the server, from the project folder. Recreates the app container from an image
+# still on the server; deploy.sh and rollback.sh both go through it.
+#
+#   switch.sh <name> <tag>       run <name>:<tag>
+#   switch.sh <name> previous    run the image deployed before the live one
+#   switch.sh <name> --list      list the images that can be run
+set -euo pipefail
+
+NAME="$1"
+TAG="$2"
+KEEP=5
+
+CURRENT=$(cat .active-tag 2>/dev/null || true)
+# Tags start with a UTC timestamp, so newest first is a plain reverse sort.
+TAGS=$(sudo docker images "$NAME" --format '{{.Tag}}' | grep -v '^latest$' | sort -r || true)
+
+if [ "$TAG" = "--list" ]; then
+  echo "$TAGS" | sed "${CURRENT:+s/^$CURRENT\$/& (live)/}"
+  exit 0
+fi
+
+if [ "$TAG" = "previous" ]; then
+  if [ -z "$CURRENT" ]; then
+    echo "No live version recorded yet, pass a tag (--list shows them)" >&2
+    exit 1
+  fi
+  TAG=$(echo "$TAGS" | grep -A1 -x "$CURRENT" | sed -n 2p)
+  if [ -z "$TAG" ]; then
+    echo "No image older than $CURRENT is left on the server" >&2
+    exit 1
+  fi
+fi
+
+if ! sudo docker image inspect "$NAME:$TAG" > /dev/null 2>&1; then
+  echo "Image $NAME:$TAG is not on the server (--list shows the ones that are)" >&2
+  exit 1
+fi
+
+echo "Running $NAME:$TAG (was: ${CURRENT:-unknown})"
+sudo docker tag "$NAME:$TAG" "$NAME:latest"
+sudo docker compose up -d --force-recreate
+echo "$TAG" > .active-tag
+
+# Images in use are refused by rmi, so the live one always survives.
+echo "$TAGS" | tail -n +$((KEEP + 1)) | xargs -r -I {} sudo docker rmi "$NAME:{}" > /dev/null 2>&1 || true
+
+echo "Live: $NAME:$TAG"