@restforgejs/platform 5.1.21 → 5.2.0

package/generators/cli/schema/init.js

@@ -1,95 +1,95 @@
-'use strict';
-
-/**
- * Contract: schema init
- *
- * Thin wrapper untuk scaffold file schema definition. Implementasi sekarang
- * mendelegasikan ke binary native sdf-tools.exe dengan template `dummy`,
- * menggantikan generator skeleton custom yang sebelumnya inline.
- *
- * Setara dengan: sdf-tools.exe --table=dummy --generate --lang=sdf --path=<USER_PATH>
- *
- * Kontrak CLI dipertahankan (verb, category, flag --path) agar workflow user
- * tidak breaking. File yang dihasilkan berisi struktur template `dummy` dari
- * koleksi RestForge Schema Reference, yang dapat di-rename dan diadaptasi
- * sesuai kebutuhan.
- */
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
-function resolveBinaryPath() {
-    if (os.platform() !== 'win32') return null;
-    return path.resolve(__dirname, '..', '..', '..', 'bin', 'sdf-tools.exe');
-}
-
-module.exports = {
-    resource: 'schema',
-    verb: 'init',
-    description: 'Membuat skeleton file schema definition (delegate ke sdf-tools dengan template dummy)',
-    category: 'utility',
-    flags: {
-        path: {
-            type: 'string',
-            required: true,
-            description: 'Path file schema yang akan dibuat (mis. schema/users.js)'
-        }
-    },
-    examples: [
-        'npx restforge schema init --path=schema/users.js',
-        'npx restforge schema init --path=./schema/item_product.js'
-    ],
-    async handler(args) {
-        if (!args.path) {
-            console.error('Error: Target file path is required.');
-            console.error("Run 'npx restforge schema init --help' for usage information");
-            throw new Error('Target file path is required');
-        }
-
-        const binaryPath = resolveBinaryPath();
-        if (!binaryPath) {
-            const err = new Error(
-                `schema init 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 = [
-            '--table=dummy',
-            '--generate',
-            '--lang=sdf',
-            `--path=${args.path}`
-        ];
-
-        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;
-        }
-    }
-};
+'use strict';
+
+/**
+ * Contract: schema init
+ *
+ * Thin wrapper untuk scaffold file schema definition. Implementasi sekarang
+ * mendelegasikan ke binary native sdf-tools.exe dengan template `dummy`,
+ * menggantikan generator skeleton custom yang sebelumnya inline.
+ *
+ * Setara dengan: sdf-tools.exe --table=dummy --generate --lang=sdf --path=<USER_PATH>
+ *
+ * Kontrak CLI dipertahankan (verb, category, flag --path) agar workflow user
+ * tidak breaking. File yang dihasilkan berisi struktur template `dummy` dari
+ * koleksi RestForge Schema Reference, yang dapat di-rename dan diadaptasi
+ * sesuai kebutuhan.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function resolveBinaryPath() {
+    if (os.platform() !== 'win32') return null;
+    return path.resolve(__dirname, '..', '..', '..', 'bin', 'sdf-tools.exe');
+}
+
+module.exports = {
+    resource: 'schema',
+    verb: 'init',
+    description: 'Create a skeleton schema definition file (delegates to sdf-tools with a dummy template)',
+    category: 'utility',
+    flags: {
+        'schema-path': {
+            type: 'string',
+            required: true,
+            description: 'Path to the schema file to create (e.g., schema/users.js)'
+        }
+    },
+    examples: [
+        'npx restforge schema init --schema-path=schema/users.js',
+        'npx restforge schema init --schema-path=./schema/item_product.js'
+    ],
+    async handler(args) {
+        if (!args['schema-path']) {
+            console.error('Error: Target file path is required.');
+            console.error("Run 'npx restforge schema init --help' for usage information");
+            throw new Error('Target file path is required');
+        }
+
+        const binaryPath = resolveBinaryPath();
+        if (!binaryPath) {
+            const err = new Error(
+                `schema init 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 = [
+            '--table=dummy',
+            '--generate',
+            '--lang=sdf',
+            `--path=${args['schema-path']}`
+        ];
+
+        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/introspect.js

@@ -238,49 +238,49 @@ function resolveTargetPath(mode, item) {
 module.exports = {
     resource: 'schema',
     verb: 'introspect',
-    description: 'Reverse-engineer database existing menjadi schema definition (dbschema-kit factory function)',
+    description: 'Reverse-engineer an existing database into schema definitions (dbschema-kit factory function)',
     category: 'introspection',
     flags: {
         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`)'
+            description: 'Database config file (.env). Fallback to `.restforge/defaults.json` if not explicitly provided (set via `config set-default`)'
         },
         'schema-path': {
             type: 'string',
             required: true,
-            description: 'Folder atau file output schema'
+            description: 'Output folder or file for the schema'
         },
         table: {
             type: 'string',
             required: false,
             default: null,
-            description: 'Hanya satu tabel (unqualified atau qualified schema.table)'
+            description: 'Introspect only one table (unqualified or qualified schema.table)'
         },
         schema: {
             type: 'string',
             required: false,
             default: null,
-            description: 'Filter schema (single atau comma-separated)'
+            description: 'Filter by schema name (single or comma-separated)'
         },
         'all-schemas': {
             type: 'boolean',
             required: false,
             default: false,
-            description: 'Auto-detect seluruh user schemas (skip system schemas)'
+            description: 'Auto-detect all user schemas (skips system schemas)'
         },
         force: {
             type: 'boolean',
             required: false,
             default: false,
-            description: 'Timpa file existing'
+            description: 'Overwrite existing files'
         },
         'dry-run': {
             type: 'boolean',
             required: false,
             default: false,
-            description: 'Print factory function ke stdout tanpa menulis file'
+            description: 'Print factory function to stdout without writing files'
         }
     },
     examples: [

package/generators/cli/schema/list.js

@@ -67,38 +67,38 @@ function renderHumanTable(tables, schemas, dbType) {
 module.exports = {
     resource: 'schema',
     verb: 'list',
-    description: 'Menampilkan daftar tabel pada database secara live introspection',
+    description: 'List tables in the database via live introspection',
     category: 'introspection',
     flags: {
         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`)'
+            description: 'Database config file (.env). Fallback to `.restforge/defaults.json` if not explicitly provided (set via `config set-default`)'
         },
         schema: {
             type: 'string',
             required: false,
             default: null,
-            description: 'Filter berdasarkan nama schema (default: semua non-system)'
+            description: 'Filter by schema name (default: all non-system schemas)'
         },
         'include-system': {
             type: 'boolean',
             required: false,
             default: false,
-            description: 'Sertakan system schemas'
+            description: 'Include system schemas'
         },
         format: {
             type: 'string',
             required: false,
             default: 'table',
-            description: 'Format output: `table` (human-readable, di-group per schema) atau `json` (untuk AI agent / mcp-server)'
+            description: 'Output format: `table` (human-readable, grouped by schema) or `json` (for AI agent / mcp-server)'
         },
         pretty: {
             type: 'boolean',
             required: false,
             default: true,
-            description: 'Pretty-print output JSON (hanya berlaku saat --format=json)'
+            description: 'Pretty-print JSON output (only applies when --format=json)'
         }
     },
     examples: [

package/generators/cli/schema/migrate.js

@@ -77,49 +77,55 @@ function formatStatementForDisplay(stmt, dialect) {
 module.exports = {
     resource: 'schema',
     verb: 'migrate',
-    description: 'Apply schema definition ke database (load → validate → generate DDL → execute). Destruktif.',
+    description: 'Apply schema definition to database (load → validate → generate DDL → execute). Destructive.',
     category: 'management',
     flags: {
-        path: {
+        'schema-path': {
             type: 'string',
             required: true,
-            description: 'Path file atau folder schema (mis. ./schema atau ./schema/users.js)'
+            description: 'Path to schema file or directory (e.g., ./schema or ./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`)'
+            description: 'Database config file (.env). Fallback to `.restforge/defaults.json` if not explicitly provided (set via `config set-default`)'
         },
         drop: {
             type: 'boolean',
             required: false,
             default: false,
-            description: 'Drop tabel sebelum re-create (destruktif, data hilang)'
+            description: 'Drop tables before re-create (destructive, data will be lost)'
         },
         'dry-run': {
             type: 'boolean',
             required: false,
             default: false,
-            description: 'Preview DDL tanpa apply ke database'
+            description: 'Preview DDL without applying to database'
         },
         'max-name-length': {
             type: 'number',
             required: false,
             default: null,
-            description: 'Batas panjang identifier (override default per dialect: postgres=63, mysql=64, oracle=128, sqlite=63)'
+            description: 'Maximum identifier length (overrides default per dialect: postgres=63, mysql=64, oracle=128, sqlite=63)'
         },
         'auto-create-db': {
             type: 'boolean',
             required: false,
             default: false,
-            description: 'Khusus postgres/mysql. Otomatis buat database jika belum ada (skip konfirmasi interaktif). Berguna untuk mode non-interaktif (CI/CD).'
+            description: 'Postgres/MySQL only. Automatically create database if it does not exist (skips interactive confirmation). Useful for non-interactive mode (CI/CD).'
+        },
+        'auto-create-schema': {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Postgres only. Automatically create schema (namespace) if it does not exist (skips interactive confirmation). Useful for non-interactive mode (CI/CD).'
         }
     },
     examples: [
-        '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'
+        'npx restforge schema migrate --schema-path=./schema --config=db.env --dry-run',
+        'npx restforge schema migrate --schema-path=./schema --config=db.env',
+        'npx restforge schema migrate --schema-path=./schema --config=db.env --auto-create-db'
     ],
     async handler(args) {
         const resolved = resolveConfig(args.config, process.cwd());
@@ -143,7 +149,7 @@ module.exports = {
             throw err;
         }
 
-        const schemaPathArg = args.path;
+        const schemaPathArg = args['schema-path'];
         const absPath = path.resolve(process.cwd(), schemaPathArg);
 
         if (!fs.existsSync(absPath)) {
@@ -274,7 +280,7 @@ module.exports = {
             }
 
             if (testErr && isDbNotExistsError(targetDbType, testErr)) {
-                const hintParts = ['npx restforge schema migrate', `--path=${args.path}`, `--config=${args.config}`];
+                const hintParts = ['npx restforge schema migrate', `--schema-path=${args['schema-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(' ');
@@ -305,6 +311,78 @@ module.exports = {
             // dengan behavior sebelumnya.
         }
 
+        // ------------------------------------------------------------------
+        // Pre-check schema (namespace) existence untuk postgres.
+        // Bila ada schema yang belum ada, tawarkan pembuatan via dialog
+        // konfirmasi (TTY) atau flag --auto-create-schema (non-TTY).
+        //
+        // Berbeda dari missing database: setelah schema berhasil dibuat,
+        // command langsung lanjut apply DDL tanpa perlu re-run.
+        //
+        // Pre-check di-skip bila test stub aktif agar unit test tidak
+        // melakukan real network call ke database.
+        // ------------------------------------------------------------------
+        if (config.dialect === 'postgres' && !process.env.DBSCHEMA_KIT_TEST_APPLY_STUB) {
+            const {
+                checkMissingSchemas,
+                handleMissingSchemas
+            } = require('../../../src/utils/db-bootstrap');
+
+            // Ekstrak namespace dari qualified table name (mis. "mydemo.guest_book" → "mydemo")
+            const namespacesNeeded = new Set();
+            for (const qualified of models.keys()) {
+                const dotIndex = qualified.indexOf('.');
+                if (dotIndex > 0) {
+                    namespacesNeeded.add(qualified.slice(0, dotIndex));
+                }
+            }
+            namespacesNeeded.delete('public'); // public selalu ada di PostgreSQL
+
+            if (namespacesNeeded.size > 0) {
+                const connectionConfig = {
+                    host: config.host,
+                    port: config.port,
+                    user: config.user,
+                    password: config.password,
+                    database: config.database
+                };
+
+                let missingSchemas = [];
+                try {
+                    missingSchemas = await checkMissingSchemas(connectionConfig, [...namespacesNeeded]);
+                } catch (_) {
+                    // Jika check gagal, biarkan apply executor yang menangani error
+                }
+
+                if (missingSchemas.length > 0) {
+                    const schemaResult = await handleMissingSchemas({
+                        connectionConfig,
+                        missingSchemas,
+                        autoCreate: args['auto-create-schema']
+                    });
+
+                    if (schemaResult.handled && !schemaResult.created) {
+                        if (schemaResult.reason === 'user declined') {
+                            console.log('Aborted by user. No changes applied.');
+                            return;
+                        }
+                        if (schemaResult.reason === 'non-interactive' && schemaResult.hint) {
+                            console.log('');
+                            console.log(`Tip: ${schemaResult.hint}`);
+                        }
+                        if (schemaResult.reason === 'create failed') {
+                            console.error('Error: Failed to create one or more schemas. No changes applied.');
+                            throw new Error('Schema creation failed');
+                        }
+                        // non-interactive tanpa flag dan tanpa --auto-create-schema:
+                        // lanjut apply; executor akan melempar error "schema does not exist"
+                        // seperti sebelumnya (backward-compatible)
+                    }
+                    // schemaResult.created === true → lanjut apply DDL
+                }
+            }
+        }
+
         console.log('Connection target:');
         console.log(buildConnectionSummary(config));
         console.log('');

package/generators/cli/schema/models.js

@@ -67,21 +67,21 @@ function sortModels(models) {
 module.exports = {
     resource: 'schema',
     verb: 'models',
-    description: 'Menampilkan daftar schema models dengan ringkasan struktur (fields, primary key, indexes, uniques, relations)',
+    description: 'List schema models with a structure summary (fields, primary key, indexes, uniques, relations)',
     category: 'introspection',
     flags: {
-        path: {
+        'schema-path': {
             type: 'string',
             required: true,
-            description: 'Path file atau folder schema (mis. ./schema atau ./schema/users.js)'
+            description: 'Path to schema file or directory (e.g., ./schema or ./schema/users.js)'
         }
     },
     examples: [
-        'npx restforge schema models --path=./schema',
-        'npx restforge schema models --path=./custom-schema'
+        'npx restforge schema models --schema-path=./schema',
+        'npx restforge schema models --schema-path=./custom-schema'
     ],
     async handler(args) {
-        const schemaPath = args.path;
+        const schemaPath = args['schema-path'];
         const absPath = path.resolve(process.cwd(), schemaPath);
 
         let models;