rotifex 0.1.0

package/src/db/adapters/sqlite.js

@@ -0,0 +1,86 @@
+import Database from 'better-sqlite3';
+import { DatabaseAdapter } from './base.js';
+
+/**
+ * SQLite adapter backed by better-sqlite3.
+ *
+ * All operations are synchronous (better-sqlite3's design) which keeps
+ * the API simple and avoids callback/promise complexity for a local CLI tool.
+ */
+export class SqliteAdapter extends DatabaseAdapter {
+  /** @type {import('better-sqlite3').Database|null} */
+  #db = null;
+
+  /**
+   * @param {string} filepath  Path to the SQLite database file.
+   *                           Defaults to `database.sqlite` in the cwd.
+   */
+  constructor(filepath = 'database.sqlite') {
+    super();
+    this.filepath = filepath;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Connection lifecycle                                               */
+  /* ------------------------------------------------------------------ */
+
+  /** @inheritdoc */
+  open() {
+    if (this.#db) return;
+    this.#db = new Database(this.filepath);
+    // Enable WAL mode for better concurrent-read performance.
+    this.#db.pragma('journal_mode = WAL');
+  }
+
+  /** @inheritdoc */
+  close() {
+    if (!this.#db) return;
+    this.#db.close();
+    this.#db = null;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Query helpers                                                      */
+  /* ------------------------------------------------------------------ */
+
+  /** @inheritdoc */
+  run(sql, params = []) {
+    this.#ensureOpen();
+    return this.#db.prepare(sql).run(...params);
+  }
+
+  /** @inheritdoc */
+  get(sql, params = []) {
+    this.#ensureOpen();
+    return this.#db.prepare(sql).get(...params);
+  }
+
+  /** @inheritdoc */
+  all(sql, params = []) {
+    this.#ensureOpen();
+    return this.#db.prepare(sql).all(...params);
+  }
+
+  /** @inheritdoc */
+  exec(sql) {
+    this.#ensureOpen();
+    this.#db.exec(sql);
+  }
+
+  /** @inheritdoc */
+  transaction(fn) {
+    this.#ensureOpen();
+    const wrapped = this.#db.transaction(() => fn(this));
+    return wrapped();
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Internal                                                           */
+  /* ------------------------------------------------------------------ */
+
+  #ensureOpen() {
+    if (!this.#db) {
+      throw new Error('Database is not open. Call adapter.open() first.');
+    }
+  }
+}

package/src/db/connection.js

@@ -0,0 +1,45 @@
+import { SqliteAdapter } from './adapters/sqlite.js';
+
+/**
+ * Singleton database connection manager.
+ *
+ * Call `getDatabase()` to obtain the shared adapter instance.
+ * The adapter type is selected by `config.adapter` (currently only 'sqlite').
+ * Adding PostgreSQL later requires only a new adapter class and a case here.
+ */
+
+/** @type {import('./adapters/base.js').DatabaseAdapter|null} */
+let instance = null;
+
+/**
+ * Return (and lazily create) the singleton database adapter.
+ *
+ * @param {{ adapter?: 'sqlite', filepath?: string }} [config]
+ * @returns {import('./adapters/base.js').DatabaseAdapter}
+ */
+export function getDatabase(config = {}) {
+  if (instance) return instance;
+
+  const { adapter = 'sqlite', filepath } = config;
+
+  switch (adapter) {
+    case 'sqlite':
+      instance = new SqliteAdapter(filepath);
+      break;
+    // Future: case 'postgres': …
+    default:
+      throw new Error(`Unknown database adapter: "${adapter}"`);
+  }
+
+  instance.open();
+  return instance;
+}
+
+/**
+ * Close the active database connection and discard the singleton.
+ */
+export function closeDatabase() {
+  if (!instance) return;
+  instance.close();
+  instance = null;
+}

package/src/db/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public API for the Rotifex database layer.
+ *
+ * Usage:
+ *   import { getDatabase, closeDatabase, createTable, dropTable, Migrator } from '../db/index.js';
+ */
+
+export { getDatabase, closeDatabase } from './connection.js';
+export { createTable, dropTable } from './schema.js';
+export { Migrator } from './migrator.js';
+export { DatabaseAdapter } from './adapters/base.js';
+export { SqliteAdapter } from './adapters/sqlite.js';

package/src/db/migrator.js

@@ -0,0 +1,142 @@
+import { readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * File-based migration runner.
+ *
+ * Migration files live in `migrations/` and are named `NNN_description.js`.
+ * Each file must export `up(db)` and `down(db)` functions.
+ *
+ * Applied migrations are tracked in the `_migrations` table, which records
+ * the filename and batch number so rollbacks can undo an entire batch.
+ */
+export class Migrator {
+  /**
+   * @param {import('./adapters/base.js').DatabaseAdapter} db
+   * @param {string} [migrationsDir]  Absolute or relative path to the
+   *                                   migrations folder (default: `./migrations`).
+   */
+  constructor(db, migrationsDir = 'migrations') {
+    this.db = db;
+    this.migrationsDir = resolve(migrationsDir);
+    this.#ensureMigrationsTable();
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Public API                                                         */
+  /* ------------------------------------------------------------------ */
+
+  /**
+   * Return the list of migration filenames that have not yet been applied.
+   * @returns {Promise<string[]>}
+   */
+  async pending() {
+    const all = await this.#readMigrationFiles();
+    const applied = this.#appliedNames();
+    return all.filter(f => !applied.has(f));
+  }
+
+  /**
+   * Apply all pending migrations.
+   * @returns {Promise<string[]>}  List of filenames that were applied.
+   */
+  async up() {
+    const pendingFiles = await this.pending();
+    if (pendingFiles.length === 0) return [];
+
+    const batch = this.#nextBatch();
+
+    for (const file of pendingFiles) {
+      const mod = await this.#loadMigration(file);
+      this.db.transaction((db) => {
+        mod.up(db);
+        db.run(
+          'INSERT INTO _migrations (name, batch) VALUES (?, ?)',
+          [file, batch],
+        );
+      });
+    }
+
+    return pendingFiles;
+  }
+
+  /**
+   * Roll back the latest batch of migrations.
+   * @returns {Promise<string[]>}  List of filenames that were rolled back.
+   */
+  async down() {
+    const lastBatch = this.db.get(
+      'SELECT MAX(batch) AS batch FROM _migrations',
+    );
+    if (!lastBatch?.batch) return [];
+
+    const rows = this.db.all(
+      'SELECT name FROM _migrations WHERE batch = ? ORDER BY id DESC',
+      [lastBatch.batch],
+    );
+
+    for (const row of rows) {
+      const mod = await this.#loadMigration(row.name);
+      this.db.transaction((db) => {
+        mod.down(db);
+        db.run('DELETE FROM _migrations WHERE name = ?', [row.name]);
+      });
+    }
+
+    return rows.map(r => r.name);
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Internal helpers                                                   */
+  /* ------------------------------------------------------------------ */
+
+  #ensureMigrationsTable() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _migrations (
+        id    INTEGER PRIMARY KEY AUTOINCREMENT,
+        name  TEXT NOT NULL UNIQUE,
+        batch INTEGER NOT NULL,
+        applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+    `);
+  }
+
+  /** @returns {Set<string>} */
+  #appliedNames() {
+    const rows = this.db.all('SELECT name FROM _migrations');
+    return new Set(rows.map(r => r.name));
+  }
+
+  /** @returns {number} */
+  #nextBatch() {
+    const row = this.db.get('SELECT MAX(batch) AS batch FROM _migrations');
+    return (row?.batch ?? 0) + 1;
+  }
+
+  /**
+   * Read and sort migration filenames from the migrations directory.
+   * @returns {Promise<string[]>}
+   */
+  async #readMigrationFiles() {
+    try {
+      const entries = await readdir(this.migrationsDir);
+      return entries
+        .filter(f => /^\d+_.+\.js$/.test(f))
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Dynamically import a migration module.
+   * @param {string} filename
+   * @returns {Promise<{ up: Function, down: Function }>}
+   */
+  async #loadMigration(filename) {
+    const fullPath = join(this.migrationsDir, filename);
+    const fileUrl = pathToFileURL(fullPath).href;
+    return import(fileUrl);
+  }
+}

package/src/db/schema.js

@@ -0,0 +1,48 @@
+/**
+ * Lightweight schema helpers for table creation.
+ *
+ * Every table automatically receives:
+ *   - `id`         TEXT PRIMARY KEY  (UUID v4)
+ *   - `created_at` TEXT NOT NULL     (ISO-8601, defaults to now)
+ *   - `updated_at` TEXT NOT NULL     (ISO-8601, defaults to now)
+ */
+
+/**
+ * @typedef {object} ColumnDef
+ * @property {string}  name         Column name.
+ * @property {string}  type         SQL type (TEXT, INTEGER, REAL, BLOB, …).
+ * @property {string}  [constraints]  Extra constraints, e.g. 'NOT NULL UNIQUE'.
+ */
+
+/**
+ * Create a table with automatic `id`, `created_at`, and `updated_at` columns.
+ *
+ * @param {import('./adapters/base.js').DatabaseAdapter} db
+ * @param {string} tableName
+ * @param {ColumnDef[]} columns   User-defined columns (id & timestamps are added automatically).
+ */
+export function createTable(db, tableName, columns = []) {
+  const allColumns = [
+    "id TEXT PRIMARY KEY NOT NULL",
+    ...columns.map(col => {
+      const parts = [col.name, col.type];
+      if (col.constraints) parts.push(col.constraints);
+      return parts.join(' ');
+    }),
+    "created_at TEXT NOT NULL DEFAULT (datetime('now'))",
+    "updated_at TEXT NOT NULL DEFAULT (datetime('now'))",
+  ];
+
+  const sql = `CREATE TABLE IF NOT EXISTS ${tableName} (\n  ${allColumns.join(',\n  ')}\n);`;
+  db.exec(sql);
+}
+
+/**
+ * Drop a table if it exists.
+ *
+ * @param {import('./adapters/base.js').DatabaseAdapter} db
+ * @param {string} tableName
+ */
+export function dropTable(db, tableName) {
+  db.exec(`DROP TABLE IF EXISTS ${tableName};`);
+}

package/src/engine/index.js

@@ -0,0 +1,76 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadSchema, parseModelDef } from './schemaLoader.js';
+import { syncTables } from './tableSync.js';
+import { registerGenericRoutes } from './routeFactory.js';
+import { initStore, upsertModel } from './schemaStore.js';
+import { logger } from '../lib/logger.js';
+
+/**
+ * Built-in system models that are always guaranteed to exist.
+ * These are written to schema.json on first boot if absent.
+ */
+const SYSTEM_MODELS = {
+  User: {
+    fields: {
+      email:        { type: 'string', required: true, unique: true },
+      display_name: { type: 'string' },
+      role:         { type: 'string', default: 'user' },
+    },
+  },
+};
+
+/**
+ * Ensure system models exist in schema.json and the in-memory store.
+ * Idempotent — only adds what's missing, never overwrites existing.
+ */
+function ensureSystemModels(schemaPath) {
+  const abs = resolve(schemaPath);
+  let schema = {};
+  if (existsSync(abs)) {
+    try { schema = JSON.parse(readFileSync(abs, 'utf-8')); } catch {}
+  }
+
+  let changed = false;
+  for (const [name, def] of Object.entries(SYSTEM_MODELS)) {
+    if (!schema[name]) {
+      schema[name] = def;
+      changed = true;
+    }
+  }
+
+  if (changed) writeFileSync(abs, JSON.stringify(schema, null, 2));
+}
+
+/**
+ * Bootstrap the dynamic REST engine.
+ *
+ * 1. Ensure system models (User) exist in schema.json
+ * 2. Load all model definitions into the in-memory store
+ * 3. Auto-create DB tables (idempotent)
+ * 4. Register five generic /api/:table routes
+ *
+ * @param {import('fastify').FastifyInstance} app
+ * @param {import('../db/adapters/base.js').DatabaseAdapter} db
+ * @param {string} [schemaPath]
+ */
+export function bootstrapEngine(app, db, schemaPath = 'schema.json') {
+  ensureSystemModels(schemaPath);
+
+  const models = loadSchema(schemaPath);
+
+  initStore(models);
+  syncTables(db, models);
+  registerGenericRoutes(app, db);
+
+  logger.success(
+    `Woke up ${models.size} model(s) and they're ready to party: ${[...models.keys()].join(', ')}`,
+  );
+}
+
+export { loadSchema, parseModelDef } from './schemaLoader.js';
+export { syncTables } from './tableSync.js';
+export { registerGenericRoutes } from './routeFactory.js';
+export { buildValidators } from './zodFactory.js';
+export { buildListQuery } from './queryBuilder.js';
+export { initStore, getStore, getModelByTable, upsertModel, removeModel } from './schemaStore.js';

package/src/engine/queryBuilder.js

@@ -0,0 +1,52 @@
+/**
+ * Build parameterised SQL for list queries with filtering, sorting,
+ * and pagination.
+ *
+ * @param {string}   tableName
+ * @param {object[]} fields        Normalised field definitions.
+ * @param {object}   query         Raw query-string object from the request.
+ * @returns {{ sql: string, countSql: string, params: any[], page: number, limit: number }}
+ */
+export function buildListQuery(tableName, fields, query = {}) {
+  const fieldNames = new Set(fields.map(f => f.name));
+  // Also allow filtering on the auto-generated columns
+  fieldNames.add('id');
+  fieldNames.add('created_at');
+  fieldNames.add('updated_at');
+
+  // ── Filtering ─────────────────────────────────────────────────────
+  const whereClauses = [];
+  const params = [];
+
+  for (const [key, value] of Object.entries(query)) {
+    if (['sort', 'order', 'page', 'limit'].includes(key)) continue;
+    if (!fieldNames.has(key)) continue;       // ignore unknown fields
+    whereClauses.push(`${key} = ?`);
+    params.push(value);
+  }
+
+  const whereSQL = whereClauses.length
+    ? `WHERE ${whereClauses.join(' AND ')}`
+    : '';
+
+  // ── Sorting ───────────────────────────────────────────────────────
+  const sortField = fieldNames.has(query.sort) ? query.sort : 'created_at';
+  const sortOrder = query.order?.toUpperCase() === 'ASC' ? 'ASC' : 'DESC';
+  const orderSQL  = `ORDER BY ${sortField} ${sortOrder}`;
+
+  // ── Pagination ────────────────────────────────────────────────────
+  const page  = Math.max(1, parseInt(query.page,  10) || 1);
+  const limit = Math.min(100, Math.max(1, parseInt(query.limit, 10) || 20));
+  const offset = (page - 1) * limit;
+
+  const sql      = `SELECT * FROM ${tableName} ${whereSQL} ${orderSQL} LIMIT ? OFFSET ?`;
+  const countSql = `SELECT COUNT(*) AS total FROM ${tableName} ${whereSQL}`;
+
+  return {
+    sql,
+    countSql,
+    params,          // shared between data + count queries
+    page,
+    limit,
+  };
+}

package/src/engine/routeFactory.js

@@ -0,0 +1,119 @@
+import crypto from 'node:crypto';
+import { buildValidators } from './zodFactory.js';
+import { buildListQuery } from './queryBuilder.js';
+import { getModelByTable } from './schemaStore.js';
+
+const NOT_FOUND_TABLE = (table) => ({
+  error: 'Not Found',
+  message: `Unknown resource "${table}"`,
+  statusCode: 404,
+});
+
+/**
+ * Register five generic CRUD routes that resolve the model from the
+ * in-memory schema store at request time.
+ *
+ * Because the store is updated live (no restart needed), any model added
+ * via the admin API is immediately reachable through these routes.
+ *
+ *   GET    /:table          List (filter + sort + paginate)
+ *   GET    /:table/:id      Get by ID
+ *   POST   /:table          Create
+ *   PUT    /:table/:id      Update (partial)
+ *   DELETE /:table/:id      Delete
+ *
+ * Static routes registered elsewhere (/health, /files/*, /admin/*)
+ * always take priority over these parametric routes in Fastify's router.
+ *
+ * @param {import('fastify').FastifyInstance} app
+ * @param {import('../db/adapters/base.js').DatabaseAdapter} db
+ */
+export function registerGenericRoutes(app, db) {
+
+  // ── LIST ─────────────────────────────────────────────────────────────
+  app.get('/api/:table', (request, reply) => {
+    const model = getModelByTable(request.params.table);
+    if (!model) return reply.status(404).send(NOT_FOUND_TABLE(request.params.table));
+
+    const { tableName, fields } = model;
+    const { sql, countSql, params, page, limit } = buildListQuery(tableName, fields, request.query);
+
+    const rows          = db.all(sql, [...params, limit, (page - 1) * limit]);
+    const { total }     = db.get(countSql, params);
+
+    return { data: rows, meta: { total, page, limit, pages: Math.ceil(total / limit) } };
+  });
+
+  // ── GET BY ID ─────────────────────────────────────────────────────────
+  app.get('/api/:table/:id', (request, reply) => {
+    const model = getModelByTable(request.params.table);
+    if (!model) return reply.status(404).send(NOT_FOUND_TABLE(request.params.table));
+
+    const row = db.get(`SELECT * FROM ${model.tableName} WHERE id = ?`, [request.params.id]);
+    if (!row) return reply.status(404).send({ error: 'Not Found', message: `${model.tableName} not found`, statusCode: 404 });
+    return { data: row };
+  });
+
+  // ── CREATE ────────────────────────────────────────────────────────────
+  app.post('/api/:table', (request, reply) => {
+    const model = getModelByTable(request.params.table);
+    if (!model) return reply.status(404).send(NOT_FOUND_TABLE(request.params.table));
+
+    const { tableName, fields } = model;
+    const { createSchema } = buildValidators(fields);
+    const parsed = createSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.status(400).send({ error: 'Validation Error', message: parsed.error.issues, statusCode: 400 });
+    }
+
+    const data      = parsed.data;
+    const id        = crypto.randomUUID();
+    const now       = new Date().toISOString();
+    const cols      = ['id', ...Object.keys(data), 'created_at', 'updated_at'];
+    const sqlParams = [id, ...Object.values(data), now, now]
+      .map(v => (typeof v === 'boolean' ? (v ? 1 : 0) : v));
+
+    db.run(`INSERT INTO ${tableName} (${cols.join(', ')}) VALUES (${cols.map(() => '?').join(', ')})`, sqlParams);
+    return reply.status(201).send({ data: db.get(`SELECT * FROM ${tableName} WHERE id = ?`, [id]) });
+  });
+
+  // ── UPDATE ────────────────────────────────────────────────────────────
+  app.put('/api/:table/:id', (request, reply) => {
+    const model = getModelByTable(request.params.table);
+    if (!model) return reply.status(404).send(NOT_FOUND_TABLE(request.params.table));
+
+    const { tableName, fields } = model;
+    const existing = db.get(`SELECT * FROM ${tableName} WHERE id = ?`, [request.params.id]);
+    if (!existing) return reply.status(404).send({ error: 'Not Found', message: `${tableName} not found`, statusCode: 404 });
+
+    const { updateSchema } = buildValidators(fields);
+    const parsed = updateSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.status(400).send({ error: 'Validation Error', message: parsed.error.issues, statusCode: 400 });
+    }
+
+    const data = parsed.data;
+    if (Object.keys(data).length === 0) {
+      return reply.status(400).send({ error: 'Validation Error', message: 'No fields to update', statusCode: 400 });
+    }
+
+    const now        = new Date().toISOString();
+    const setClauses = [...Object.keys(data).map(k => `${k} = ?`), 'updated_at = ?'];
+    const params     = [...Object.values(data).map(v => (typeof v === 'boolean' ? (v ? 1 : 0) : v)), now, request.params.id];
+
+    db.run(`UPDATE ${tableName} SET ${setClauses.join(', ')} WHERE id = ?`, params);
+    return { data: db.get(`SELECT * FROM ${tableName} WHERE id = ?`, [request.params.id]) };
+  });
+
+  // ── DELETE ────────────────────────────────────────────────────────────
+  app.delete('/api/:table/:id', (request, reply) => {
+    const model = getModelByTable(request.params.table);
+    if (!model) return reply.status(404).send(NOT_FOUND_TABLE(request.params.table));
+
+    const existing = db.get(`SELECT * FROM ${model.tableName} WHERE id = ?`, [request.params.id]);
+    if (!existing) return reply.status(404).send({ error: 'Not Found', message: `${model.tableName} not found`, statusCode: 404 });
+
+    db.run(`DELETE FROM ${model.tableName} WHERE id = ?`, [request.params.id]);
+    return reply.status(204).send();
+  });
+}

package/src/engine/schemaLoader.js

@@ -0,0 +1,75 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/**
+ * Schema-to-SQL type mapping.
+ */
+const SQL_TYPE_MAP = {
+  string:  'TEXT',
+  number:  'REAL',
+  integer: 'INTEGER',
+  boolean: 'INTEGER',   // SQLite stores booleans as 0/1
+};
+
+/**
+ * Normalise a field definition.
+ * Supports both shorthand (`"email": "string"`) and full form
+ * (`"email": { "type": "string", "required": true }`).
+ */
+function normaliseField(name, raw) {
+  if (typeof raw === 'string') {
+    return { name, type: raw, sqlType: SQL_TYPE_MAP[raw] || 'TEXT', required: false, unique: false, default: undefined };
+  }
+  const sqlType = SQL_TYPE_MAP[raw.type] || 'TEXT';
+  return {
+    name,
+    type:     raw.type,
+    sqlType,
+    required: raw.required ?? false,
+    unique:   raw.unique   ?? false,
+    default:  raw.default,
+  };
+}
+
+/**
+ * Load and parse `schema.json`, returning a Map of model definitions.
+ *
+ * @param {string} [filepath='schema.json']
+ * @returns {Map<string, { tableName: string, fields: object[] }>}
+ */
+export function loadSchema(filepath = 'schema.json') {
+  const abs  = resolve(filepath);
+  const raw  = JSON.parse(readFileSync(abs, 'utf-8'));
+  const models = new Map();
+
+  for (const [modelName, modelDef] of Object.entries(raw)) {
+    const fieldsRaw = modelDef.fields ?? modelDef;   // support both formats
+    const fields = Object.entries(fieldsRaw).map(
+      ([name, def]) => normaliseField(name, def),
+    );
+
+    // Pluralise + lowercase for table / route name
+    const tableName = modelName.toLowerCase() + 's';
+
+    models.set(modelName, { tableName, fields });
+  }
+
+  return models;
+}
+
+/**
+ * Parse a single model definition (as stored in schema.json) into a
+ * normalised model object that the engine and store understand.
+ *
+ * @param {string} modelName   e.g. "Product"
+ * @param {object} modelDef    e.g. { fields: { name: { type: 'string', required: true } } }
+ * @returns {{ tableName: string, fields: object[] }}
+ */
+export function parseModelDef(modelName, modelDef) {
+  const fieldsRaw = modelDef.fields ?? modelDef;
+  const fields    = Object.entries(fieldsRaw).map(([name, def]) => normaliseField(name, def));
+  const tableName = modelName.toLowerCase() + 's';
+  return { tableName, fields };
+}
+
+export { SQL_TYPE_MAP };