@restforgejs/platform 5.0.9 → 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);
+    }
+};