@restforgejs/platform 4.3.4 → 4.3.8

package/generators/cli/payload/migrate.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * Contract: payload migrate
+ *
+ * Konversi file payload backend (RDF / RESTForge consumer) menjadi file payload
+ * frontend (UDF / designer). Port dari `rfd migrate` di packages/designer/.
+ *
+ * Perbedaan dengan `rfd migrate`:
+ *  - `apiBaseUrl` di-construct dari SERVER_ADDRESS + SERVER_PORT (db-connection.env)
+ *    + --project sehingga sesuai dengan runtime server actual
+ *  - Port di-baca dari db-connection.env (SERVER_PORT), bukan hard-coded 3000
+ *  - Primary key (constraints.primaryKey=true) di-skip dari fields[] apapun
+ *    tipenya (uuid/string/integer), karena PK adalah identifier teknis dan
+ *    tidak perlu di-render di UI form
+ */
+
+const runner = require('../../lib/migrate/migrate-runner');
+
+module.exports = {
+    resource: 'payload',
+    verb: 'migrate',
+    description: 'Convert backend payload (RDF) file into frontend payload (UDF) for the designer',
+    category: 'generation',
+    flags: {
+        name: {
+            type: 'string',
+            required: true,
+            description: 'Backend payload file name (e.g. visitors.json). Relative to cwd or cwd/payload/.'
+        },
+        output: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Output directory (the file will be written with the same name as --name inside it). If ending with `.json`, treated as an explicit file path. Default: frontend/payload/'
+        },
+        config: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Database config file (.env). Used to read SERVER_ADDRESS and SERVER_PORT. Falls back to `.restforge/defaults.json`.'
+        },
+        project: {
+            type: 'string',
+            required: true,
+            description: 'Project name (kebab-case code) used as the path segment in apiBaseUrl: http://{host}:{port}/api/{project}'
+        },
+        'app-name': {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Application name (default: "My Application")'
+        },
+        'app-code': {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Application code in kebab-case (default: follows --project)'
+        },
+        plugin: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Designer plugin ID (default: "vanilla-js-basic")'
+        },
+        port: {
+            type: 'number',
+            required: false,
+            default: null,
+            description: 'Frontend application port written to appConfig.port (default: 8000). Independent from the backend port used in apiBaseUrl.'
+        },
+        overwrite: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Overwrite the output file if it already exists'
+        }
+    },
+    examples: [
+        'npx restforge payload migrate --name=visitors.json --output=..\\sandbox\\frontend\\payload --config=db.env --project=myapp',
+        'npx restforge payload migrate --name=visitors.json --project=myapp --overwrite'
+    ],
+    async handler(args) {
+        await runner.run({
+            name: args.name,
+            output: args.output || null,
+            config: args.config || null,
+            project: args.project,
+            appName: args['app-name'] || null,
+            appCode: args['app-code'] || null,
+            plugin: args.plugin || null,
+            port: typeof args.port === 'number' ? args.port : null,
+            overwrite: args.overwrite === true
+        });
+    }
+};

package/generators/lib/migrate/backend-payload-migrator.js

@@ -0,0 +1,221 @@
+'use strict';
+
+/**
+ * Port dari packages/designer/src/migrators/backend_payload_migrator.rs.
+ *
+ * Orchestrator utama konversi payload backend (RESTForge / RDF) menjadi
+ * frontend payload designer (UDF). Menggabungkan output sql-parser +
+ * field-type-resolver + label-generator untuk menghasilkan frontend payload
+ * deterministic.
+ */
+
+const { parseDatatablesQuery } = require('./sql-parser');
+const { FieldTypeResolver } = require('./field-type-resolver');
+const { snakeToKebab, snakeToTitle } = require('./naming');
+
+const DEFAULT_ICON = 'file-text';
+const ICON_MAP = {
+    contact: 'users',
+    customer: 'users',
+    user: 'users',
+    supplier: 'truck',
+    vendor: 'truck',
+    category: 'tag',
+    item: 'package',
+    product: 'package',
+    stock: 'clipboard',
+    inventory: 'clipboard',
+    warehouse: 'building',
+    order: 'shopping-cart',
+    invoice: 'file-text',
+    city: 'map-pin',
+    country: 'globe',
+    department: 'briefcase',
+    employee: 'user'
+};
+
+function detectIcon(tableName) {
+    const lower = String(tableName || '').toLowerCase();
+    for (const keyword of Object.keys(ICON_MAP)) {
+        if (lower.includes(keyword)) return ICON_MAP[keyword];
+    }
+    return DEFAULT_ICON;
+}
+
+function detectDisplayField(resolvedFields, primaryKey) {
+    for (const rf of resolvedFields) {
+        if (rf.name.endsWith('_name') || rf.name === 'name') return rf.name;
+    }
+    for (const rf of resolvedFields) {
+        if (rf.name.endsWith('_code') || rf.name === 'code') return rf.name;
+    }
+    for (const rf of resolvedFields) {
+        if ((rf.fieldType === 'text' || rf.fieldType === 'textarea') && rf.name !== primaryKey) {
+            return rf.name;
+        }
+    }
+    if (resolvedFields.length > 0) return resolvedFields[0].name;
+    return '';
+}
+
+function convertSinglePage(backend) {
+    const warnings = [];
+    const tableName = String(backend.tableName || '');
+    const primaryKey = String(backend.primaryKey || '');
+    const fieldNames = Array.isArray(backend.fieldName) ? backend.fieldName.filter(n => typeof n === 'string') : [];
+    const datatablesQuery = String(backend.datatablesQuery || '');
+    const datatablesWhere = Array.isArray(backend.datatablesWhere) ? backend.datatablesWhere : [];
+    const fieldValidations = Array.isArray(backend.fieldValidation) ? backend.fieldValidation : [];
+
+    const cleanTable = tableName.split('.').pop() || tableName;
+    const parsedQuery = parseDatatablesQuery(datatablesQuery);
+    const resolver = new FieldTypeResolver(fieldValidations, parsedQuery, primaryKey);
+
+    const resolvedFields = fieldNames
+        .map(name => resolver.resolve(name))
+        .filter(rf => !rf.skip);
+
+    const displayField = detectDisplayField(resolvedFields, primaryKey);
+
+    const hasSearch = datatablesWhere.length > 0
+        && datatablesWhere.some(w => typeof w === 'string' && w !== 'all');
+    const hasStatusFilter = resolvedFields.some(rf => rf.name === 'is_active' || rf.name === 'status');
+
+    const features = {
+        enableSearch: hasSearch,
+        fieldLayout: 'vertical'
+    };
+
+    if (hasStatusFilter) {
+        features.enableStatusFilter = true;
+        for (const rf of resolvedFields) {
+            if ((rf.name === 'is_active' || rf.name === 'status') && rf.fieldType === 'checkbox') {
+                const cbt = (rf.extra && rf.extra.checkboxText) || {};
+                const checked = typeof cbt.checked === 'string' ? cbt.checked : 'Active';
+                const unchecked = typeof cbt.unchecked === 'string' ? cbt.unchecked : 'Inactive';
+                features.statusFilter = {
+                    field: rf.name,
+                    label: rf.label,
+                    options: [
+                        { value: 'true', text: checked },
+                        { value: 'false', text: unchecked }
+                    ]
+                };
+                break;
+            }
+        }
+    }
+
+    const fieldsArray = [];
+    for (const rf of resolvedFields) {
+        const fieldObj = { name: rf.name, label: rf.label, type: rf.fieldType };
+        if (rf.required) fieldObj.required = true;
+        if (rf.inTable) {
+            fieldObj.inTable = true;
+            if (rf.tableOrder !== null && rf.tableOrder !== undefined) {
+                fieldObj.tableOrder = rf.tableOrder;
+            }
+        }
+        if (rf.tableField) fieldObj.tableField = rf.tableField;
+        if (rf.defaultValue !== undefined) fieldObj.defaultValue = rf.defaultValue;
+        if (rf.extra && typeof rf.extra === 'object') {
+            for (const [key, val] of Object.entries(rf.extra)) {
+                fieldObj[key] = val;
+            }
+        }
+        fieldsArray.push(fieldObj);
+    }
+
+    if (backend.masterDetail !== undefined && backend.masterDetail !== null) {
+        warnings.push(`${cleanTable}: masterDetail is detected — detail tables are not yet supported, only header fields will be converted`);
+    }
+
+    const pageId = snakeToKebab(cleanTable);
+    const pageTitle = snakeToTitle(cleanTable);
+
+    const page = {
+        pageId,
+        pageTitle,
+        pageSubtitle: `Manage ${pageTitle.toLowerCase()} data`,
+        pageIcon: detectIcon(cleanTable),
+        apiPath: pageId,
+        primaryKey,
+        displayField,
+        features,
+        fields: fieldsArray
+    };
+
+    return { page, warnings };
+}
+
+function migrate(backendPayloads, appName, appCode, plugin, apiBaseUrl, port) {
+    if (!Array.isArray(backendPayloads) || backendPayloads.length === 0) {
+        return {
+            success: false,
+            payload: null,
+            pageResults: [],
+            errors: ['No backend payload was provided'],
+            warnings: []
+        };
+    }
+
+    const pages = [];
+    const pageResults = [];
+    const allWarnings = [];
+
+    for (let i = 0; i < backendPayloads.length; i++) {
+        const backend = backendPayloads[i];
+        const tableName = (backend && typeof backend.tableName === 'string') ? backend.tableName : '';
+        if (!tableName) {
+            allWarnings.push(`Payload #${i + 1}: tableName is not defined, skipped`);
+            continue;
+        }
+
+        const { page, warnings } = convertSinglePage(backend);
+
+        const fieldCount = Array.isArray(page.fields) ? page.fields.length : 0;
+        const tableColCount = Array.isArray(page.fields)
+            ? page.fields.filter(f => f.inTable === true).length
+            : 0;
+
+        pages.push(page);
+        pageResults.push({
+            pageId: page.pageId,
+            fieldCount,
+            tableColCount,
+            warnings: warnings.slice()
+        });
+        for (const w of warnings) allWarnings.push(w);
+    }
+
+    if (pages.length === 0) {
+        return {
+            success: false,
+            payload: null,
+            pageResults: [],
+            errors: ['No page was successfully converted'],
+            warnings: allWarnings
+        };
+    }
+
+    const payload = {
+        appConfig: {
+            appName,
+            appCode,
+            plugin,
+            apiBaseUrl,
+            port
+        },
+        pages
+    };
+
+    return {
+        success: true,
+        payload,
+        pageResults,
+        errors: [],
+        warnings: allWarnings
+    };
+}
+
+module.exports = { migrate, convertSinglePage, detectIcon, detectDisplayField };

package/generators/lib/migrate/field-type-resolver.js

@@ -0,0 +1,319 @@
+'use strict';
+
+/**
+ * Port dari packages/designer/src/migrators/field_type_resolver.rs.
+ *
+ * Rules engine untuk resolve tipe field frontend dari fieldValidations backend +
+ * struktur JOIN datatablesQuery. Output berupa ResolvedField yang mendeskripsikan
+ * tipe form input (text/number/date/select/checkbox/textarea/dll.), label,
+ * posisi tabel, dan extra metadata tambahan per tipe.
+ *
+ * Perbedaan dengan Rust source:
+ * - Rule 1a (PK skip) diperluas: SEMUA field dengan constraints.primaryKey === true
+ *   akan di-skip dari output fields[] apapun tipenya (uuid, string, integer, ...).
+ *   Rust source hanya skip jika type=uuid + autoGenerate. Hasil di Rust: tabel
+ *   dengan PK type=string + autoGenerate (mis. visitors.visitor_id) tetap masuk
+ *   ke fields[] sebagai text field. PK adalah identifier teknis, tidak perlu
+ *   ditampilkan di UI form.
+ */
+
+const { generateLabel } = require('./label-generator');
+const { snakeToTitle } = require('./naming');
+
+const AUDIT_FIELDS = ['created_at', 'created_by', 'updated_at', 'updated_by'];
+const TEXTAREA_FIELDS = ['address', 'description', 'notes'];
+const TEXTAREA_PREFIXES = ['remark'];
+
+const CHECKBOX_TEXT_DEFAULT = { checked: 'Yes', unchecked: 'No' };
+const CHECKBOX_TEXT_MAP = {
+    is_active: { checked: 'Active', unchecked: 'Inactive' },
+    status: { checked: 'Active', unchecked: 'Inactive' }
+};
+
+const MAXLENGTH_DEFAULTS = {
+    code: 20,
+    name: 100,
+    email: 255,
+    phone: 20,
+    textarea: 500,
+    text: 255
+};
+
+function defaultMaxlength(fieldName) {
+    if (fieldName.endsWith('_code') || fieldName === 'code') return MAXLENGTH_DEFAULTS.code;
+    if (fieldName.endsWith('_name') || fieldName === 'name') return MAXLENGTH_DEFAULTS.name;
+    if (fieldName.includes('email')) return MAXLENGTH_DEFAULTS.email;
+    if (fieldName.includes('phone')) return MAXLENGTH_DEFAULTS.phone;
+    return MAXLENGTH_DEFAULTS.text;
+}
+
+function generatePlaceholder(fieldName, label) {
+    if (fieldName.includes('email')) return 'email@example.com';
+    if (fieldName.includes('phone')) return '+62xxx';
+    if (fieldName.endsWith('_code') || fieldName === 'code') {
+        return `Enter ${label.toLowerCase()}`;
+    }
+    return '';
+}
+
+function guessDisplayCol(join) {
+    return `${join.tableName}_name`;
+}
+
+function makeSkipped(name) {
+    return { name, label: '', fieldType: '', skip: true, required: false, inTable: false, tableOrder: null, tableField: null, defaultValue: undefined, extra: {} };
+}
+
+class FieldTypeResolver {
+    constructor(fieldValidations, parsedQuery, primaryKey) {
+        this.parsedQuery = parsedQuery || { selectColumns: [], joins: [], mainTable: '', mainAlias: '' };
+        this.primaryKey = String(primaryKey || '');
+
+        this.validationMap = new Map();
+        for (const fv of (fieldValidations || [])) {
+            if (fv && typeof fv.name === 'string') {
+                this.validationMap.set(fv.name, fv);
+            }
+        }
+
+        this.joinMap = new Map();
+        for (const join of this.parsedQuery.joins) {
+            this.joinMap.set(join.localColumn, join);
+        }
+
+        const joinAliasSet = new Set(this.parsedQuery.joins.map(j => j.tableAlias));
+
+        this.selectPositions = new Map();
+        this.joinDisplayFields = new Map();
+        let pkSkipped = false;
+        let adjustedPos = 0;
+
+        for (const col of this.parsedQuery.selectColumns) {
+            if (joinAliasSet.has(col.tableAlias)) {
+                for (const join of this.parsedQuery.joins) {
+                    if (join.tableAlias === col.tableAlias) {
+                        this.joinDisplayFields.set(join.localColumn, col.name);
+                        adjustedPos += 1;
+                        this.selectPositions.set(join.localColumn, adjustedPos);
+                        break;
+                    }
+                }
+            } else if (col.name === this.primaryKey && !pkSkipped) {
+                pkSkipped = true;
+                continue;
+            } else {
+                adjustedPos += 1;
+                this.selectPositions.set(col.name, adjustedPos);
+            }
+        }
+    }
+
+    resolve(fieldName) {
+        const validation = this.validationMap.get(fieldName) || null;
+        const valType = (validation && typeof validation.type === 'string') ? validation.type : '';
+        const constraints = (validation && validation.constraints && typeof validation.constraints === 'object')
+            ? validation.constraints
+            : {};
+
+        // Rule 0a: Audit fields → skip
+        if (AUDIT_FIELDS.includes(fieldName)) {
+            return makeSkipped(fieldName);
+        }
+
+        // Rule 0b: Display-only field dari JOIN (column milik table_alias join) → skip
+        for (const join of this.parsedQuery.joins) {
+            if (!join.tableAlias) continue;
+            const belongsToJoin = this.parsedQuery.selectColumns.some(
+                col => col.tableAlias === join.tableAlias && col.name === fieldName
+            );
+            if (belongsToJoin) {
+                return makeSkipped(fieldName);
+            }
+        }
+
+        // Rule 1a (FIX): SEMUA field dengan constraints.primaryKey=true → skip
+        // (extended dari Rust source yang hanya skip type=uuid + autoGenerate)
+        if (constraints.primaryKey === true) {
+            return makeSkipped(fieldName);
+        }
+
+        // Rule 1b: PK by name tanpa validation → skip
+        if (fieldName === this.primaryKey && validation === null) {
+            return makeSkipped(fieldName);
+        }
+
+        // FK + label + posisi tabel
+        const isFk = this.joinMap.has(fieldName);
+        const label = generateLabel(fieldName, isFk);
+        const inTable = this.selectPositions.has(fieldName);
+        const tableOrder = this.selectPositions.get(fieldName) || null;
+        const tableField = this.joinDisplayFields.get(fieldName) || null;
+        const required = constraints.required === true;
+
+        // Rule 2: Boolean → checkbox
+        if (valType === 'boolean') {
+            const textMap = CHECKBOX_TEXT_MAP[fieldName] || CHECKBOX_TEXT_DEFAULT;
+            const defaultVal = Object.prototype.hasOwnProperty.call(constraints, 'default')
+                ? constraints.default
+                : true;
+            return {
+                name: fieldName,
+                label,
+                fieldType: 'checkbox',
+                skip: false,
+                required: false,
+                inTable,
+                tableOrder,
+                tableField: null,
+                defaultValue: defaultVal,
+                extra: {
+                    checkboxText: { checked: textMap.checked, unchecked: textMap.unchecked }
+                }
+            };
+        }
+
+        // Rule 3: FK with JOIN → select (API)
+        if (isFk) {
+            const join = this.joinMap.get(fieldName);
+            const displayCol = guessDisplayCol(join);
+            return {
+                name: fieldName,
+                label,
+                fieldType: 'select',
+                skip: false,
+                required,
+                inTable,
+                tableOrder,
+                tableField,
+                defaultValue: undefined,
+                extra: {
+                    dataSource: {
+                        type: 'api',
+                        resource: join.tableName,
+                        select: [join.remoteColumn, displayCol]
+                    }
+                }
+            };
+        }
+
+        // Rule 4: Number
+        if (valType === 'number') {
+            const extra = {};
+            for (const key of ['min', 'max', 'step']) {
+                if (Object.prototype.hasOwnProperty.call(constraints, key)) {
+                    extra[key] = constraints[key];
+                }
+            }
+            return {
+                name: fieldName,
+                label,
+                fieldType: 'number',
+                skip: false,
+                required,
+                inTable,
+                tableOrder,
+                tableField: null,
+                defaultValue: undefined,
+                extra
+            };
+        }
+
+        // Rule 5: String with enum → select (static)
+        if (valType === 'string' && Array.isArray(constraints.enum) && constraints.enum.length > 0) {
+            const options = constraints.enum
+                .filter(v => typeof v === 'string')
+                .map(s => ({ value: s, text: snakeToTitle(s) }));
+            return {
+                name: fieldName,
+                label,
+                fieldType: 'select',
+                skip: false,
+                required,
+                inTable,
+                tableOrder,
+                tableField: null,
+                defaultValue: undefined,
+                extra: {
+                    dataSource: { type: 'static', options }
+                }
+            };
+        }
+
+        // Rule 6: Date
+        if (fieldName.endsWith('_date') || fieldName === 'date') {
+            return {
+                name: fieldName,
+                label,
+                fieldType: 'date',
+                skip: false,
+                required,
+                inTable,
+                tableOrder,
+                tableField: null,
+                defaultValue: undefined,
+                extra: {}
+            };
+        }
+
+        // Rule 7: Time
+        if (fieldName.endsWith('_time') || fieldName === 'time') {
+            return {
+                name: fieldName,
+                label,
+                fieldType: 'time',
+                skip: false,
+                required,
+                inTable,
+                tableOrder,
+                tableField: null,
+                defaultValue: undefined,
+                extra: {}
+            };
+        }
+
+        // Rule 8: Textarea
+        const isTextarea = TEXTAREA_FIELDS.includes(fieldName)
+            || TEXTAREA_PREFIXES.some(p => fieldName.startsWith(p));
+        if (isTextarea) {
+            const maxlen = (typeof constraints.maxLength === 'number')
+                ? constraints.maxLength
+                : MAXLENGTH_DEFAULTS.textarea;
+            return {
+                name: fieldName,
+                label,
+                fieldType: 'textarea',
+                skip: false,
+                required,
+                inTable,
+                tableOrder,
+                tableField: null,
+                defaultValue: undefined,
+                extra: { rows: 3, maxlength: maxlen }
+            };
+        }
+
+        // Rule 9: Default → text
+        const maxlen = (typeof constraints.maxLength === 'number')
+            ? constraints.maxLength
+            : defaultMaxlength(fieldName);
+        const extra = { maxlength: maxlen };
+        const placeholder = generatePlaceholder(fieldName, label);
+        if (placeholder) {
+            extra.placeholder = placeholder;
+        }
+        return {
+            name: fieldName,
+            label,
+            fieldType: 'text',
+            skip: false,
+            required,
+            inTable,
+            tableOrder,
+            tableField: null,
+            defaultValue: undefined,
+            extra
+        };
+    }
+}
+
+module.exports = { FieldTypeResolver };

package/generators/lib/migrate/label-generator.js

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * Port dari packages/designer/src/migrators/label_generator.rs.
+ * Generator label field dari snake_case ke human-readable format.
+ */
+
+const { snakeToTitle } = require('./naming');
+
+const LABEL_OVERRIDES = {
+    is_active: 'Status',
+    uom: 'UOM',
+    sku: 'SKU',
+    email: 'Email',
+    phone: 'Phone',
+    url: 'URL',
+    ip: 'IP',
+    id: 'ID'
+};
+
+function generateLabel(fieldName, isForeignKey) {
+    const name = String(fieldName || '');
+
+    if (Object.prototype.hasOwnProperty.call(LABEL_OVERRIDES, name)) {
+        return LABEL_OVERRIDES[name];
+    }
+
+    if (isForeignKey && name.endsWith('_id')) {
+        const stripped = name.slice(0, -3);
+        if (stripped.length > 0) {
+            return snakeToTitle(stripped);
+        }
+    }
+
+    return snakeToTitle(name);
+}
+
+module.exports = { generateLabel };