@restforgejs/platform 5.1.0 → 5.1.4

package/generators/cli/data/pull.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Contract: data pull
+ *
+ * Export isi sebuah tabel database ke file envelope JSON
+ * (`{cwd}/data-storage/<table>.json`) dengan whitelist kolom dan metadata
+ * bersumber MURNI dari SDF (Schema Definition File), bukan introspeksi DB.
+ *
+ * Eksekusi via jalur CLI generator (cli-entry.js) tanpa gerbang license/integrity
+ * (amandemen arah B, lihat docs/plan/data-pull-push/data-pull-push-09-amendments.md).
+ * Handler tetap tipis: seluruh logika berada di lib/data/pull-runner.js.
+ *
+ * Catatan: flag `--schema` (namespace) TIDAK dideklarasikan — namespace tabel
+ * diambil dari SDF IR (amandemen A4). Lokasi SDF ditentukan `--schema-path`.
+ */
+
+module.exports = {
+    resource: 'data',
+    verb: 'pull',
+    description: 'Export isi tabel database ke file envelope JSON (data-storage/<table>.json) berdasarkan metadata SDF',
+    category: 'introspection',
+    flags: {
+        table: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Nama tabel sumber yang akan di-pull (harus terdaftar di SDF)'
+        },
+        'all-tables': {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Pull seluruh tabel yang terdaftar di --schema-path (mutual-exclusive dengan --table)'
+        },
+        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`)'
+        },
+        'schema-path': {
+            type: 'string',
+            required: false,
+            default: 'schema',
+            description: 'Lokasi SDF (file atau folder) sumber metadata tabel'
+        },
+        format: {
+            type: 'string',
+            required: false,
+            default: 'json',
+            description: "Format penyimpanan nilai; saat ini hanya menerima 'json'"
+        },
+        limit: {
+            type: 'number',
+            required: false,
+            default: null,
+            description: 'Batas maksimum total rows yang di-export (null = seluruh tabel)'
+        },
+        'batch-size': {
+            type: 'number',
+            required: false,
+            default: 1000,
+            description: 'Ukuran batch baca internal dari database'
+        },
+        'storage-path': {
+            type: 'string',
+            required: false,
+            default: 'data-storage',
+            description: 'Folder output relatif terhadap working directory'
+        },
+        force: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Overwrite file output bila sudah ada'
+        },
+        json: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Output ringkasan dalam format JSON (untuk konsumsi CI/CD)'
+        }
+    },
+    examples: [
+        'npx restforge data pull --table=visitors',
+        'npx restforge data pull --all-tables --config=db.env',
+        'npx restforge data pull --all-tables --config=db.env --json',
+        'npx restforge data pull --table=visitors --config=db.env --limit=500',
+        'npx restforge data pull --table=visitors --config=db.env --json'
+    ],
+    async handler(args) {
+        return require('../../lib/data/pull-runner').run(args);
+    }
+};

package/generators/cli/data/push.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Contract: data push
+ *
+ * Muat isi file envelope JSON (`{cwd}/data-storage/<qualifiedName>.json`) ke tabel
+ * tujuan via INSERT batch dengan commit per batch. Nama file diturunkan dari SDF
+ * (aturan IDENTIK `data pull`, bukan dari flag `--table` mentah). Metadata kolom +
+ * tipe canonical bersumber MURNI dari SDF; konversi nilai per dialect tujuan
+ * ditangani value-codec.
+ *
+ * Eksekusi via jalur CLI generator (cli-entry.js) tanpa gerbang license/integrity
+ * (amandemen arah B, lihat docs/plan/data-pull-push/data-pull-push-09-amendments.md).
+ * Handler tetap tipis: seluruh logika berada di lib/data/push-runner.js.
+ *
+ * Push bersifat append-only (amandemen A6, User konfirmasi 2026-06-03). Mode
+ * `upsert`/`replace` di-descope dari v1, sehingga flag `--mode` dan `--force`
+ * TIDAK dideklarasikan. Push selalu menjalankan jalur append (INSERT batch +
+ * commit per batch). `--mode=...`/`--force` kini menjadi unknown flag → ditolak
+ * arg-parser dengan exit 2 (perilaku standar).
+ *
+ * Catatan: flag `--schema` (namespace) TIDAK dideklarasikan — namespace tabel
+ * diambil dari SDF IR (amandemen A4). Lokasi SDF ditentukan `--schema-path`.
+ */
+
+module.exports = {
+    resource: 'data',
+    verb: 'push',
+    description: 'Muat isi file envelope JSON (data-storage/<table>.json) ke tabel tujuan via INSERT batch berdasarkan metadata SDF',
+    category: 'management',
+    flags: {
+        table: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Nama tabel tujuan yang akan di-push (harus terdaftar di SDF)'
+        },
+        'all-tables': {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Push seluruh tabel yang punya file di --storage-path, urut topological FK parent→child (mutual-exclusive dengan --table)'
+        },
+        config: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'File config database tujuan (.env). Fallback ke `.restforge/defaults.json` bila tidak disediakan eksplisit (set via `config set-default`)'
+        },
+        'schema-path': {
+            type: 'string',
+            required: false,
+            default: 'schema',
+            description: 'Lokasi SDF (file atau folder) sumber metadata tabel'
+        },
+        'storage-path': {
+            type: 'string',
+            required: false,
+            default: 'data-storage',
+            description: 'Folder sumber file envelope relatif terhadap working directory'
+        },
+        'batch-size': {
+            type: 'number',
+            required: false,
+            default: 1000,
+            description: 'Ukuran batch INSERT, sekaligus unit commit per batch'
+        },
+        json: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Output ringkasan dalam format JSON (untuk konsumsi CI/CD)'
+        }
+    },
+    examples: [
+        'npx restforge data push --table=visitors',
+        'npx restforge data push --all-tables --config=db.env',
+        'npx restforge data push --all-tables --config=db.env --json',
+        'npx restforge data push --table=visitors --config=db.env --batch-size=500',
+        'npx restforge data push --table=visitors --config=db.env --json'
+    ],
+    async handler(args) {
+        return require('../../lib/data/push-runner').run(args);
+    }
+};

package/generators/cli/fast-track.js

@@ -18,9 +18,6 @@
  * Scope Frontend (dan bagian frontend pada ALL) juga dieksekusi NYATA: payload
  * migrate (RDF -> UDF) per tabel -> restforge-designer activate -> generate.
  *
- * Flag `--sim-no-designer` memaksa cabang dialog "designer NOT FOUND" untuk
- * keperluan uji (mem-bypass probe `restforge-designer --version`).
- *
  * Catatan: contract ini global verb (snapshot key = `fast-track`), file berada
  * di root `generators/cli/` sehingga ter-discover otomatis sejajar dengan `init`.
  */
@@ -246,19 +243,15 @@ function collectTables(schemaDir) {
 // Preflight: cek dependency restforge-designer (sebelum input konfigurasi)
 // ---------------------------------------------------------------------------
 
-function checkDesigner(args) {
+function checkDesigner() {
     console.log('');
     console.log('[Preflight]');
 
-    // Probe nyata: jalankan `restforge-designer --version`. Flag --sim-no-designer
-    // memaksa cabang NOT FOUND untuk keperluan uji dialog.
-    let found = false;
+    // Probe nyata: jalankan `restforge-designer --version`.
+    const r = spawnSync('cmd', ['/S', '/C', 'restforge-designer --version'], { encoding: 'utf8' });
+    const found = !r.error && r.status === 0;
     let version = '';
-    if (!args['sim-no-designer']) {
-        const r = spawnSync('cmd', ['/S', '/C', 'restforge-designer --version'], { encoding: 'utf8' });
-        found = !r.error && r.status === 0;
-        if (found && r.stdout) version = r.stdout.trim().split(/\r?\n/)[0];
-    }
+    if (found && r.stdout) version = r.stdout.trim().split(/\r?\n/)[0];
 
     if (!found) {
         console.log(leader('  > restforge-designer', 'NOT FOUND', 32));
@@ -838,7 +831,7 @@ module.exports = {
             required: true,
             description: 'Nama project/aplikasi (mis. visitors-app)'
         },
-        schema: {
+        'schema-path': {
             type: 'string',
             required: true,
             description: 'Folder berisi SDF aplikasi (relatif cwd)'
@@ -860,22 +853,16 @@ module.exports = {
             required: false,
             default: false,
             description: 'Mode destruktif: drop table & regenerate (perlu konfirmasi y/N)'
-        },
-        'sim-no-designer': {
-            type: 'boolean',
-            required: false,
-            default: false,
-            description: '[preview] Paksa cabang dialog "restforge-designer NOT FOUND" (scope frontend)'
         }
     },
     examples: [
-        'npx restforge fast-track --project=visitors-app --schema=./schema',
-        'npx restforge fast-track --project=visitors-app --schema=./schema --config=db-connection.env',
-        'npx restforge fast-track --project=visitors-app --schema=./schema --overwrite'
+        'npx restforge fast-track --project=visitors-app --schema-path=./schema',
+        'npx restforge fast-track --project=visitors-app --schema-path=./schema --config=db-connection.env',
+        'npx restforge fast-track --project=visitors-app --schema-path=./schema --overwrite'
     ],
     async handler(args) {
         const cwd = process.cwd();
-        const schemaDir = path.resolve(cwd, args.schema);
+        const schemaDir = path.resolve(cwd, args['schema-path']);
         const { names: tables } = collectTables(schemaDir);
 
         const prompter = createPrompter();
@@ -888,13 +875,13 @@ module.exports = {
 
             // 3) Preflight designer hanya bila scope mencakup frontend.
             if (scope.frontend) {
-                checkDesigner(args);
+                checkDesigner();
             }
 
             const ctx = {
                 cwd,
                 project: args.project,
-                schemaFlag: args.schema,
+                schemaFlag: args['schema-path'],
                 configFlag: args.config,
                 tables,
                 cfg,

package/generators/cli/schema/introspect.js

@@ -180,7 +180,7 @@ function parseSchemaFlag(value) {
 }
 
 function resolveMode(args, schemaList, tableQualified) {
-    const out = args.output;
+    const out = args['schema-path'];
     const isDry = args['dry-run'];
 
     if (isDry && !out) {
@@ -200,7 +200,7 @@ function resolveMode(args, schemaList, tableQualified) {
             if (expectedBase !== targetTableName) {
                 return {
                     error: `Single-mode output filename '${path.basename(out)}' does not match --table='${targetTableName}'. ` +
-                        `Use --output=<folder> or rename the file to '${targetTableName}.js'.`
+                        `Use --schema-path=<folder> or rename the file to '${targetTableName}.js'.`
                 };
             }
             return { kind: 'single-file', file: path.resolve(out), table: targetTableName };
@@ -209,7 +209,7 @@ function resolveMode(args, schemaList, tableQualified) {
     }
 
     if (looksLikeJs) {
-        return { error: `Bulk mode requires a folder for --output, got file '${out}'. Specify a folder or add --table=<name>.` };
+        return { error: `Bulk mode requires a folder for --schema-path, got file '${out}'. Specify a folder or add --table=<name>.` };
     }
 
     const isMultiSchema = (args['all-schemas']) || (Array.isArray(schemaList) && schemaList.length > 1);
@@ -242,7 +242,7 @@ module.exports = {
             default: null,
             description: 'File config database (.env). Fallback ke `.restforge/defaults.json` bila tidak disediakan eksplisit (set via `config set-default`)'
         },
-        output: {
+        'schema-path': {
             type: 'string',
             required: true,
             description: 'Folder atau file output schema'
@@ -279,9 +279,9 @@ module.exports = {
         }
     },
     examples: [
-        'npx restforge schema introspect --config=db.env --output=./schema',
-        'npx restforge schema introspect --config=db.env --output=./schema --table=users --dry-run',
-        'npx restforge schema introspect --config=db.env --output=./schema --all-schemas --force'
+        'npx restforge schema introspect --config=db.env --schema-path=./schema',
+        'npx restforge schema introspect --config=db.env --schema-path=./schema --table=users --dry-run',
+        'npx restforge schema introspect --config=db.env --schema-path=./schema --all-schemas --force'
     ],
     async handler(args) {
         const resolvedConfigResult = resolveConfig(args.config, process.cwd());
@@ -291,9 +291,9 @@ module.exports = {
             throw new Error('--config=<file> is required');
         }
 
-        if (!args['dry-run'] && !args.output) {
-            console.error('Error: --output=<path> is required (or use --dry-run to preview to stdout).');
-            throw new Error('--output=<path> is required');
+        if (!args['dry-run'] && !args['schema-path']) {
+            console.error('Error: --schema-path=<path> is required (or use --dry-run to preview to stdout).');
+            throw new Error('--schema-path=<path> is required');
         }
 
         if (resolvedConfigResult.source === 'default') {