Refactor Study Desk application structure

scripts/backup-database.mjs

@@ -0,0 +1,42 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import Database from "better-sqlite3";
+import { databasePathFromUrl } from "./databasePath.mjs";
+
+function argument(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+export async function backupDatabase(sourcePath, outputPath) {
+  const source = path.resolve(sourcePath);
+  const output = path.resolve(outputPath);
+  if (!existsSync(source)) throw new Error(`Source database does not exist: ${source}`);
+  if (existsSync(output)) throw new Error(`Backup destination already exists: ${output}`);
+  if (source === output) throw new Error("Backup destination must differ from source");
+
+  const database = new Database(source, { readonly: true, fileMustExist: true });
+  try {
+    await database.backup(output);
+  } finally {
+    database.close();
+  }
+
+  const backup = new Database(output, { readonly: true, fileMustExist: true });
+  try {
+    const integrity = backup.pragma("integrity_check", { simple: true });
+    if (integrity !== "ok") throw new Error(`Backup integrity check failed: ${integrity}`);
+  } finally {
+    backup.close();
+  }
+  return output;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const source = argument("--source") ?? databasePathFromUrl(process.env.DATABASE_URL);
+  const output = argument("--output");
+  if (!output) throw new Error("Usage: npm run db:backup -- --output <new-backup.db>");
+  const completedPath = await backupDatabase(source, output);
+  console.info(`Verified SQLite backup created: ${completedPath}`);
+}

scripts/databasePath.mjs

@@ -0,0 +1,10 @@
+import path from "node:path";
+
+export function databasePathFromUrl(databaseUrl, cwd = process.cwd()) {
+  if (!databaseUrl?.startsWith("file:")) {
+    throw new Error("DATABASE_URL must be a file: SQLite URL");
+  }
+  const rawPath = databaseUrl.slice("file:".length).split("?")[0];
+  if (!rawPath) throw new Error("DATABASE_URL does not contain a database path");
+  return path.resolve(cwd, rawPath);
+}

scripts/migration-preflight.mjs

@@ -0,0 +1,312 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import Database from "better-sqlite3";
+import { databasePathFromUrl } from "./databasePath.mjs";
+
+export const GROUP_MIGRATION = "20260807090000_add_material_groups";
+
+function tableExists(database, table) {
+  return Boolean(
+    database
+      .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?")
+      .get(table)
+  );
+}
+
+function hasColumn(database, table, column) {
+  if (!tableExists(database, table)) return false;
+  return database.pragma(`table_info(${table})`).some((item) => item.name === column);
+}
+
+function hasForeignKey(database, table, from, target, onDelete) {
+  return database
+    .pragma(`foreign_key_list(${table})`)
+    .some(
+      (item) =>
+        item.from === from && item.table === target && item.on_delete === onDelete
+    );
+}
+
+function hasUniqueIndex(database, table, indexName, column) {
+  const index = database
+    .pragma(`index_list(${table})`)
+    .find((item) => item.name === indexName && item.unique === 1);
+  if (!index) return false;
+  const columns = database.pragma(`index_info(${indexName})`);
+  return columns.length === 1 && columns[0].name === column;
+}
+
+function schemaSnapshot(database) {
+  const tables = database
+    .prepare(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name <> '_prisma_migrations' ORDER BY name"
+    )
+    .all()
+    .map((row) => row.name);
+
+  return tables.map((table) => ({
+    table,
+    columns: database.pragma(`table_info(${JSON.stringify(table)})`).map((column) => ({
+      name: column.name,
+      type: column.type,
+      notnull: column.notnull,
+      defaultValue: column.dflt_value,
+      primaryKey: column.pk,
+    })),
+    foreignKeys: database
+      .pragma(`foreign_key_list(${JSON.stringify(table)})`)
+      .map((foreignKey) => ({
+        id: foreignKey.id,
+        sequence: foreignKey.seq,
+        target: foreignKey.table,
+        from: foreignKey.from,
+        to: foreignKey.to,
+        onUpdate: foreignKey.on_update,
+        onDelete: foreignKey.on_delete,
+        match: foreignKey.match,
+      }))
+      .sort((left, right) => left.id - right.id || left.sequence - right.sequence),
+    indexes: database
+      .pragma(`index_list(${JSON.stringify(table)})`)
+      .filter((index) => !index.name.startsWith("sqlite_autoindex_"))
+      .map((index) => ({
+        name: index.name,
+        unique: index.unique,
+        partial: index.partial,
+        columns: database
+          .pragma(`index_info(${JSON.stringify(index.name)})`)
+          .map((column) => column.name),
+      }))
+      .sort((left, right) => left.name.localeCompare(right.name)),
+  }));
+}
+
+function expectedSchemaSnapshot(migrationNames) {
+  const database = new Database(":memory:");
+  try {
+    database.pragma("foreign_keys = ON");
+    for (const migrationName of migrationNames) {
+      database.exec(
+        readFileSync(
+          path.join(
+            process.cwd(),
+            "prisma",
+            "migrations",
+            migrationName,
+            "migration.sql"
+          ),
+          "utf8"
+        )
+      );
+    }
+    return schemaSnapshot(database);
+  } finally {
+    database.close();
+  }
+}
+
+export function inspectMigrationState(databasePath) {
+  if (!existsSync(databasePath)) {
+    throw new Error(`Database does not exist: ${databasePath}`);
+  }
+  const database = new Database(databasePath, { readonly: true, fileMustExist: true });
+  try {
+    const migrationNames = tableExists(database, "_prisma_migrations")
+      ? database
+          .prepare(
+            'SELECT "migration_name" FROM "_prisma_migrations" WHERE "finished_at" IS NOT NULL AND "rolled_back_at" IS NULL'
+          )
+          .all()
+          .map((row) => row.migration_name)
+      : [];
+    const committedMigrations = readdirSync(
+      path.join(process.cwd(), "prisma", "migrations"),
+      { withFileTypes: true }
+    )
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+    const priorMigrations = committedMigrations.filter(
+      (name) => name < GROUP_MIGRATION
+    );
+    const laterMigrations = committedMigrations.filter(
+      (name) => name > GROUP_MIGRATION
+    );
+
+    const artifacts = {
+      materialGroup: tableExists(database, "MaterialGroup"),
+      deckColumn: hasColumn(database, "Deck", "groupId"),
+      quizColumn: hasColumn(database, "QuizSet", "groupId"),
+      shareColumn: hasColumn(database, "ShareLink", "groupId"),
+      deckForeignKey: hasForeignKey(
+        database,
+        "Deck",
+        "groupId",
+        "MaterialGroup",
+        "SET NULL"
+      ),
+      quizForeignKey: hasForeignKey(
+        database,
+        "QuizSet",
+        "groupId",
+        "MaterialGroup",
+        "SET NULL"
+      ),
+      shareForeignKey: hasForeignKey(
+        database,
+        "ShareLink",
+        "groupId",
+        "MaterialGroup",
+        "CASCADE"
+      ),
+      shareUnique: hasUniqueIndex(
+        database,
+        "ShareLink",
+        "ShareLink_groupId_key",
+        "groupId"
+      ),
+    };
+    const values = Object.values(artifacts);
+    const groupArtifactsPresent = values.every(Boolean);
+    const groupArtifactsAbsent = values.every((value) => !value);
+    const groupMigrationApplied = migrationNames.includes(GROUP_MIGRATION);
+    const priorHistoryComplete = priorMigrations.every((name) =>
+      migrationNames.includes(name)
+    );
+    const knownMigrationNames = new Set(committedMigrations);
+    const historyHasUnknown = migrationNames.some(
+      (name) => !knownMigrationNames.has(name)
+    );
+    const laterHistoryPresent = laterMigrations.some((name) =>
+      migrationNames.includes(name)
+    );
+    const actualSchema = schemaSnapshot(database);
+    const matches = (expected) =>
+      JSON.stringify(actualSchema) === JSON.stringify(expected);
+    const preGroupSchemaExact = matches(expectedSchemaSnapshot(priorMigrations));
+    const adoptedGroupSchemaExact = matches(
+      expectedSchemaSnapshot([...priorMigrations, GROUP_MIGRATION])
+    );
+    const appliedPrefix = committedMigrations.filter((name, index) =>
+      committedMigrations.slice(0, index + 1).every((candidate) =>
+        migrationNames.includes(candidate)
+      )
+    );
+    const appliedHistoryExact =
+      !historyHasUnknown &&
+      migrationNames.length === appliedPrefix.length &&
+      migrationNames.every((name) => appliedPrefix.includes(name));
+    const trackedSchemaExact =
+      appliedHistoryExact && matches(expectedSchemaSnapshot(appliedPrefix));
+
+    let classification = "CONFLICT";
+    if (groupMigrationApplied && trackedSchemaExact) classification = "CURRENT";
+    else if (
+      !groupMigrationApplied &&
+      !laterHistoryPresent &&
+      priorHistoryComplete &&
+      migrationNames.length === priorMigrations.length &&
+      groupArtifactsAbsent &&
+      preGroupSchemaExact
+    ) classification = "APPLY";
+    else if (
+      !groupMigrationApplied &&
+      !laterHistoryPresent &&
+      priorHistoryComplete &&
+      migrationNames.length === priorMigrations.length &&
+      groupArtifactsPresent &&
+      adoptedGroupSchemaExact
+    ) classification = "ADOPT";
+
+    return {
+      classification,
+      artifacts,
+      migrationNames,
+      priorHistoryComplete,
+      exactSchema: {
+        preGroup: preGroupSchemaExact,
+        adoptedGroup: adoptedGroupSchemaExact,
+        tracked: trackedSchemaExact,
+      },
+    };
+  } finally {
+    database.close();
+  }
+}
+
+function verifyBackup(backupPath, sourcePath) {
+  if (!backupPath || !existsSync(backupPath)) {
+    throw new Error("--resolve requires an existing verified --backup file");
+  }
+  if (path.resolve(backupPath) === path.resolve(sourcePath)) {
+    throw new Error("--backup must be a separate database file, not the source database");
+  }
+  const backup = new Database(backupPath, { readonly: true, fileMustExist: true });
+  const source = new Database(sourcePath, { readonly: true, fileMustExist: true });
+  try {
+    if (backup.pragma("integrity_check", { simple: true }) !== "ok") {
+      throw new Error("Backup failed SQLite integrity_check");
+    }
+    if (JSON.stringify(schemaSnapshot(backup)) !== JSON.stringify(schemaSnapshot(source))) {
+      throw new Error("Backup schema does not match the source database");
+    }
+    const sourceCounts = Object.fromEntries(
+      schemaSnapshot(source).map(({ table }) => [
+        table,
+        source.prepare(`SELECT COUNT(*) AS count FROM ${JSON.stringify(table)}`).get().count,
+      ])
+    );
+    const backupCounts = Object.fromEntries(
+      schemaSnapshot(backup).map(({ table }) => [
+        table,
+        backup.prepare(`SELECT COUNT(*) AS count FROM ${JSON.stringify(table)}`).get().count,
+      ])
+    );
+    if (JSON.stringify(sourceCounts) !== JSON.stringify(backupCounts)) {
+      throw new Error("Backup row counts do not match the source database");
+    }
+  } finally {
+    backup.close();
+    source.close();
+  }
+}
+
+function resolveMigration(databaseUrl) {
+  const cli = path.join(process.cwd(), "node_modules", "prisma", "build", "index.js");
+  const result = spawnSync(
+    process.execPath,
+    [cli, "migrate", "resolve", "--applied", GROUP_MIGRATION],
+    {
+      cwd: process.cwd(),
+      env: { ...process.env, DATABASE_URL: databaseUrl },
+      encoding: "utf8",
+    }
+  );
+  if (result.status !== 0) {
+    throw new Error(`Prisma migration resolve failed:\n${result.stdout}\n${result.stderr}`);
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const databaseUrl = process.env.DATABASE_URL;
+  const databasePath = databasePathFromUrl(databaseUrl);
+  const state = inspectMigrationState(databasePath);
+  console.info(JSON.stringify(state, null, 2));
+
+  if (process.argv.includes("--resolve")) {
+    if (state.classification !== "ADOPT") {
+      throw new Error(`Refusing adoption for ${state.classification} database state`);
+    }
+    const backupIndex = process.argv.indexOf("--backup");
+    verifyBackup(
+      backupIndex >= 0 ? process.argv[backupIndex + 1] : undefined,
+      databasePath
+    );
+    resolveMigration(databaseUrl);
+    console.info(`Marked ${GROUP_MIGRATION} applied after exact-schema preflight.`);
+  } else if (state.classification === "CONFLICT") {
+    process.exitCode = 2;
+  }
+}

scripts/request-password-reset.mjs

@@ -0,0 +1,56 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import Database from "better-sqlite3";
+import { databasePathFromUrl } from "./databasePath.mjs";
+
+const PASSWORD_HASH_KEY = "admin_password_hash";
+const RESET_TOKEN_KEY = "admin_password_reset";
+const RESET_TOKEN_LIFETIME_MS = 15 * 60 * 1000;
+
+function activeRecord(value) {
+  try {
+    const record = JSON.parse(value);
+    return new Date(record.expiresAt).getTime() > Date.now();
+  } catch {
+    return false;
+  }
+}
+
+export function createResetToken(databasePath) {
+  if (!existsSync(databasePath)) throw new Error(`Database does not exist: ${databasePath}`);
+  const database = new Database(databasePath, { fileMustExist: true });
+  try {
+    if (!database.prepare('SELECT 1 FROM "Setting" WHERE "key" = ?').get(PASSWORD_HASH_KEY)) {
+      throw new Error("Password recovery is unavailable before initial setup");
+    }
+    const existing = database
+      .prepare('SELECT "value" FROM "Setting" WHERE "key" = ?')
+      .get(RESET_TOKEN_KEY);
+    if (existing && activeRecord(existing.value)) {
+      throw new Error("An unexpired reset token already exists; it was not replaced");
+    }
+
+    const token = randomBytes(24).toString("base64url");
+    const expiresAt = new Date(Date.now() + RESET_TOKEN_LIFETIME_MS).toISOString();
+    const value = JSON.stringify({
+      digest: createHash("sha256").update(token, "utf8").digest("hex"),
+      nonce: randomUUID(),
+      expiresAt,
+    });
+    database
+      .prepare(
+        'INSERT INTO "Setting" ("key", "value") VALUES (?, ?) ON CONFLICT("key") DO UPDATE SET "value" = excluded."value"'
+      )
+      .run(RESET_TOKEN_KEY, value);
+    return { token, expiresAt };
+  } finally {
+    database.close();
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = createResetToken(databasePathFromUrl(process.env.DATABASE_URL));
+  console.info(`Password reset token: ${result.token}`);
+  console.info(`Expires: ${result.expiresAt}`);
+}

scripts/verify-backup-restore.mjs

@@ -0,0 +1,197 @@
+import { randomUUID } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import path from "node:path";
+import Database from "better-sqlite3";
+import { backupDatabase } from "./backup-database.mjs";
+
+const root = path.join(process.cwd(), ".test-databases");
+const directory = path.join(root, `backup-restore-${randomUUID()}`);
+if (!path.resolve(directory).startsWith(`${path.resolve(root)}${path.sep}`)) {
+  throw new Error("Unsafe disposable backup verification path");
+}
+mkdirSync(directory, { recursive: true });
+const sourcePath = path.join(directory, "source.test.db");
+const backupPath = path.join(directory, "backup.test.db");
+const restoredPath = path.join(directory, "restored.test.db");
+let source;
+
+function rowCounts(database) {
+  const tables = database
+    .prepare(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+    )
+    .all()
+    .map((row) => row.name);
+  return Object.fromEntries(
+    tables.map((table) => [
+      table,
+      database.prepare(`SELECT COUNT(*) AS count FROM ${JSON.stringify(table)}`).get().count,
+    ])
+  );
+}
+
+try {
+  source = new Database(sourcePath);
+  source.pragma("foreign_keys = ON");
+  source.pragma("journal_mode = WAL");
+  source.pragma("wal_autocheckpoint = 0");
+  const migrations = readdirSync(path.join(process.cwd(), "prisma", "migrations"), {
+    withFileTypes: true,
+  })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+  for (const migration of migrations) {
+    source.exec(
+      readFileSync(
+        path.join(process.cwd(), "prisma", "migrations", migration, "migration.sql"),
+        "utf8"
+      )
+    );
+  }
+  source.transaction(() => {
+    source
+      .prepare('INSERT INTO "Class" ("id", "name", "slug", "sortOrder") VALUES (?, ?, ?, ?)')
+      .run("backup-class", "Representative content", "representative-content", 0);
+    source
+      .prepare(
+        'INSERT INTO "MaterialGroup" ("id", "classId", "name", "type", "sortOrder") VALUES (?, ?, ?, ?, ?)'
+      )
+      .run("backup-group", "backup-class", "Backup group", "DECK", 0);
+    source
+      .prepare(
+        'INSERT INTO "Deck" ("id", "classId", "groupId", "name", "description", "sortOrder") VALUES (?, ?, ?, ?, ?, ?)'
+      )
+      .run(
+        "backup-deck",
+        "backup-class",
+        "backup-group",
+        "Backup deck",
+        "Restore drill content",
+        0
+      );
+    source
+      .prepare(
+        'INSERT INTO "Flashcard" ("id", "deckId", "front", "back", "sortOrder") VALUES (?, ?, ?, ?, ?)'
+      )
+      .run("backup-card", "backup-deck", "Representative front", "Representative back", 0);
+    source
+      .prepare(
+        'INSERT INTO "QuizSet" ("id", "classId", "name", "description", "sortOrder") VALUES (?, ?, ?, ?, ?)'
+      )
+      .run("backup-quiz", "backup-class", "Backup quiz", "Quiz relationship", 0);
+    source
+      .prepare(
+        'INSERT INTO "Question" ("id", "quizSetId", "type", "prompt", "rationale", "category", "sortOrder") VALUES (?, ?, ?, ?, ?, ?, ?)'
+      )
+      .run(
+        "backup-question",
+        "backup-quiz",
+        "MULTIPLE_CHOICE",
+        "Representative prompt",
+        "Representative rationale",
+        "backup",
+        0
+      );
+    source
+      .prepare(
+        'INSERT INTO "AnswerOption" ("id", "questionId", "text", "isCorrect", "sortOrder") VALUES (?, ?, ?, ?, ?)'
+      )
+      .run("backup-option", "backup-question", "Correct option", 1, 0);
+    source
+      .prepare(
+        'INSERT INTO "SpacedRepetitionSet" ("id", "classId", "name", "sortOrder", "updatedAt") VALUES (?, ?, ?, ?, ?)'
+      )
+      .run("backup-srs", "backup-class", "Backup SRS", 0, Date.now());
+    source
+      .prepare(
+        'INSERT INTO "SpacedRepetitionSetDeck" ("setId", "deckId", "sortOrder") VALUES (?, ?, ?)'
+      )
+      .run("backup-srs", "backup-deck", 0);
+    source
+      .prepare(
+        'INSERT INTO "ShareLink" ("id", "targetType", "groupId") VALUES (?, ?, ?)'
+      )
+      .run("backup-share", "GROUP", "backup-group");
+  })();
+
+  const walPath = `${sourcePath}-wal`;
+  if (!existsSync(walPath) || statSync(walPath).size === 0) {
+    throw new Error("Backup drill did not create an active WAL database");
+  }
+  const sourceWalBytes = statSync(walPath).size;
+  const sourceCounts = rowCounts(source);
+  await backupDatabase(sourcePath, backupPath);
+  copyFileSync(backupPath, restoredPath);
+  source.close();
+  source = undefined;
+
+  const restored = new Database(restoredPath, { readonly: true, fileMustExist: true });
+  try {
+    const integrity = restored.pragma("integrity_check", { simple: true });
+    const foreignKeyErrors = restored.pragma("foreign_key_check");
+    const restoredCounts = rowCounts(restored);
+    const representative = restored
+      .prepare(`
+        SELECT c.name AS className, g.name AS groupName, d.description,
+               f.front, s.name AS setName, sl.targetType
+        FROM "Class" c
+        JOIN "MaterialGroup" g ON g.classId = c.id
+        JOIN "Deck" d ON d.groupId = g.id
+        JOIN "Flashcard" f ON f.deckId = d.id
+        JOIN "SpacedRepetitionSetDeck" sd ON sd.deckId = d.id
+        JOIN "SpacedRepetitionSet" s ON s.id = sd.setId
+        JOIN "ShareLink" sl ON sl.groupId = g.id
+        WHERE d.id = ?
+      `)
+      .get("backup-deck");
+    const quizRelationship = restored
+      .prepare(`
+        SELECT q.name AS quizName, question.prompt, option.text, option.isCorrect
+        FROM "QuizSet" q
+        JOIN "Question" question ON question.quizSetId = q.id
+        JOIN "AnswerOption" option ON option.questionId = question.id
+        WHERE q.id = ?
+      `)
+      .get("backup-quiz");
+    if (
+      integrity !== "ok" ||
+      foreignKeyErrors.length !== 0 ||
+      JSON.stringify(restoredCounts) !== JSON.stringify(sourceCounts) ||
+      representative?.description !== "Restore drill content" ||
+      representative?.setName !== "Backup SRS" ||
+      representative?.targetType !== "GROUP" ||
+      quizRelationship?.isCorrect !== 1
+    ) {
+      throw new Error("Restored database did not preserve integrity, counts, content, and relationships");
+    }
+    console.info(
+      JSON.stringify(
+        {
+          method: "better-sqlite3 online backup while the WAL source remained open",
+          sourceWalBytes,
+          integrity,
+          foreignKeyErrors,
+          counts: restoredCounts,
+          representative,
+          quizRelationship,
+        },
+        null,
+        2
+      )
+    );
+  } finally {
+    restored.close();
+  }
+} finally {
+  source?.close();
+  rmSync(directory, { recursive: true, force: true });
+}

scripts/verify-http-smoke.mjs

@@ -0,0 +1,83 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import Database from "better-sqlite3";
+
+const root = path.join(process.cwd(), ".test-databases");
+const directory = path.join(root, `http-smoke-${randomUUID()}`);
+if (!path.resolve(directory).startsWith(`${path.resolve(root)}${path.sep}`)) {
+  throw new Error("Unsafe disposable HTTP smoke path");
+}
+mkdirSync(directory, { recursive: true });
+const databasePath = path.join(directory, "http-smoke.test.db");
+const database = new Database(databasePath);
+try {
+  database.pragma("foreign_keys = ON");
+  for (const migration of readdirSync(path.join(process.cwd(), "prisma", "migrations"), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()) {
+    database.exec(readFileSync(path.join(process.cwd(), "prisma", "migrations", migration, "migration.sql"), "utf8"));
+  }
+} finally {
+  database.close();
+}
+
+const port = 3789;
+const server = spawn(
+  process.execPath,
+  [path.join(process.cwd(), "node_modules", "next", "dist", "bin", "next"), "start", "-p", String(port)],
+  {
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      NODE_ENV: "production",
+      DATABASE_URL: `file:${databasePath.replaceAll("\\", "/")}`,
+      SESSION_SECRET: "http-smoke-secret-0123456789abcdef0123456789",
+      ALLOW_INITIAL_SETUP: "true",
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  }
+);
+let output = "";
+server.stdout.on("data", (chunk) => { output += chunk.toString(); });
+server.stderr.on("data", (chunk) => { output += chunk.toString(); });
+
+try {
+  let health;
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    try {
+      health = await fetch(`http://127.0.0.1:${port}/api/health`);
+      if (health.ok) break;
+    } catch {}
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  if (!health?.ok) throw new Error(`Health check did not become ready.\n${output}`);
+  const login = await fetch(`http://127.0.0.1:${port}/login`);
+  const setup = await fetch(`http://127.0.0.1:${port}/api/auth/setup-status`);
+  const setupBody = await setup.json();
+  const protectedDot = await fetch(`http://127.0.0.1:${port}/api/decks/file.json`, { redirect: "manual" });
+  if (!login.ok || !setup.ok || setupBody.setupRequired !== true || setupBody.setupAllowed !== true || protectedDot.status !== 307) {
+    throw new Error("HTTP smoke responses did not match the production contract");
+  }
+  console.info(JSON.stringify({
+    health: health.status,
+    login: login.status,
+    setup: setupBody,
+    protectedDot: { status: protectedDot.status, location: protectedDot.headers.get("location") },
+  }, null, 2));
+  if (process.argv.includes("--stay")) {
+    console.info(`Browser smoke server ready at http://127.0.0.1:${port}/login`);
+    await new Promise(() => {});
+  }
+} finally {
+  server.kill();
+  await new Promise((resolve) => {
+    if (server.exitCode !== null) return resolve();
+    server.once("exit", resolve);
+    setTimeout(resolve, 2_000);
+  });
+  rmSync(directory, { recursive: true, force: true });
+}