v2026.08.01

AGENTS.md

@@ -29,6 +29,7 @@
 │   ├── entry-server.tsx       # SSR rendering (renderToPipeableStream)
 │   ├── database/
 │   │   ├── schema.sql         # SQLite schema — source of truth for DB structure
+│   │   ├── migrations/        # Forward-only migration scripts (production)
 │   │   └── seeder.sql         # Test/seed data
 │   ├── express/
 │   │   ├── routes.ts          # Registers all Express modules via importAndUse()
@@ -60,19 +61,17 @@
 ```bash
 npm install
 cp .env.sample .env
-npm run database:sync      # Load schema + seed data into SQLite
+npm run database:reset      # Drop all, replay schema + migrations + seeder
 npm run dev                # Start dev server (Express + Vite together on port 5173)
 ```
 
 ### Database
 
 ```bash
-npm run database:schema:load          # Apply schema.sql to the SQLite file
-npm run database:seeder:load          # Load seeder.sql test data
-npm run database:sync                 # Both above — resets DB to a clean state
-npm run database:sync -- -n           # Non-interactive (CI/CD — skips confirmation prompt)
-npm run database:schema:load -- -n    # Same, schema only
-npm run database:seeder:load -- -n    # Same, seeder only
+npm run database:reset                # Drop all, replay schema + migrations + seeder
+npm run database:reset -- -n          # Non-interactive (CI/CD — skips confirmation prompt)
+npm run database:migrate              # Apply un-applied migrations (production)
+npm run database:migrate -- -n        # Non-interactive (CI/CD)
 ```
 
 > SQLite requires NO Docker, NO connection string, NO async setup. The DB file is created on the fly.

README.fr-FR.md

@@ -50,7 +50,7 @@ cd mon-projet
 # 2. Installer les dépendances et initialiser la base de données
 npm install
 cp .env.sample .env
-npm run database:sync
+npm run database:reset
 
 # 3. Lancer l'application
 npm run dev

README.md

@@ -49,7 +49,7 @@ cd my-prototype
 # 2. Install dependencies and initialize the database
 npm install
 cp .env.sample .env
-npm run database:sync
+npm run database:reset
 
 # 3. Start co-creating
 npm run dev

package.json

@@ -13,9 +13,8 @@
     "build": "npm run build:client && npm run build:server",
     "build:client": "vite build --outDir dist/client",
     "build:server": "vite build --outDir dist/server --ssr src/entry-server",
-    "database:schema:load": "tsx --env-file=.env scripts/database-sync schema",
-    "database:seeder:load": "tsx --env-file=.env scripts/database-sync seeder",
-    "database:sync": "tsx --env-file=.env scripts/database-sync both",
+    "database:migrate": "tsx --env-file=.env scripts/database-migrate",
+    "database:reset": "tsx --env-file=.env scripts/database-reset",
     "dev": "tsx watch --include .env --env-file=.env server",
     "install:check": "vitest run tests/install",
     "make:clone": "tsx  --env-file=.env scripts/make-clone",

scripts/database-helpers.ts

@@ -0,0 +1,109 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import type { DatabaseSync } from "node:sqlite";
+
+/**
+ * Scans `src/database/` for all SQL files in the correct execution order:
+ * 1. `schema.sql` (always first)
+ * 2. migration files in `migrations/` (alphabetical order)
+ * 3. `seeder.sql` (always last)
+ *
+ * Missing files or directories are silently skipped.
+ */
+export function scanDatabaseFiles(rootDir: string): string[] {
+  const databaseDir = path.join(rootDir, "src/database");
+
+  const files: string[] = [];
+
+  // 1. schema.sql first
+  const schemaFile = path.join(databaseDir, "schema.sql");
+  if (fs.existsSync(schemaFile)) {
+    files.push(schemaFile);
+  }
+
+  // 2. migration files in alphabetical order
+  const migrationsDir = path.join(databaseDir, "migrations");
+  if (fs.existsSync(migrationsDir)) {
+    const migrationFiles = fs
+      .readdirSync(migrationsDir)
+      .filter((f) => f.endsWith(".sql"))
+      .sort()
+      .map((f) => path.join(migrationsDir, f));
+
+    files.push(...migrationFiles);
+  }
+
+  // 3. seeder.sql last
+  const seederFile = path.join(databaseDir, "seeder.sql");
+  if (fs.existsSync(seederFile)) {
+    files.push(seederFile);
+  }
+
+  return files;
+}
+
+/**
+ * Same as scanDatabaseFiles but excludes seeder.sql.
+ * Used by `database:migrate` (production) and test infrastructure.
+ */
+export function scanMigrationFiles(rootDir: string): string[] {
+  return scanDatabaseFiles(rootDir).filter(
+    (f) => path.basename(f) !== "seeder.sql",
+  );
+}
+
+/**
+ * Computes the SHA-256 checksum of a file's content.
+ */
+export function computeChecksum(content: string): string {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+/**
+ * Drops all user-created tables from the database.
+ * Temporarily disables foreign keys to avoid cascade errors during drop.
+ */
+export function dropAllTables(database: DatabaseSync): void {
+  const existingTables = database
+    .prepare(
+      "select name from sqlite_schema where type ='table' and name not like 'sqlite_%'",
+    )
+    .all();
+
+  // Prevent errors because of cascade deletion
+  database.exec("PRAGMA foreign_keys = OFF");
+
+  for (const table of existingTables) {
+    database.exec(`drop table "${table.name}"`);
+  }
+
+  // Re-enable cascade deletion
+  database.exec("PRAGMA foreign_keys = ON");
+}
+
+/**
+ * Ensures the _migrations tracking table exists.
+ */
+export function ensureMigrationsTable(database: DatabaseSync): void {
+  database.exec(`
+    create table if not exists _migrations (
+      filename text primary key,
+      checksum text not null,
+      applied_at datetime default current_timestamp
+    );
+  `);
+}
+
+/**
+ * Records an executed SQL file in the _migrations table.
+ */
+export function recordMigration(
+  database: DatabaseSync,
+  filename: string,
+  checksum: string,
+): void {
+  database
+    .prepare("insert into _migrations (filename, checksum) values (?, ?)")
+    .run(filename, checksum);
+}

scripts/database-migrate.ts

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import database from "../src/database";
+import {
+  computeChecksum,
+  ensureMigrationsTable,
+  recordMigration,
+  scanMigrationFiles,
+} from "./database-helpers";
+
+export async function main(
+  argv: string[] = process.argv,
+  rootDirOverride?: string,
+) {
+  const rootDir = rootDirOverride ?? path.join(import.meta.dirname, "..");
+
+  const databaseFile = database.location() ?? ":memory:";
+
+  const args = argv.slice(2);
+
+  const noInteraction =
+    args.includes("--no-interaction") || args.includes("-n");
+
+  const expectedArgs = noInteraction ? ["--no-interaction"] : [];
+
+  if (args.length !== expectedArgs.length) {
+    throw new Error("Usage: database-migrate [--no-interaction|-n]");
+  }
+
+  // Back up the database file (temporary: deleted after migration)
+  const backupFile = `${databaseFile}.bak`;
+  const isFileDatabase = databaseFile !== ":memory:";
+
+  if (isFileDatabase) {
+    fs.copyFileSync(databaseFile, backupFile);
+    console.info(`\nBackup created: '${path.normalize(backupFile)}'`);
+  }
+
+  // Ensure the _migrations tracking table exists
+  ensureMigrationsTable(database);
+
+  // Scan all SQL files (schema + migrations, excluding seeder)
+  const files = scanMigrationFiles(rootDir);
+
+  // Check which files have already been applied
+  const applied = new Map<string, string>();
+  const rows = database
+    .prepare("select filename, checksum from _migrations")
+    .all() as { filename: string; checksum: string }[];
+
+  for (const row of rows) {
+    applied.set(row.filename, row.checksum);
+  }
+
+  // Determine which files need to be applied
+  const pending: { file: string; sql: string }[] = [];
+
+  for (const file of files) {
+    const sql = fs.readFileSync(file, "utf8");
+    const filename = path.basename(file);
+    const currentChecksum = computeChecksum(sql);
+
+    if (applied.has(filename)) {
+      const storedChecksum = applied.get(filename);
+
+      if (storedChecksum !== currentChecksum) {
+        console.warn(
+          `\n⚠️  '${filename}' was modified since it was applied. These changes will NOT take effect. Revert your change or write a new migration script.`,
+        );
+      }
+    } else {
+      pending.push({ file, sql });
+    }
+  }
+
+  if (pending.length === 0) {
+    console.info("\nNothing to migrate. Database is up to date. ✅");
+
+    // Clean up backup
+    if (isFileDatabase && fs.existsSync(backupFile)) {
+      fs.unlinkSync(backupFile);
+    }
+
+    return;
+  }
+
+  // Confirm before applying
+  console.info(`\n${pending.length} file(s) to apply:`);
+  for (const { file } of pending) {
+    console.info(`  - ${path.basename(file)}`);
+  }
+
+  if (!noInteraction) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    try {
+      const answer = await rl.question("\nApply these migrations? (y/N) ");
+
+      if (answer.toLowerCase() !== "y") {
+        console.info("\nMigration cancelled.");
+
+        // Clean up backup
+        if (isFileDatabase && fs.existsSync(backupFile)) {
+          fs.unlinkSync(backupFile);
+        }
+
+        return;
+      }
+    } finally {
+      rl.close();
+    }
+  }
+
+  // Apply pending files inside a transaction
+  try {
+    database.exec("BEGIN");
+
+    for (const { file, sql } of pending) {
+      database.exec(sql);
+
+      const filename = path.basename(file);
+      const checksum = computeChecksum(sql);
+      recordMigration(database, filename, checksum);
+
+      console.info(
+        `\n'${filename}' applied to '${path.normalize(databaseFile)}' ✅`,
+      );
+    }
+
+    database.exec("COMMIT");
+
+    console.info("\nMigration complete! ✅");
+  } catch (error) {
+    // Rollback the transaction
+    try {
+      database.exec("ROLLBACK");
+    } catch {
+      // ROLLBACK may fail if the transaction was already rolled back
+    }
+
+    // Restore from backup
+    if (isFileDatabase && fs.existsSync(backupFile)) {
+      fs.copyFileSync(backupFile, databaseFile);
+      console.info(
+        `\nDatabase restored from backup: '${path.normalize(backupFile)}'`,
+      );
+    }
+
+    throw error;
+  } finally {
+    // Always clean up the backup file
+    if (isFileDatabase && fs.existsSync(backupFile)) {
+      fs.unlinkSync(backupFile);
+    }
+  }
+}
+
+/* v8 ignore next 6 */
+if (process.env.NODE_ENV !== "test") {
+  main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  });
+}