'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);
    }
};
