@restforgejs/platform 4.1.1 → 4.2.8

package/generators/lib/payload/schema-diff.js

@@ -0,0 +1,277 @@
+'use strict';
+
+/**
+ * Schema Diff - Shared payload-vs-database comparison
+ *
+ * Module ini ekstraksi logic dari `SchemaValidator` di payload-runner.js untuk
+ * dipakai bersama oleh `endpoint create` (validasi pre-codegen) tanpa mengikat
+ * caller ke seluruh ergonomi `payload diff` command (mis. summary console output
+ * yang fokus ke batch validation).
+ *
+ * Audit-column-awareness:
+ *   Default behavior `runtime` adalah inject 4 kolom audit (`created_at`,
+ *   `created_by`, `updated_at`, `updated_by`) ke INSERT/UPDATE saat
+ *   `payload.auditColumns` tidak di-set `false`/`null`. Fungsi ini meng-compute
+ *   effective field list (eksplisit + audit) dan men-flag kolom audit yang
+ *   *required* tapi tidak ada di database secara eksplisit, sehingga error
+ *   runtime "column does not exist" dapat di-detect saat generate-time.
+ *
+ * @module lib/payload/schema-diff
+ */
+
+const { resolveEffectiveFieldList, resolveAuditColumnNames, DEFAULT_AUDIT_COLUMNS } = require('../utils/audit-columns');
+
+const DEFAULT_EXCLUDED_COLUMNS = DEFAULT_AUDIT_COLUMNS;
+
+/**
+ * Normalisasi tipe dari fieldValidation payload ke kategori yang sama dengan
+ * `normalizeDatabaseType`. Dipakai untuk men-detect type drift antara payload
+ * dan database.
+ *
+ * @param {Object} validation - Entry dari payload.fieldValidation
+ * @returns {string|null}
+ */
+function normalizePayloadValidationType(validation) {
+    if (!validation) return null;
+    const t = (validation.type || '').toLowerCase();
+    switch (t) {
+        case 'uuid': return 'uuid';
+        case 'integer': return 'integer';
+        case 'number': return 'numeric';
+        case 'boolean': return 'boolean';
+        case 'date': return 'date';
+        case 'datetime': return 'timestamp';
+        case 'string': return 'varchar';
+        case 'json':
+        case 'array': return 'json';
+        default: return t || null;
+    }
+}
+
+/**
+ * Normalisasi tipe data database ke kategori umum untuk perbandingan
+ * (mirror dari SchemaValidator.normalizeType di payload-runner.js).
+ *
+ * @param {string} dataType
+ * @param {string} udtName
+ * @param {Object} col
+ * @returns {string}
+ */
+function normalizeDatabaseType(dataType, udtName, col) {
+    const dt = (dataType || '').toLowerCase();
+    const udt = (udtName || '').toLowerCase();
+
+    if (dt === 'uuid' || udt === 'uuid') return 'uuid';
+    if (dt === 'boolean' || udt === 'bool') return 'boolean';
+
+    if (['integer', 'bigint', 'smallint', 'serial', 'bigserial', 'smallserial',
+         'int', 'tinyint', 'mediumint'].includes(dt) ||
+        ['int4', 'int8', 'int2', 'serial4', 'serial8', 'serial2'].includes(udt)) {
+        return 'integer';
+    }
+
+    if (['numeric', 'decimal', 'real', 'double precision', 'float', 'double'].includes(dt) ||
+        ['numeric', 'float4', 'float8'].includes(udt)) {
+        return 'numeric';
+    }
+
+    if (['character varying', 'varchar', 'varchar2', 'nvarchar2', 'nvarchar'].includes(dt)) return 'varchar';
+    if (['text', 'clob', 'nclob', 'longtext', 'mediumtext', 'tinytext'].includes(dt)) return 'text';
+    if (['char', 'character', 'nchar'].includes(dt)) return 'char';
+
+    if (dt === 'date') return 'date';
+    if (dt === 'datetime') return 'timestamp';
+    if (dt.startsWith('timestamp')) return 'timestamp';
+    if (dt.startsWith('time')) return 'time';
+
+    if (['json', 'jsonb'].includes(dt) || ['json', 'jsonb'].includes(udt)) return 'json';
+
+    return dt || 'unknown';
+}
+
+/**
+ * Bandingkan satu payload dengan schema database aktual.
+ *
+ * Mode strict ini audit-column-aware:
+ *   - tidak men-skip kolom audit default dari sisi "added" (kolom audit yang
+ *     di-required oleh payload tapi tidak ada di database dilaporkan sebagai
+ *     `auditMissing`).
+ *   - compute removed = field di payload (eksplisit) yang tidak ada di database
+ *   - compute typeChanges = field yang ada di payload + database tapi tipenya
+ *     beda (pakai `fieldValidation` di payload sebagai source of truth)
+ *
+ * Dipakai bersama oleh endpoint create, payload validate, payload diff, dan
+ * payload sync sebagai source of truth tunggal untuk drift detection.
+ *
+ * @param {Object} payload - Processed payload object
+ * @param {Object} db - DatabaseIntrospector terkoneksi
+ * @returns {Promise<{
+ *   tableName: string,
+ *   status: 'ok' | 'drift' | 'error',
+ *   removed: Array<{ column: string, source: 'payload' | 'audit' }>,
+ *   added: Array<{ column: string, type: string, nullable: boolean }>,
+ *   typeChanges: Array<{ column: string, payloadType: string, databaseType: string }>,
+ *   auditMissing: string[],
+ *   summary: string
+ * }>}
+ */
+async function compareSchemaStrict(payload, db) {
+    const tableName = payload.tableName;
+    const result = {
+        tableName,
+        status: 'ok',
+        removed: [],
+        added: [],
+        typeChanges: [],
+        auditMissing: [],
+        summary: ''
+    };
+
+    const dbColumns = await db.getDetailedColumnInfo(tableName);
+    if (!Array.isArray(dbColumns) || dbColumns.length === 0) {
+        result.status = 'error';
+        result.summary = `Table "${tableName}" not found in database`;
+        return result;
+    }
+
+    const dbColumnSet = new Set(dbColumns.map(c => c.column_name));
+    const dbColumnList = dbColumns.map(c => c.column_name);
+    const dbColumnMap = {};
+    for (const col of dbColumns) {
+        dbColumnMap[col.column_name] = col;
+    }
+
+    const { explicit, audit } = resolveEffectiveFieldList(payload);
+
+    const explicitSet = new Set(explicit);
+    for (const field of explicit) {
+        if (!dbColumnSet.has(field)) {
+            result.removed.push({ column: field, source: 'payload' });
+        }
+    }
+
+    for (const auditCol of audit) {
+        if (!dbColumnSet.has(auditCol)) {
+            result.auditMissing.push(auditCol);
+        }
+    }
+
+    for (const dbCol of dbColumns) {
+        const name = dbCol.column_name;
+        if (explicitSet.has(name)) continue;
+        if (DEFAULT_EXCLUDED_COLUMNS.includes(name)) continue;
+        if (audit.includes(name)) continue;
+        result.added.push({
+            column: name,
+            type: normalizeDatabaseType(dbCol.data_type, dbCol.udt_name, dbCol),
+            nullable: dbCol.is_nullable === 'YES'
+        });
+    }
+
+    // Type drift: hanya untuk field yang ada di kedua sisi DAN punya entry
+    // di payload.fieldValidation. Tanpa fieldValidation, type drift tidak bisa
+    // di-detect (payload tidak men-claim tipe spesifik).
+    const validationMap = {};
+    if (Array.isArray(payload.fieldValidation)) {
+        for (const fv of payload.fieldValidation) {
+            if (fv && fv.name) validationMap[fv.name] = fv;
+        }
+    }
+    for (const field of explicit) {
+        const dbCol = dbColumnMap[field];
+        if (!dbCol) continue;
+        const validation = validationMap[field];
+        if (!validation) continue;
+
+        const dbType = normalizeDatabaseType(dbCol.data_type, dbCol.udt_name, dbCol);
+        const payloadType = normalizePayloadValidationType(validation);
+        if (!payloadType) continue;
+
+        if (dbType !== payloadType) {
+            result.typeChanges.push({
+                column: field,
+                payloadType,
+                databaseType: dbType
+            });
+        }
+    }
+
+    const driftCount = result.removed.length + result.added.length
+        + result.auditMissing.length + result.typeChanges.length;
+    if (driftCount > 0) {
+        result.status = 'drift';
+        const parts = [];
+        if (result.removed.length > 0) parts.push(`${result.removed.length} payload field(s) missing from database`);
+        if (result.typeChanges.length > 0) parts.push(`${result.typeChanges.length} type change(s)`);
+        if (result.added.length > 0) parts.push(`${result.added.length} new database column(s) not in payload`);
+        if (result.auditMissing.length > 0) parts.push(`${result.auditMissing.length} audit column(s) required but missing`);
+        result.summary = parts.join(', ');
+    } else {
+        result.summary = 'Schema is in sync';
+    }
+
+    result.totalColumnsChecked = dbColumnList.length;
+    return result;
+}
+
+/**
+ * Format drift result ke output console untuk endpoint create.
+ * Format mengikuti spec phase-01-implementation.md:
+ *   [-] kolom_a  (in payload, not in database)
+ *   [+] kolom_b  (in database, not in payload)
+ *   [+] created_at, ... (required by auditColumns=true, not in database)
+ *
+ * @param {Object} comparison - Hasil compareSchemaStrict()
+ * @param {Object} options
+ * @param {string} options.payloadFileName - Nama file payload (untuk resolution message)
+ * @param {string} options.tableName - Nama table
+ * @returns {string[]} Lines untuk di-print
+ */
+function formatDriftReport(comparison, options = {}) {
+    const lines = [];
+    const payloadFile = options.payloadFileName || comparison.tableName;
+    const tableName = comparison.tableName;
+
+    lines.push('  [BLOCKED] Payload-database drift detected:');
+
+    for (const item of comparison.removed) {
+        lines.push(`    [-] ${item.column.padEnd(12)} (in payload, not in database)`);
+    }
+
+    if (Array.isArray(comparison.typeChanges)) {
+        for (const item of comparison.typeChanges) {
+            lines.push(`    [~] ${item.column.padEnd(12)} (type: ${item.payloadType} -> ${item.databaseType})`);
+        }
+    }
+
+    for (const item of comparison.added) {
+        lines.push(`    [+] ${item.column.padEnd(12)} (in database, not in payload)`);
+    }
+
+    if (comparison.auditMissing.length > 0) {
+        const cols = comparison.auditMissing.join(', ');
+        lines.push(`    [+] ${cols}`);
+        lines.push('                     (required by auditColumns=true, not in database)');
+    }
+
+    lines.push('');
+    lines.push('  Resolution:');
+    lines.push(`    1. Run: npx restforge payload sync --table=${tableName} --config=<ENV>`);
+    if (comparison.auditMissing.length > 0) {
+        lines.push(`    2. Add audit columns to schema OR set "auditColumns": false in payload/${payloadFile}`);
+        lines.push('    3. Re-run endpoint create after resolving');
+    } else {
+        lines.push('    2. Tambah kolom missing ke schema untuk match dengan payload');
+        lines.push('    3. Re-run endpoint create after resolving');
+    }
+
+    return lines;
+}
+
+module.exports = {
+    DEFAULT_EXCLUDED_COLUMNS,
+    normalizeDatabaseType,
+    normalizePayloadValidationType,
+    compareSchemaStrict,
+    formatDriftReport
+};

package/generators/lib/utils/audit-columns.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * Audit Columns Helper
+ *
+ * Resolve nama kolom audit yang efektif berdasarkan konfigurasi payload.
+ * Konvensi default mengikuti BaseModel runtime di `src/models/base-model.js`:
+ *   createdAt -> created_at
+ *   createdBy -> created_by
+ *   updatedAt -> updated_at
+ *   updatedBy -> updated_by
+ *
+ * Payload dapat override behavior:
+ *   - `auditColumns: false` (atau null) -> disable audit columns
+ *   - `auditColumns: { createdAt, createdBy, updatedAt, updatedBy }` -> custom mapping
+ *   - tidak di-set / true -> pakai default 4 nama standar
+ *
+ * Helper ini dipakai oleh:
+ *   - schema-diff: compute effective field list (fieldName ∪ audit columns)
+ *   - endpoint create: validation pre-codegen
+ *
+ * @module lib/utils/audit-columns
+ */
+
+const DEFAULT_AUDIT_COLUMN_MAP = {
+    createdAt: 'created_at',
+    createdBy: 'created_by',
+    updatedAt: 'updated_at',
+    updatedBy: 'updated_by'
+};
+
+const DEFAULT_AUDIT_COLUMNS = Object.values(DEFAULT_AUDIT_COLUMN_MAP);
+
+/**
+ * Cek apakah audit columns aktif untuk payload ini.
+ *
+ * @param {Object} payload - Processed payload object
+ * @returns {boolean} true jika audit columns akan di-inject runtime
+ */
+function isAuditColumnsEnabled(payload) {
+    if (!payload) return false;
+    if (!Object.prototype.hasOwnProperty.call(payload, 'auditColumns')) return true;
+    const value = payload.auditColumns;
+    if (value === false || value === null) return false;
+    return true;
+}
+
+/**
+ * Resolve nama kolom audit (sisi database) yang akan di-inject runtime.
+ * Mengembalikan empty array bila audit columns di-disable.
+ *
+ * @param {Object} payload - Processed payload object
+ * @returns {string[]} Array nama kolom database (snake_case)
+ */
+function resolveAuditColumnNames(payload) {
+    if (!isAuditColumnsEnabled(payload)) return [];
+
+    const value = payload && payload.auditColumns;
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const out = [];
+        for (const key of Object.keys(DEFAULT_AUDIT_COLUMN_MAP)) {
+            const mapped = value[key];
+            if (typeof mapped === 'string' && mapped.length > 0) {
+                out.push(mapped);
+            } else {
+                out.push(DEFAULT_AUDIT_COLUMN_MAP[key]);
+            }
+        }
+        return out;
+    }
+
+    return DEFAULT_AUDIT_COLUMNS.slice();
+}
+
+/**
+ * Resolve effective field list yang dipakai generator codegen:
+ * gabungan fieldName eksplisit di payload + audit columns yang akan
+ * di-inject runtime.
+ *
+ * Dipakai oleh schema validation untuk men-detect drift yang berasal
+ * dari implicit audit columns (kasus umum: auditColumns aktif tapi
+ * tabel database tidak punya kolom audit).
+ *
+ * @param {Object} payload - Processed payload object
+ * @returns {{ fields: string[], audit: string[], explicit: string[] }}
+ */
+function resolveEffectiveFieldList(payload) {
+    const explicit = Array.isArray(payload && payload.fieldName)
+        ? payload.fieldName.slice()
+        : [];
+    const audit = resolveAuditColumnNames(payload);
+
+    const merged = [];
+    const seen = new Set();
+    for (const f of explicit) {
+        if (!seen.has(f)) {
+            seen.add(f);
+            merged.push(f);
+        }
+    }
+    for (const f of audit) {
+        if (!seen.has(f)) {
+            seen.add(f);
+            merged.push(f);
+        }
+    }
+
+    return {
+        fields: merged,
+        audit,
+        explicit
+    };
+}
+
+/**
+ * Deteksi alignment kolom audit standar antara payload generator dan tabel
+ * database aktual. Helper ini dipakai oleh sync flow (payload-runner) dan
+ * initial generation untuk men-set `auditColumns: false` bila kolom audit
+ * tidak tersedia di database.
+ *
+ * Konvensi: kolom audit standar mengikuti DEFAULT_AUDIT_COLUMNS (snake_case).
+ * Match dilakukan exact lowercase; bila tabel pakai naming convention lain
+ * (mis. `CreatedAt`), audit detection akan miss.
+ *
+ * @param {string[]} dbColumns - Daftar nama kolom dari tabel database
+ * @returns {{
+ *   all: boolean,        // semua 4 kolom audit standar ada di database
+ *   partial: boolean,    // sebagian (1-3) kolom audit ada
+ *   none: boolean,       // tidak satupun kolom audit ada
+ *   present: string[],   // kolom audit yang ada di database
+ *   missing: string[]    // kolom audit yang tidak ada di database
+ * }}
+ */
+function detectAuditAlignment(dbColumns) {
+    const columns = Array.isArray(dbColumns) ? dbColumns : [];
+    const present = DEFAULT_AUDIT_COLUMNS.filter(col => columns.includes(col));
+    const missing = DEFAULT_AUDIT_COLUMNS.filter(col => !columns.includes(col));
+    return {
+        all: present.length === DEFAULT_AUDIT_COLUMNS.length,
+        partial: present.length > 0 && present.length < DEFAULT_AUDIT_COLUMNS.length,
+        none: present.length === 0,
+        present,
+        missing
+    };
+}
+
+/**
+ * Cek apakah konfigurasi `auditColumns` di payload memerlukan resolusi
+ * berdasarkan alignment dengan database. Dipakai sync flow untuk men-detect
+ * "audit-only drift" yang tidak ter-detect oleh comparator schema reguler.
+ *
+ * Aturan resolusi:
+ *   - `auditColumns: false`/`null` -> no-op (preserved)
+ *   - `auditColumns: { ... }` (object form) -> no auto-override (manual)
+ *   - `auditColumns: true` atau tidak di-set (default true) -> butuh resolusi
+ *     bila database tidak punya keempat kolom audit standar (none atau partial)
+ *
+ * @param {Object} payload - Processed payload object
+ * @param {ReturnType<typeof detectAuditAlignment>} auditAlignment
+ * @returns {boolean} true bila sync wajib regenerate untuk men-set false
+ */
+function needsAuditColumnResolution(payload, auditAlignment) {
+    if (!payload || !auditAlignment) return false;
+    const hasField = Object.prototype.hasOwnProperty.call(payload, 'auditColumns');
+    const value = hasField ? payload.auditColumns : undefined;
+
+    if (value === false || value === null) return false;
+    if (value && typeof value === 'object' && !Array.isArray(value)) return false;
+
+    return !auditAlignment.all;
+}
+
+module.exports = {
+    DEFAULT_AUDIT_COLUMN_MAP,
+    DEFAULT_AUDIT_COLUMNS,
+    isAuditColumnsEnabled,
+    resolveAuditColumnNames,
+    resolveEffectiveFieldList,
+    detectAuditAlignment,
+    needsAuditColumnResolution
+};

package/generators/lib/utils/cli-output.js

@@ -67,6 +67,9 @@ class CliOutput {
       ? `${data.config.database} (force overwrite)`
       : data.config.database;
     out(`  Database     ${dbLine}`);
+    if (data.config.config) {
+      out(`  Config       ${data.config.config}`);
+    }
     out('');
 
     if (data.payload) {
@@ -79,6 +82,20 @@ class CliOutput {
       out('');
     }
 
+    if (data.schemaValidation) {
+      out('Schema Validation:');
+      if (data.schemaValidation.status === 'ok') {
+        const n = data.schemaValidation.columnsChecked || 0;
+        out(`  Status       OK (${n} column${n === 1 ? '' : 's'} match database)`);
+      } else if (data.schemaValidation.status === 'skipped') {
+        out('  Status       SKIPPED (--skip-schema-check)');
+        if (data.schemaValidation.reason) {
+          out(`  Reason       ${data.schemaValidation.reason}`);
+        }
+      }
+      out('');
+    }
+
     if (data.archive && data.archive.count > 0) {
       out('Archive (force):');
       out(`  Generation ${data.archive.generation} - ${data.archive.count} file(s) archived`);

package/generators/lib/utils/database-introspector.js

@@ -242,22 +242,25 @@ class DatabaseIntrospector {
   }
 
   /**
-   * Close database connection
+   * Close database connection. Idempotent — panggilan kedua jadi no-op
+   * setelah `this.pool` di-null-kan. Ini mencegah pesan "Database connection
+   * closed" muncul dua kali ketika caller punya cleanup ganda (mis. cleanup
+   * eksplisit + cleanup di catch block).
    */
   async close() {
-    if (this.pool) {
-      try {
-        if (this.dbType === 'oracle') {
-          await this.pool.close(0);
-        } else {
-          await this.pool.end();
-        }
-      } catch (e) {
-        // ignore close errors
-      }
-      if (!this.quiet) {
-        console.log('Database connection closed');
+    if (!this.pool) return;
+    try {
+      if (this.dbType === 'oracle') {
+        await this.pool.close(0);
+      } else {
+        await this.pool.end();
       }
+    } catch (e) {
+      // ignore close errors
+    }
+    this.pool = null;
+    if (!this.quiet) {
+      console.log('Database connection closed');
     }
   }
 

package/integrity-manifest.json

@@ -1,15 +1,15 @@
 {
-  "version": "4.1.1",
-  "generated": "2026-05-19T01:38:06.824Z",
+  "version": "4.2.8",
+  "generated": "2026-05-21T01:20:53.402Z",
   "generator": "restforge-build-system",
   "algorithm": "sha256",
   "files": {
-    "server.js": "2bf1e25e7af33bb70dd0f3d5f3f970ed2f5d227c6c5534b4dfe5cb294d59b2f5",
-    "src/utils/license-client.js": "976511ab72f356595bf1399a50480d340b556f9bce4b71058b90b10d6bd8e793",
-    "src/utils/trusted-keys.js": "faf93514b43a83650c950c05aca6e42ed64c19fbeb7e3c84e93c509de84bd2c0",
-    "cli/consumer.js": "e2a5055652cee82d32b6873e21469bc07784a490d125ec7e64171ba06ad31397",
-    "src/utils/security-checks.js": "1748b39715ff5c1047a730d1e62a22151b38eedc0f48bbd33b1ab4f0ff592d34",
-    "scripts/verify-integrity.js": "3e891f9baa234362ebcee8d1048fe7bac3221a026c2918cf0e154e5ea3444c87"
+    "server.js": "91f5255aacad771c0ff9370c6c76be4a081fa6f264adf1fb5bc77a1f585ddce9",
+    "src/utils/license-client.js": "2f9cfbc101e87c9e179a36d7c7e1b8dc2fd78999331efb3752bcb66dafb2364e",
+    "src/utils/trusted-keys.js": "2a02c10de6ca639ace51417ac93c74feb00db51a55ebf98f18a831eefef60516",
+    "cli/consumer.js": "2815eeba5613515349853107034f3763347a218d1a0ec3f484456a5fb4674143",
+    "src/utils/security-checks.js": "04aca0bfcb331befd114e454e0fdeff37a201874394afe0cdba79c9969aed776",
+    "scripts/verify-integrity.js": "2f4d06552da2d9204565c3473cde414c24ed6aef326f177acf30ba0ee7d243b8"
   },
   "stats": {
     "totalFiles": 6,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@restforgejs/platform",
-  "version": "4.1.1",
+  "version": "4.2.8",
   "description": "RESTForge Platform — Schema-driven backend framework and code generator for full-stack Node.js applications. Generates production backend APIs with multi-database support (PostgreSQL, MySQL, Oracle). A platform builder and backend runtime, not an API testing or client tool.",
   "main": "server.js",
   "bin": {