@restforgejs/platform 4.1.1 → 4.3.1

package/generators/cli/schema/migrate.js

@@ -22,8 +22,6 @@ const { splitStatements } = require('../../lib/dbschema-kit/statement-splitter')
 const { applyIfNotExistsModifier } = require('../../lib/dbschema-kit/statement-modifier');
 const { resolveConfig, printDefaultConfigWarning } = require('../../lib/utils/config-resolver');
 
-const DEFAULT_PATH = './schema';
-
 // Mapping dialect (internal naming di dbschema-kit) ke dbType (naming yang
 // dipakai db-bootstrap helper). Hanya postgres dan mysql yang relevan untuk
 // flow "create database if missing".
@@ -82,10 +80,16 @@ module.exports = {
     description: 'Apply schema definition ke database (load → validate → generate DDL → execute). Destruktif.',
     category: 'management',
     flags: {
-        config: {
+        path: {
             type: 'string',
             required: true,
-            description: 'File config database (.env)'
+            description: 'Path file atau folder schema (mis. ./schema atau ./schema/users.js)'
+        },
+        config: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'File config database (.env). Fallback ke `.restforge/defaults.json` bila tidak disediakan eksplisit (set via `config set-default`)'
         },
         drop: {
             type: 'boolean',
@@ -112,18 +116,10 @@ module.exports = {
             description: 'Khusus postgres/mysql. Otomatis buat database jika belum ada (skip konfirmasi interaktif). Berguna untuk mode non-interaktif (CI/CD).'
         }
     },
-    positional: [
-        {
-            name: 'path',
-            type: 'string',
-            required: false,
-            description: 'Path file atau folder schema (default: ./schema)'
-        }
-    ],
     examples: [
-        'npx restforge schema migrate ./schema --config=db.env --dry-run',
-        'npx restforge schema migrate ./schema --config=db.env',
-        'npx restforge schema migrate ./schema --config=db.env --auto-create-db'
+        'npx restforge schema migrate --path=./schema --config=db.env --dry-run',
+        'npx restforge schema migrate --path=./schema --config=db.env',
+        'npx restforge schema migrate --path=./schema --config=db.env --auto-create-db'
     ],
     async handler(args) {
         const resolved = resolveConfig(args.config, process.cwd());
@@ -147,7 +143,7 @@ module.exports = {
             throw err;
         }
 
-        const schemaPathArg = args.path || DEFAULT_PATH;
+        const schemaPathArg = args.path;
         const absPath = path.resolve(process.cwd(), schemaPathArg);
 
         if (!fs.existsSync(absPath)) {
@@ -258,8 +254,7 @@ module.exports = {
             }
 
             if (testErr && isDbNotExistsError(targetDbType, testErr)) {
-                const schemaArg = args.path || DEFAULT_PATH;
-                const hintParts = ['npx restforge schema migrate', schemaArg, `--config=${args.config}`];
+                const hintParts = ['npx restforge schema migrate', `--path=${args.path}`, `--config=${args.config}`];
                 if (args.drop === true) hintParts.push('--drop=true');
                 if (args['auto-create-db']) hintParts.push('--auto-create-db');
                 const commandHint = hintParts.join(' ');

package/generators/cli/schema/models.js

@@ -14,8 +14,6 @@
 const path = require('path');
 const { loadSchemaPath } = require('../../lib/dbschema-kit/loader');
 
-const DEFAULT_PATH = './schema';
-
 const COL_SCHEMA = 12;
 const COL_TABLE = 25;
 const COL_FIELDS = 8;
@@ -71,21 +69,19 @@ module.exports = {
     verb: 'models',
     description: 'Menampilkan daftar schema models dengan ringkasan struktur (fields, primary key, indexes, uniques, relations)',
     category: 'introspection',
-    flags: {},
-    positional: [
-        {
-            name: 'path',
+    flags: {
+        path: {
             type: 'string',
-            required: false,
-            description: 'Path folder schema (default: ./schema)'
+            required: true,
+            description: 'Path file atau folder schema (mis. ./schema atau ./schema/users.js)'
         }
-    ],
+    },
     examples: [
-        'npx restforge schema models',
-        'npx restforge schema models ./schema'
+        'npx restforge schema models --path=./schema',
+        'npx restforge schema models --path=./custom-schema'
     ],
     async handler(args) {
-        const schemaPath = args.path || DEFAULT_PATH;
+        const schemaPath = args.path;
         const absPath = path.resolve(process.cwd(), schemaPath);
 
         let models;

package/generators/cli/schema/template.js

@@ -0,0 +1,222 @@
+'use strict';
+
+/**
+ * Contract: schema template
+ *
+ * Browse, preview, dan generate template schema dari koleksi RestForge Schema
+ * Reference (85 template, 30 domain, 33 section). Verb ini bertindak sebagai
+ * wrapper terhadap binary native `sdf-tools.exe` yang di-ship melalui folder
+ * bin/. Semua filter dan display flag diteruskan ke binary; help text di sisi
+ * Node mempertahankan kontrak CLI (contract validator + help generator).
+ *
+ * Binary lookup: <package-root>/bin/sdf-tools.exe relatif terhadap file ini
+ * (resolusi sama untuk source workspace dan installation di node_modules).
+ *
+ * Platform: saat ini hanya Windows (sdf-tools.exe). Pemanggilan di non-Windows
+ * akan return error eksplisit, bukan crash diam-diam.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const VALUE_FLAGS = ['domain', 'table', 'category', 'pattern', 'section', 'lang', 'path', 'format'];
+const BOOLEAN_FLAGS = [
+    'has-sdf',
+    'no-sdf',
+    'show',
+    'example',
+    'generate',
+    'force',
+    'list-domains',
+    'list-categories',
+    'list-sections',
+    'stats'
+];
+
+function resolveBinaryPath() {
+    if (os.platform() !== 'win32') return null;
+    return path.resolve(__dirname, '..', '..', '..', 'bin', 'sdf-tools.exe');
+}
+
+function buildBinaryArgs(args) {
+    const out = [];
+    for (const name of VALUE_FLAGS) {
+        const value = args[name];
+        if (value === undefined || value === null || value === '') continue;
+        out.push(`--${name}=${value}`);
+    }
+    for (const name of BOOLEAN_FLAGS) {
+        if (args[name] === true) {
+            out.push(`--${name}`);
+        }
+    }
+    return out;
+}
+
+module.exports = {
+    resource: 'schema',
+    verb: 'template',
+    description: 'Browse, preview, dan generate template schema dari koleksi RestForge Schema Reference',
+    category: 'utility',
+    flags: {
+        domain: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Filter berdasarkan domain (csv, mis. erp atau erp,finance)'
+        },
+        table: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Filter nama tabel (wildcard glob: sales*, *_invoice)'
+        },
+        category: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Filter category: master-data atau transactional'
+        },
+        pattern: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Filter pattern: single-table atau master-detail'
+        },
+        section: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Filter section code (lihat --list-sections)'
+        },
+        'has-sdf': {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Filter hanya template yang sudah punya versi SDF'
+        },
+        'no-sdf': {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Filter hanya template yang belum punya SDF (gap analysis)'
+        },
+        show: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Cetak schema template (perlu --table=<nama_spesifik>)'
+        },
+        example: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Sertakan section CONTOH DATA (kombinasi dengan --show)'
+        },
+        lang: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Format schema: sdf (default) atau sql'
+        },
+        generate: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Generate template ke filesystem (perlu --table dan --path)'
+        },
+        path: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Path destination untuk --generate (direktori atau file)'
+        },
+        force: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Overwrite file destination existing saat --generate'
+        },
+        'list-domains': {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'List semua domain aplikasi yang tersedia'
+        },
+        'list-categories': {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'List semua category template'
+        },
+        'list-sections': {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'List semua section beserta category-nya'
+        },
+        stats: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Tampilkan statistik koleksi (per category, pattern, domain, section)'
+        },
+        format: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Format output: table (default), plain, atau json'
+        }
+    },
+    examples: [
+        'npx restforge schema template',
+        'npx restforge schema template --domain=erp',
+        'npx restforge schema template --domain=erp,inventory --category=master-data',
+        'npx restforge schema template --table=sales_order --show',
+        'npx restforge schema template --table=sales_order --show --lang=sql',
+        'npx restforge schema template --table=sales_order --generate --path=./schema --lang=sdf',
+        'npx restforge schema template --stats',
+        'npx restforge schema template --list-domains'
+    ],
+    async handler(args) {
+        const binaryPath = resolveBinaryPath();
+        if (!binaryPath) {
+            const err = new Error(
+                `schema template hanya tersedia di Windows (sdf-tools.exe). Platform saat ini: ${os.platform()}`
+            );
+            err.exitCode = 3;
+            throw err;
+        }
+
+        if (!fs.existsSync(binaryPath)) {
+            const err = new Error(
+                `sdf-tools.exe tidak ditemukan di ${binaryPath}. ` +
+                'Pastikan binary sudah di-build dan tersedia di folder bin/ package.'
+            );
+            err.exitCode = 3;
+            throw err;
+        }
+
+        const binaryArgs = buildBinaryArgs(args);
+        const result = spawnSync(binaryPath, binaryArgs, {
+            stdio: 'inherit',
+            windowsHide: true
+        });
+
+        if (result.error) {
+            const err = new Error(`Gagal menjalankan sdf-tools.exe: ${result.error.message}`);
+            err.exitCode = 1;
+            throw err;
+        }
+
+        const status = typeof result.status === 'number' ? result.status : 1;
+        if (status !== 0) {
+            const err = new Error(`sdf-tools.exe exit code ${status}`);
+            err.exitCode = status;
+            err.silent = true;
+            throw err;
+        }
+    }
+};

package/generators/cli/schema/validate.js

@@ -22,8 +22,6 @@ const { validateCheckCompatibility } = require('../../lib/dbschema-kit/validator
 const { reportHuman, getExitCode } = require('../../lib/dbschema-kit/validator/validator-reporter');
 const { defineModel } = require('../../lib/dbschema-kit/define-model');
 
-const DEFAULT_PATH = './schema';
-
 function listSchemaFiles(absPath) {
     const fs = require('fs');
     const stat = fs.statSync(absPath);
@@ -67,21 +65,19 @@ module.exports = {
     verb: 'validate',
     description: 'Memvalidasi file schema definition (single-model dan cross-model)',
     category: 'introspection',
-    flags: {},
-    positional: [
-        {
-            name: 'path',
+    flags: {
+        path: {
             type: 'string',
-            required: false,
-            description: 'Path file atau folder schema (default: ./schema)'
+            required: true,
+            description: 'Path file atau folder schema (mis. ./schema atau ./schema/users.js)'
         }
-    ],
+    },
     examples: [
-        'npx restforge schema validate',
-        'npx restforge schema validate ./my-schema'
+        'npx restforge schema validate --path=./schema',
+        'npx restforge schema validate --path=./my-schema'
     ],
     async handler(args) {
-        const schemaPath = args.path || DEFAULT_PATH;
+        const schemaPath = args.path;
         const absPath = path.resolve(process.cwd(), schemaPath);
 
         let models;

package/generators/cli-entry.js

@@ -162,11 +162,26 @@ async function dispatch(argv, options = {}) {
         await contract.handler(parseResult.args);
         return 0;
     } catch (handlerErr) {
-        const message = handlerErr && handlerErr.message ? handlerErr.message : String(handlerErr);
-        writeLine(stderr, `Error: ${message}`);
+        // Handler dapat men-set property `silent: true` untuk men-suppress
+        // pesan "Error: ..." (mis. payload validate/diff/sync yang sudah
+        // print verdict lengkap dan tidak perlu redundant error message).
+        // DEBUG mode tetap tampilkan stack untuk troubleshooting.
+        if (!handlerErr || handlerErr.silent !== true) {
+            const message = handlerErr && handlerErr.message ? handlerErr.message : String(handlerErr);
+            writeLine(stderr, `Error: ${message}`);
+        }
         if (process.env.DEBUG && handlerErr && handlerErr.stack) {
             writeLine(stderr, handlerErr.stack);
         }
+        // Handler dapat men-set property `exitCode` pada Error untuk override
+        // default exit code 1. Dipakai oleh validasi schema di `endpoint create`
+        // yang membedakan drift (1) vs usage (2) vs connection (3).
+        const customCode = handlerErr && Number.isInteger(handlerErr.exitCode)
+            ? handlerErr.exitCode
+            : null;
+        if (customCode !== null && customCode >= 0 && customCode <= 255) {
+            return customCode;
+        }
         return 1;
     }
 }