@restforgejs/platform 5.1.0 → 5.1.6

package/generators/cli/data/pull.js

@@ -0,0 +1,104 @@
+'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: scope tabel dipilih lewat tepat satu dari `--table` / `--schema` /
+ * `--all-schemas`. Flag `--schema` di sini adalah FILTER scope (bukan penentu
+ * namespace) — namespace tabel tetap diambil dari SDF IR (amandemen A4). Lokasi
+ * SDF ditentukan `--schema-path`. Layout output: bersarang `<schema>/<table>.json`
+ * untuk tabel ber-schema, flat `<table>.json` untuk tabel tanpa schema.
+ */
+
+module.exports = {
+    resource: 'data',
+    verb: 'pull',
+    description: 'Export isi tabel database ke file envelope JSON (data-storage/<schema>/<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)'
+        },
+        schema: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Filter schema: satu atau comma-separated (mutual-exclusive dengan --table/--all-schemas)'
+        },
+        'all-schemas': {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Pull seluruh tabel di semua schema (mutual-exclusive dengan --table/--schema)'
+        },
+        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 --schema=public --config=db.env',
+        'npx restforge data pull --all-schemas --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,95 @@
+'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: scope tabel dipilih lewat tepat satu dari `--table` / `--schema` /
+ * `--all-schemas`. Flag `--schema` adalah FILTER scope (bukan penentu namespace) —
+ * namespace tabel tetap diambil dari SDF IR (amandemen A4). Lokasi SDF ditentukan
+ * `--schema-path`. Path input mengikuti aturan IDENTIK pull (bersarang
+ * `<schema>/<table>.json` untuk tabel ber-schema, flat `<table>.json` untuk tabel
+ * tanpa schema).
+ */
+
+module.exports = {
+    resource: 'data',
+    verb: 'push',
+    description: 'Muat isi file envelope JSON (data-storage/<schema>/<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)'
+        },
+        schema: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Filter schema: satu atau comma-separated (mutual-exclusive dengan --table/--all-schemas)'
+        },
+        'all-schemas': {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Push seluruh tabel di semua schema, urut topological FK parent→child (mutual-exclusive dengan --table/--schema)'
+        },
+        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 --schema=public --config=db.env',
+        'npx restforge data push --all-schemas --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,