@restforgejs/platform 5.0.8 → 5.1.0

package/generators/cli/fast-track.js

@@ -0,0 +1,963 @@
+'use strict';
+
+/**
+ * Contract: fast-track (verb global)
+ *
+ * Orkestrator alur pembangunan aplikasi RESTForge dari rencana di
+ * `docs/plan/fast-track-command.md`. Alur dialog: input konfigurasi (LICENSE +
+ * database) -> menu scope -> preview + konfirmasi -> eksekusi.
+ *
+ * Scope REST API (dan bagian backend pada scope ALL) dieksekusi NYATA dengan
+ * mengorkestrasi command restforge existing (urutan mengikuti referensi
+ * `restforge-playbook/fast-track.mjs` dan `quick-start.mjs`):
+ *   ensureEnv -> validate -> config set-default -> schema migrate (folder)
+ *   -> per tabel: payload generate + endpoint create.
+ * Setelah generate, command menawarkan menjalankan runtime server di window
+ * CMD baru (Windows).
+ *
+ * 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`.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const http = require('node:http');
+const readline = require('node:readline');
+const { spawnSync } = require('node:child_process');
+
+// ---------------------------------------------------------------------------
+// Default konfigurasi (selaras dengan restforge-playbook/fast-track.mjs)
+// ---------------------------------------------------------------------------
+
+const DEFAULTS = {
+    LICENSE: '8ECD-92A4-86BB-698Q',
+    SERVER_ADDRESS: '127.0.0.1',
+    SERVER_PORT: '3000',
+    WEB_SERVER_PORT: '8000',
+    DB_TYPE: 'postgresql',
+    DB_HOST: '127.0.0.1',
+    DB_PORT: '5432',
+    DB_USER: 'postgres',
+    DB_PASSWORD: 'postgres1234',
+    DB_NAME: 'dbsandbox',
+    DB_FILE: './data/sandbox.db'
+};
+
+const DEFAULT_CONFIG_FILE = 'db-connection.env';
+
+// Default DB_PORT/DB_USER/DB_NAME menyesuaikan DB_TYPE yang dipilih; bila tidak
+// terdaftar, fallback ke DEFAULTS.
+const DB_TYPE_DEFAULTS = {
+    postgresql: { DB_PORT: '5432', DB_USER: 'postgres' },
+    postgres:   { DB_PORT: '5432', DB_USER: 'postgres' },
+    mysql:      { DB_PORT: '3306', DB_USER: 'root' },
+    oracle:     { DB_PORT: '1521', DB_USER: 'oracle', DB_NAME: 'ORCL' }
+};
+
+// Pilihan scope generate. Frontend selalu menyertakan REST API: payload migrate
+// (RDF -> UDF) butuh file RDF dari pipeline REST API, dan runtime UI fetch ke
+// REST API server. Maka tidak ada opsi "frontend only". Default '2' (REST API +
+// frontend) selaras dengan pola dialog lain yang memakai default saat Enter.
+const SCOPES = {
+    '1': { key: 'backend', label: 'REST API only',              backend: true, frontend: false },
+    '2': { key: 'all',     label: 'REST API + Frontend app',    backend: true, frontend: true }
+};
+const DEFAULT_SCOPE = '2';
+
+// Map DB_TYPE (nilai pada db-connection.env) ke token flag `--database` pada
+// endpoint create. Env memakai 'postgresql', CLI mengharapkan 'postgres'.
+const DB_FLAG = {
+    postgresql: 'postgres',
+    postgres: 'postgres',
+    mysql: 'mysql',
+    oracle: 'oracle',
+    sqlite: 'sqlite'
+};
+
+// ---------------------------------------------------------------------------
+// Helper output
+// ---------------------------------------------------------------------------
+
+const LEADER_WIDTH = 36;
+
+/**
+ * Membangun baris ber-leader titik: `label .......... value`.
+ */
+function leader(label, value, width = LEADER_WIDTH, fill = '.') {
+    let line = `${label} `;
+    while (line.length < width) line += fill;
+    return `${line} ${value}`;
+}
+
+function rule(char = '=', width = 64) {
+    return char.repeat(width);
+}
+
+/**
+ * Membuat satu prompter berbasis queue baris untuk dipakai sepanjang command.
+ *
+ * Memakai `rl.question` berturut-turut pada input yang di-pipe tidak reliable:
+ * baris yang datang pada celah antar-prompt ter-emit tanpa handler dan hilang,
+ * lalu EOF membuat prompt berikutnya menggantung. Pendekatan ini menampung
+ * setiap event `line` ke dalam queue sehingga tidak ada input yang hilang, dan
+ * mengembalikan string kosong saat EOF (input habis).
+ */
+function createPrompter() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const lineQueue = [];
+    const waiters = [];
+    let closed = false;
+
+    rl.on('line', (line) => {
+        if (waiters.length > 0) waiters.shift()(line);
+        else lineQueue.push(line);
+    });
+    rl.on('close', () => {
+        closed = true;
+        while (waiters.length > 0) waiters.shift()('');
+    });
+
+    const ask = (message) => {
+        return new Promise((resolve) => {
+            // Saat input di-pipe (bukan TTY), readline tidak meng-echo newline,
+            // sehingga prompt berurutan menumpuk di satu baris. Echo newline
+            // manual agar transcript non-interaktif tetap terbaca.
+            const finish = (val) => {
+                if (!process.stdin.isTTY) process.stdout.write('\n');
+                resolve(val);
+            };
+
+            // Input sudah ter-buffer (umumnya mode pipe): tampilkan label prompt
+            // langsung lalu konsumsi dari queue, tanpa line-editor.
+            if (lineQueue.length > 0) {
+                process.stdout.write(message);
+                finish(lineQueue.shift());
+                return;
+            }
+            if (closed) {
+                process.stdout.write(message);
+                finish('');
+                return;
+            }
+
+            // Mode interaktif: serahkan rendering prompt ke readline via
+            // setPrompt/prompt agar readline mengetahui lebar prompt dan
+            // line-editing (backspace, panah, Ctrl+U) berfungsi benar. Menulis
+            // prompt manual membuat readline me-refresh baris dari kolom 0 dengan
+            // prompt default ("> ") sehingga teks prompt asli terhapus saat backspace.
+            rl.setPrompt(message);
+            rl.prompt();
+            waiters.push(finish);
+        });
+    };
+
+    return { ask, close: () => rl.close() };
+}
+
+/**
+ * Error yang menghentikan command tanpa pesan "Error: ..." tambahan dari
+ * cli-entry (dialog sudah mencetak konteksnya sendiri).
+ */
+function stop(message) {
+    const err = new Error(message || 'fast-track stopped');
+    err.silent = true;
+    return err;
+}
+
+/**
+ * Masking license untuk tampilan preview: grup pertama dan terakhir terlihat,
+ * grup tengah disamarkan (mis. `8ECD-****-****-698Q`). Hanya untuk tampilan —
+ * nilai asli tetap dipakai untuk penulisan env dan command.
+ */
+function maskLicense(license) {
+    if (!license || typeof license !== 'string') return license;
+    const groups = license.split('-');
+    if (groups.length >= 3) {
+        return groups
+            .map((g, i) => (i === 0 || i === groups.length - 1) ? g : '*'.repeat(g.length))
+            .join('-');
+    }
+    if (license.length > 8) {
+        return `${license.slice(0, 4)}${'*'.repeat(license.length - 8)}${license.slice(-4)}`;
+    }
+    return license;
+}
+
+/**
+ * Representasi database untuk baris preview, berdasarkan konfigurasi input.
+ */
+function describeDatabase(cfg) {
+    if (cfg.DB_TYPE === 'sqlite') return `sqlite @ ${cfg.DB_FILE}`;
+    return `${cfg.DB_TYPE} @ ${cfg.DB_HOST}:${cfg.DB_PORT}/${cfg.DB_NAME}`;
+}
+
+// ---------------------------------------------------------------------------
+// Pengumpulan data preview (read-only, tanpa efek samping)
+// ---------------------------------------------------------------------------
+
+const FALLBACK_TABLES = [
+    'customer', 'supplier', 'warehouse', 'item-project',
+    'stock-inbound', 'stock-inbound-item'
+];
+
+/**
+ * Mengumpulkan nama tabel dari folder schema bila ada; bila tidak, memakai
+ * daftar fallback yang dipadkan sampai 30 entri agar contoh kanonik (30 tabel)
+ * tetap dapat dirender.
+ */
+function collectTables(schemaDir) {
+    let names = [];
+    let realSchema = false;
+
+    try {
+        if (schemaDir && fs.existsSync(schemaDir) && fs.statSync(schemaDir).isDirectory()) {
+            names = fs.readdirSync(schemaDir)
+                .filter((f) => f.endsWith('.js') && !f.startsWith('_') && !f.endsWith('.test.js'))
+                .map((f) => f.slice(0, -3))
+                .sort();
+            if (names.length > 0) realSchema = true;
+        }
+    } catch (_err) {
+        names = [];
+    }
+
+    if (!realSchema) {
+        names = FALLBACK_TABLES.slice();
+        let n = names.length + 1;
+        while (names.length < 30) {
+            names.push(`entity-${String(n).padStart(2, '0')}`);
+            n += 1;
+        }
+    }
+
+    return { names, realSchema };
+}
+
+// ---------------------------------------------------------------------------
+// Preflight: cek dependency restforge-designer (sebelum input konfigurasi)
+// ---------------------------------------------------------------------------
+
+function checkDesigner(args) {
+    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;
+    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) {
+        console.log(leader('  > restforge-designer', 'NOT FOUND', 32));
+        console.log('');
+        console.log(`  ${rule('=', 60)}`);
+        console.log('  ERROR: restforge-designer is required but not installed.');
+        console.log(`  ${rule('=', 60)}`);
+        console.log('  fast-track generates the frontend app using restforge-designer.');
+        console.log('  Download and install it from:');
+        console.log('');
+        console.log('    https://restforge.dev/download.html');
+        console.log('');
+        console.log('  Then re-run this command.');
+        console.log('');
+        throw stop('restforge-designer not installed');
+    }
+    console.log(leader('  > restforge-designer', `${version || 'installed'}  OK`, 32));
+}
+
+// ---------------------------------------------------------------------------
+// Fase input konfigurasi (LICENSE + database), mengikuti fast-track.mjs
+// ---------------------------------------------------------------------------
+
+async function collectConfig(args, ask) {
+    console.log('');
+    console.log(rule('='));
+    console.log('  RESTForge Fast-Track  —  Configuration');
+    console.log(rule('='));
+    console.log('');
+    console.log('  Enter configuration (press Enter to use the default value):');
+    console.log('');
+
+    const askField = async (label, def) => {
+        const input = (await ask(`  ${label} (${def}): `)).trim();
+        return input || def;
+    };
+
+    const cfg = {};
+
+    // LICENSE: bila --license diberikan, dipakai sebagai default prompt.
+    const licenseDefault = args.license || DEFAULTS.LICENSE;
+    cfg.LICENSE = await askField('LICENSE', licenseDefault);
+
+    // Alamat & port. Label user-facing REST_API_PORT, namun TETAP disimpan dan
+    // ditulis ke db-connection.env sebagai SERVER_PORT (key yang dikonsumsi
+    // `restforge serve`). WEB_SERVER_PORT adalah port frontend (`npx serve`),
+    // dialirkan via `payload migrate --port` — tidak masuk runtime config.
+    cfg.SERVER_ADDRESS = await askField('SERVER_ADDRESS', DEFAULTS.SERVER_ADDRESS);
+    cfg.SERVER_PORT = await askField('REST_API_PORT', DEFAULTS.SERVER_PORT);
+    cfg.WEB_SERVER_PORT = await askField('WEB_SERVER_PORT', DEFAULTS.WEB_SERVER_PORT);
+
+    // DB_TYPE menentukan atribut yang diminta berikutnya.
+    console.log('');
+    console.log('  Available DB_TYPE: postgresql, mysql, oracle, sqlite');
+    cfg.DB_TYPE = (await askField('DB_TYPE', DEFAULTS.DB_TYPE)).toLowerCase();
+
+    if (cfg.DB_TYPE === 'sqlite') {
+        console.log('');
+        console.log('  SQLite mode: DB_HOST, DB_PORT, DB_USER, DB_PASSWORD are ignored.');
+        console.log('  The database file path is set in DB_FILE.');
+        console.log('');
+        cfg.DB_FILE = await askField('DB_FILE (.db file path)', DEFAULTS.DB_FILE);
+        cfg.DB_NAME = cfg.DB_FILE;
+    } else {
+        const dbDef = DB_TYPE_DEFAULTS[cfg.DB_TYPE] || {};
+        cfg.DB_HOST = await askField('DB_HOST', DEFAULTS.DB_HOST);
+        cfg.DB_PORT = await askField('DB_PORT', dbDef.DB_PORT || DEFAULTS.DB_PORT);
+        cfg.DB_USER = await askField('DB_USER', dbDef.DB_USER || DEFAULTS.DB_USER);
+        cfg.DB_PASSWORD = await askField('DB_PASSWORD', DEFAULTS.DB_PASSWORD);
+        cfg.DB_NAME = await askField('DB_NAME', dbDef.DB_NAME || DEFAULTS.DB_NAME);
+    }
+
+    return cfg;
+}
+
+// ---------------------------------------------------------------------------
+// Fase pemilihan scope generate (menu)
+// ---------------------------------------------------------------------------
+
+async function selectScope(ask) {
+    console.log('');
+    console.log('  Select what to generate:');
+    console.log('');
+    console.log('    1. Generate REST API Only');
+    console.log('    2. Generate REST API with Frontend Application');
+    console.log('');
+
+    let scope = null;
+    while (!scope) {
+        const choice = (await ask(`  Choice (1-2) [${DEFAULT_SCOPE}]: `)).trim() || DEFAULT_SCOPE;
+        scope = SCOPES[choice];
+        if (!scope) console.log('  Invalid choice. Enter 1 or 2.');
+    }
+    return scope;
+}
+
+// ---------------------------------------------------------------------------
+// Fase preview + konfirmasi
+// ---------------------------------------------------------------------------
+
+async function confirmDefaultMode(ctx, ask) {
+    console.log('');
+    console.log(rule('='));
+    console.log('  RESTForge Fast-Track');
+    console.log(rule('='));
+    console.log('');
+    console.log(`  Project    : ${ctx.project}`);
+    console.log(`  Generate   : ${ctx.scope.label}`);
+    console.log(`  Schema     : ${ctx.schemaFlag}   (${ctx.tables.length} SDF files)`);
+    console.log(`  Config     : ${ctx.configFlag}   (will be written)`);
+    console.log(`  License    : ${maskLicense(ctx.cfg.LICENSE)}`);
+    console.log(`  REST API   : ${ctx.cfg.SERVER_ADDRESS}:${ctx.cfg.SERVER_PORT}   (SERVER_PORT)`);
+    console.log(`  Web server : ${ctx.cfg.SERVER_ADDRESS}:${ctx.cfg.WEB_SERVER_PORT}`);
+    console.log(`  Database   : ${describeDatabase(ctx.cfg)}`);
+    console.log('  Mode       : sync   (use --overwrite to drop & regenerate)');
+    console.log('');
+    const answer = (await ask('  Continue? (Y/n): ')).trim().toLowerCase();
+    console.log('');
+    if (answer === 'n' || answer === 'no') {
+        console.log('  Aborted. No changes were made.');
+        throw stop('user aborted');
+    }
+}
+
+async function confirmOverwriteMode(ctx, ask) {
+    console.log('');
+    console.log(rule('='));
+    console.log('  RESTForge Fast-Track  —  --overwrite MODE (DESTRUCTIVE)');
+    console.log(rule('='));
+    console.log('');
+    console.log(`  Project  : ${ctx.project}`);
+    console.log(`  Generate : ${ctx.scope.label}`);
+    console.log(`  License  : ${maskLicense(ctx.cfg.LICENSE)}`);
+    console.log(`  Database : ${describeDatabase(ctx.cfg)}`);
+    console.log('');
+    console.log('  The following actions will run:');
+    if (ctx.scope.backend) {
+        console.log(`    • DROP TABLE : ${ctx.tables.length} tables            (DATA WILL BE LOST)`);
+    }
+    const overwriteTargets = [
+        ctx.scope.backend && 'RDF, endpoint',
+        ctx.scope.frontend && 'frontend'
+    ].filter(Boolean).join(', ');
+    console.log(`    • Overwrite  : affected ${overwriteTargets} files`);
+    console.log('    • Archive    : old files backed up before overwrite');
+    console.log('                   (e.g. payload/visitors.json.archive.001)');
+    console.log('');
+    console.log('  This action cannot be undone.');
+    const answer = (await ask('  Continue? (y/N): ')).trim().toLowerCase();
+    console.log('');
+    if (answer !== 'y' && answer !== 'yes') {
+        console.log('  Aborted. No changes were made.');
+        throw stop('user aborted');
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Eksekusi nyata (REST API) — orkestrasi command restforge existing
+//
+// Daftar command mengikuti referensi yang sudah terbukti di
+// restforge-playbook/fast-track.mjs dan quick-start.mjs:
+//   init -> isi env -> validate -> config set-default -> schema migrate (folder)
+//   -> per tabel: payload generate + endpoint create -> (opsional) serve.
+// ---------------------------------------------------------------------------
+
+function phase(title) {
+    console.log('');
+    console.log(rule('='));
+    console.log(`  ${title}`);
+    console.log(rule('='));
+}
+
+/** Jalankan command CMD inline; hentikan pipeline bila gagal. */
+function run(cmd, cwd, { allowNonZero = false } = {}) {
+    console.log(`\n#${cmd}`);
+    const r = spawnSync('cmd', ['/S', '/C', cmd], { cwd, stdio: 'inherit' });
+    if (allowNonZero) {
+        if (r.error) console.log(`\n  [WARN] ${cmd}\n  ${r.error.message}`);
+        return r.status;
+    }
+    if (r.error) {
+        console.log(`\n  [FAILED] ${cmd}\n  ${r.error.message}`);
+        throw stop(`command failed to start: ${cmd}`);
+    }
+    if (r.status !== 0) {
+        console.log(`\n  [FAILED] exit code ${r.status}: ${cmd}`);
+        throw stop(`command exited with code ${r.status}`);
+    }
+    return r.status;
+}
+
+/** Perbarui VALUE sejumlah KEY pada file .env tanpa mengubah baris lain. */
+function updateEnvFile(filePath, values) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const eol = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content.split(/\r?\n/);
+    const remaining = new Set(Object.keys(values));
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^(\s*)([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (m && remaining.has(m[2])) {
+            lines[i] = `${m[1]}${m[2]}=${values[m[2]]}`;
+            remaining.delete(m[2]);
+        }
+    }
+    for (const k of remaining) lines.push(`${k}=${values[k]}`);
+    fs.writeFileSync(filePath, lines.join(eol));
+}
+
+/** Susun nilai env yang akan ditulis dari konfigurasi input. */
+function envValuesFromCfg(cfg) {
+    const v = {
+        LICENSE: cfg.LICENSE,
+        SERVER_ADDRESS: cfg.SERVER_ADDRESS,
+        SERVER_PORT: cfg.SERVER_PORT,
+        DB_TYPE: cfg.DB_TYPE
+    };
+    if (cfg.DB_TYPE === 'sqlite') {
+        v.DB_FILE = cfg.DB_FILE;
+        v.DB_NAME = cfg.DB_NAME;
+    } else {
+        v.DB_HOST = cfg.DB_HOST;
+        v.DB_PORT = cfg.DB_PORT;
+        v.DB_USER = cfg.DB_USER;
+        v.DB_PASSWORD = cfg.DB_PASSWORD;
+        v.DB_NAME = cfg.DB_NAME;
+    }
+    return v;
+}
+
+/** Pastikan config/<file> ada (init bila belum) lalu isi nilai dari input. */
+function ensureEnv(ctx) {
+    const configPath = path.join(ctx.cwd, 'config', ctx.configFlag);
+    if (!fs.existsSync(configPath)) {
+        run('npx restforge init --force', ctx.cwd);
+    }
+    if (!fs.existsSync(configPath)) {
+        throw stop(`config file not found after init: ${configPath}`);
+    }
+    updateEnvFile(configPath, envValuesFromCfg(ctx.cfg));
+    console.log(`  ~ config/${ctx.configFlag} written from input.`);
+}
+
+const AUDIT_COLS = new Set(['created_at', 'created_by', 'updated_at', 'updated_by']);
+
+/**
+ * Parse satu file SDF menjadi descriptor model. Deterministik dari SDF (tanpa DB):
+ *   { kebab, table, pk, fields[{name,isPk,isAudit,fk}], fks[{childCol,parentTable,parentCol}], displayCols }
+ * displayCols = kolom yang mengandung `code`/`name`, di luar PK & kolom audit
+ * (dipakai sebagai kolom display saat tabel ini menjadi parent FK).
+ */
+function parseModel(absFile, kebab) {
+    let content = '';
+    try { content = fs.readFileSync(absFile, 'utf8'); } catch (_err) { /* kosong */ }
+    const table = (content.match(/defineModel\(\s*['"]([^'"]+)['"]/) || [, kebab.replace(/-/g, '_')])[1];
+    const block = (content.match(/fields\s*:\s*\{([\s\S]*?)\}/) || [, ''])[1];
+
+    const fields = [];
+    const re = /(\w+)\s*:\s*'([^']*)'/g;
+    let m;
+    while ((m = re.exec(block)) !== null) {
+        const name = m[1];
+        const spec = m[2];
+        const fkMatch = spec.match(/fk:(\w+)\.(\w+)/);
+        fields.push({
+            name,
+            isPk: /\bpk\b/.test(spec),
+            isAudit: AUDIT_COLS.has(name),
+            fk: fkMatch ? { parentTable: fkMatch[1], parentCol: fkMatch[2] } : null
+        });
+    }
+    const pk = (fields.find((f) => f.isPk) || {}).name || null;
+    const displayCols = fields
+        .filter((f) => !f.isPk && !f.isAudit && /(code|name)/i.test(f.name))
+        .map((f) => f.name);
+    const fks = fields
+        .filter((f) => f.fk)
+        .map((f) => ({ childCol: f.name, parentTable: f.fk.parentTable, parentCol: f.fk.parentCol }));
+
+    return { kebab, table, pk, fields, fks, displayCols };
+}
+
+/** Bangun daftar model dari folder schema. */
+function buildTableEntries(schemaDir) {
+    const files = fs.readdirSync(schemaDir)
+        .filter((f) => f.endsWith('.js') && !f.startsWith('_') && !f.endsWith('.test.js'))
+        .sort();
+    return files.map((f) => parseModel(path.join(schemaDir, f), f.slice(0, -3)));
+}
+
+/**
+ * Turunkan daftar `--fk-columns` untuk `payload sync --expand-fk` dari SDF:
+ * `<parentTable>.<displayCol>` untuk tiap kolom display (code/name) tiap parent.
+ * Kosong bila tidak ada kolom display terdeteksi (jatuh ke mode AUTO command).
+ */
+function fkColumnsForEntry(entry, byTable) {
+    const cols = [];
+    for (const fk of entry.fks) {
+        const parent = byTable.get(fk.parentTable);
+        const disp = parent ? parent.displayCols : [];
+        for (const dc of disp) cols.push(`${fk.parentTable}.${dc}`);
+    }
+    return cols;
+}
+
+/** Jeda async sederhana. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Satu kali GET <url>; resolve true bila HTTP 200 dan (jika JSON) status:'ok'. */
+function pingOnce(url, perReqTimeoutMs) {
+    return new Promise((resolve) => {
+        const req = http.get(url, (res) => {
+            let body = '';
+            res.on('data', (c) => { body += c; });
+            res.on('end', () => {
+                let ok = res.statusCode === 200;
+                if (ok && body) {
+                    // Bila body JSON, pastikan status:'ok'. Bila bukan JSON, cukup andalkan 200.
+                    try { ok = JSON.parse(body).status === 'ok'; } catch { /* keep 200 */ }
+                }
+                resolve(ok);
+            });
+        });
+        req.setTimeout(perReqTimeoutMs, () => { req.destroy(); resolve(false); });
+        req.on('error', () => resolve(false));
+    });
+}
+
+/** Poll <url> sampai sehat atau timeout. Dipakai setelah serve di-spawn. */
+async function waitForHealth(url, { timeoutMs = 30000, intervalMs = 600 } = {}) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (await pingOnce(url, 2000)) return { ok: true, elapsedMs: Date.now() - start };
+        await sleep(intervalMs);
+    }
+    return { ok: false, elapsedMs: Date.now() - start };
+}
+
+/** Host untuk health URL: 0.0.0.0/kosong -> localhost (mirror banner runtime). */
+function healthHost(serverAddress) {
+    return (!serverAddress || serverAddress === '0.0.0.0') ? 'localhost' : serverAddress;
+}
+
+/** Bila port dipakai, hentikan proses lama (Windows) sebelum serve. */
+function freePort(port) {
+    const res = spawnSync('cmd', ['/S', '/C', `netstat -ano | findstr :${port}`], { encoding: 'utf8' });
+    const pids = new Set();
+    for (const line of (res.stdout || '').split(/\r?\n/)) {
+        const p = line.trim().split(/\s+/);
+        if (p.length >= 5 && /LISTENING/i.test(p[3]) && p[1].endsWith(`:${port}`)) {
+            if (/^\d+$/.test(p[4]) && p[4] !== '0') pids.add(p[4]);
+        }
+    }
+    if (pids.size === 0) return;
+    console.log(`  Port ${port} in use (PID ${[...pids].join(', ')}); stopping old process...`);
+    for (const pid of pids) spawnSync('cmd', ['/S', '/C', `taskkill /PID ${pid} /F`], { stdio: 'inherit' });
+}
+
+/** Pipeline REST API nyata: env -> validate -> migrate -> payload+endpoint. */
+function runBackendPipeline(ctx) {
+    const dbFlag = DB_FLAG[ctx.cfg.DB_TYPE] || ctx.cfg.DB_TYPE;
+    const cfgArg = `--config=${ctx.configFlag}`;
+
+    phase('[1/4] Config, license & database validation');
+    ensureEnv(ctx);
+    run(`npx restforge validate ${cfgArg} --auto-create-db`, ctx.cwd);
+    run(`npx restforge config set-default ${cfgArg}`, ctx.cwd);
+
+    phase('[2/4] Schema migrate (SDF -> database)');
+    // Mode --overwrite: drop tabel lalu re-create (destruktif). Tanpa --overwrite:
+    // CREATE TABLE IF NOT EXISTS (tabel existing dilewati).
+    const dropFlag = ctx.overwrite ? ' --drop=true' : '';
+    run(`npx restforge schema migrate --path=${ctx.schemaFlag} ${cfgArg} --auto-create-db${dropFlag}`, ctx.cwd);
+
+    phase('[3/4] Payload RDF (generate)');
+    for (const t of ctx.tableEntries) {
+        run(`npx restforge payload generate --table=${t.table} ${cfgArg}`, ctx.cwd);
+    }
+
+    phase('[3b/4] FK expansion (payload sync --expand-fk)');
+    const fkTables = ctx.tableEntries.filter((t) => t.fks.length > 0);
+    if (fkTables.length === 0) {
+        console.log('  No FK to expand (RDF stays flat).');
+    } else {
+        for (const t of fkTables) {
+            const cols = fkColumnsForEntry(t, ctx.byTable);
+            const colFlag = cols.length ? ` --fk-columns=${cols.join(',')}` : '';
+            run(`npx restforge payload sync --table=${t.table} --expand-fk${colFlag}`, ctx.cwd);
+        }
+        // Catatan: fieldNameLookup pada parent TIDAK disuntik. Frontend default
+        // memakai kolom `name` untuk display dropdown; fieldNameLookup hanya untuk
+        // custom display dan diserahkan ke user (atau command khusus).
+    }
+
+    phase('[4/4] REST endpoints');
+    for (const t of ctx.tableEntries) {
+        run(`npx restforge endpoint create --project=${ctx.project} --name=${t.kebab} --payload=${t.kebab}.json ${cfgArg} --database=${dbFlag} --force`, ctx.cwd);
+    }
+}
+
+/**
+ * Pipeline frontend nyata: migrate RDF->UDF per tabel (agregator di-akumulasi),
+ * lalu designer activate + generate. Urutan mengikuti fast-track.mjs/quick-start.
+ * appCode default = project, sehingga agregator = frontend/payload/<project>.json.
+ */
+function runFrontendPipeline(ctx) {
+    const cfgArg = `--config=${ctx.configFlag}`;
+    const frontendDir = path.join(ctx.cwd, 'frontend');
+    const appCode = ctx.project;
+
+    phase('[F1/3] Migrate RDF -> UDF (per tabel, agregator di-akumulasi)');
+    fs.mkdirSync(path.join(frontendDir, 'payload'), { recursive: true });
+    for (const t of ctx.tableEntries) {
+        // Lewati tabel yang murni FK-parent (tanpa FK sendiri): page-nya dibuat
+        // otomatis via JOIN auto-discovery dari child (lihat scenario-12).
+        const isPureParent = t.fks.length === 0 && ctx.parentTables.has(t.table);
+        if (isPureParent) {
+            console.log(`  (skip ${t.kebab}: auto-discovered via JOIN from child)`);
+            continue;
+        }
+        run(`npx restforge payload migrate --project=${ctx.project} --name=${t.kebab}.json --output=frontend/payload ${cfgArg} --port=${ctx.cfg.WEB_SERVER_PORT} --overwrite`, ctx.cwd);
+    }
+
+    phase('[F2/3] Activate restforge-designer');
+    run(`restforge-designer activate --key=${ctx.cfg.LICENSE}`, frontendDir, { allowNonZero: true });
+
+    phase('[F3/3] Generate frontend application');
+    // Hapus index.html lama agar landing page diregenerasi sesuai set page terbaru.
+    run(`if exist apps\\${ctx.project}\\index.html del /Q apps\\${ctx.project}\\index.html`, frontendDir, { allowNonZero: true });
+    run(`restforge-designer generate --payload=payload/${appCode}.json --output=./apps/${ctx.project} --overwrite`, frontendDir);
+}
+
+/**
+ * Tulis launcher start REST API mandiri di folder kerja (lokasi pemanggilan
+ * fast-track). Windows -> server-start.bat, Linux/macOS -> server-start.sh.
+ * Perintah serve sama dengan maybeRunServer (+ --watch), selaras dengan
+ * referensi backend-v4/server-start.bat. NODE_ENV sengaja tidak di-set: shell
+ * biasa membiarkan NODE_ENV kosong sehingga logger memakai pino-pretty (rapi).
+ */
+function writeServerStartScript(ctx) {
+    const serveCmd = `npx restforge serve --project=${ctx.project} --config=${ctx.configFlag} --watch`;
+    const isWin = process.platform === 'win32';
+    const file = path.join(ctx.cwd, isWin ? 'server-start.bat' : 'server-start.sh');
+    let content;
+    if (isWin) {
+        content = [
+            '@echo off',
+            'REM Start RESTForge REST API (runtime server). Generated by fast-track.',
+            'cd /d "%~dp0"',
+            `call ${serveCmd}`,
+            ''
+        ].join('\r\n');
+    } else {
+        content = [
+            '#!/usr/bin/env bash',
+            '# Start RESTForge REST API (runtime server). Generated by fast-track.',
+            'set -e',
+            'cd "$(dirname "$0")"',
+            serveCmd,
+            ''
+        ].join('\n');
+    }
+    fs.writeFileSync(file, content);
+    if (!isWin) {
+        try { fs.chmodSync(file, 0o755); } catch { /* abaikan bila FS tak dukung chmod */ }
+    }
+    return file;
+}
+
+function printFinalSummary(ctx) {
+    const parts = [];
+    if (ctx.scope.backend) parts.push('REST API generated');
+    if (ctx.scope.frontend) parts.push('frontend app generated');
+    console.log('');
+    console.log(rule('='));
+    console.log(`  DONE  —  ${parts.join(' + ')}   [scope: ${ctx.scope.label}]`);
+    console.log(rule('='));
+    if (ctx.scope.backend) {
+        console.log(`  Backend  : payload/ , examples/${ctx.project}/  (${ctx.tableEntries.length} endpoint)`);
+        if (ctx.serverStartFile) {
+            console.log(`  Start    : ${path.basename(ctx.serverStartFile)}  (start REST API manually)`);
+        }
+    }
+    if (ctx.scope.frontend) {
+        console.log(`  Frontend : frontend/apps/${ctx.project}/  (start: npx serve . -l ${ctx.cfg.WEB_SERVER_PORT})`);
+    }
+    console.log(rule('='));
+}
+
+/** Konfirmasi lalu jalankan runtime server di window CMD baru. */
+async function maybeRunServer(ctx, ask) {
+    // Samakan dengan pola server-start.bat: serve + --watch (auto-restart pada
+    // perubahan src/). Format log rapi (pino-pretty) berasal dari NODE_ENV
+    // development yang di-set saat spawn di bawah.
+    const serveCmd = `npx restforge serve --project=${ctx.project} --config=${ctx.configFlag} --watch`;
+    console.log('');
+    const answer = (await ask('  Run Runtime Server now in a new window? (Y/n): ')).trim().toLowerCase();
+    if (answer === 'n' || answer === 'no') {
+        console.log(`  Skipped. Start later:  ${serveCmd}`);
+        return;
+    }
+    freePort(ctx.cfg.SERVER_PORT);
+    const title = `RESTForge Server - ${ctx.project}`;
+    console.log(`\n  Opening new window: "${title}"`);
+    console.log(`#${serveCmd}`);
+    // server.js (dispatcher) memaksa NODE_ENV=production untuk proses cli command,
+    // sehingga fast-track berjalan production dan secara default akan mewariskannya
+    // ke serve -> logger memakai format JSON mentah (verbose). Set development agar
+    // runtime server memakai pino-pretty (rapi), konsisten dengan playbook yang
+    // menjalankan serve dari plain `node`.
+    const serveEnv = { ...process.env, NODE_ENV: 'development' };
+    const r = spawnSync('cmd', ['/C', 'start', title, 'cmd', '/k', serveCmd], { cwd: ctx.cwd, stdio: 'inherit', env: serveEnv });
+    if (r.error) {
+        console.log(`  Failed to open server window: ${r.error.message}`);
+        return;
+    }
+    console.log('  ✓ Server window opened. Keep it open. Stop with Ctrl+C.');
+
+    // Health check: tunggu runtime benar-benar siap menerima request sebelum
+    // lanjut (mis. ke frontend). URL = banner runtime: /api/<project>/health.
+    const host = healthHost(ctx.cfg.SERVER_ADDRESS);
+    const healthUrl = `http://${host}:${ctx.cfg.SERVER_PORT}/api/${ctx.project}/health`;
+    console.log(`\n  Waiting for server health: ${healthUrl}`);
+    const h = await waitForHealth(healthUrl, { timeoutMs: 30000, intervalMs: 600 });
+    if (h.ok) {
+        console.log(`  ✓ Server healthy (${(h.elapsedMs / 1000).toFixed(1)}s).`);
+    } else {
+        console.log(`  ⚠ Health check timed out after ${(h.elapsedMs / 1000).toFixed(0)}s.`);
+        console.log('    Server may still be starting; check the server window for errors.');
+    }
+}
+
+/** Konfirmasi lalu jalankan aplikasi frontend (app-start.bat) di window CMD baru. */
+async function maybeRunFrontend(ctx, ask) {
+    const appDir = path.join(ctx.cwd, 'frontend', 'apps', ctx.project);
+    const webPort = ctx.cfg.WEB_SERVER_PORT;
+    // Jalankan langsung `npx serve . -l <port>` (identik untuk Windows & Linux),
+    // tidak bergantung pada app-start.bat/.sh. File launcher itu urusan generator.
+    const serveCmd = `npx serve . -l ${webPort}`;
+    console.log('');
+    const answer = (await ask('  Run Frontend Application now in a new window? (Y/n): ')).trim().toLowerCase();
+    if (answer === 'n' || answer === 'no') {
+        console.log(`  Skipped. Start later (in ${appDir}):  ${serveCmd}`);
+        return;
+    }
+    const indexHtml = path.join(appDir, 'index.html');
+    if (!fs.existsSync(indexHtml)) {
+        console.log(`  Frontend app not found: ${indexHtml}`);
+        console.log('  Frontend generation may have failed; cannot launch.');
+        return;
+    }
+    freePort(webPort);
+    const title = `RESTForge Frontend - ${ctx.project}`;
+    console.log(`\n  Opening new window: "${title}"`);
+    console.log(`#${serveCmd}`);
+    const r = spawnSync('cmd', ['/C', 'start', title, 'cmd', '/k', serveCmd], { cwd: appDir, stdio: 'inherit' });
+    if (r.error) {
+        console.log(`  Failed to open frontend window: ${r.error.message}`);
+    } else {
+        console.log(`  ✓ Frontend window opened (WEB_SERVER_PORT ${webPort}).`);
+        console.log(`    Open: http://localhost:${webPort}/index.html`);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Contract
+// ---------------------------------------------------------------------------
+
+module.exports = {
+    verb: 'fast-track',
+    description: 'Generate REST API + frontend app dari SDF (eksekusi nyata) + opsi runtime server',
+    category: 'generation',
+    flags: {
+        project: {
+            type: 'string',
+            required: true,
+            description: 'Nama project/aplikasi (mis. visitors-app)'
+        },
+        schema: {
+            type: 'string',
+            required: true,
+            description: 'Folder berisi SDF aplikasi (relatif cwd)'
+        },
+        config: {
+            type: 'string',
+            required: false,
+            default: DEFAULT_CONFIG_FILE,
+            description: 'Nama file env target di folder config/ (ditulis dari input; default db-connection.env)'
+        },
+        license: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'License key (XXXX-XXXX-XXXX-XXXX). Bila diisi dipakai sebagai default prompt LICENSE'
+        },
+        overwrite: {
+            type: 'boolean',
+            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'
+    ],
+    async handler(args) {
+        const cwd = process.cwd();
+        const schemaDir = path.resolve(cwd, args.schema);
+        const { names: tables } = collectTables(schemaDir);
+
+        const prompter = createPrompter();
+        try {
+            // 1) Input konfigurasi (LICENSE + database), gaya fast-track.mjs.
+            const cfg = await collectConfig(args, prompter.ask);
+
+            // 2) Menu pemilihan scope generate (REST API / frontend / all).
+            const scope = await selectScope(prompter.ask);
+
+            // 3) Preflight designer hanya bila scope mencakup frontend.
+            if (scope.frontend) {
+                checkDesigner(args);
+            }
+
+            const ctx = {
+                cwd,
+                project: args.project,
+                schemaFlag: args.schema,
+                configFlag: args.config,
+                tables,
+                cfg,
+                scope,
+                overwrite: args.overwrite === true
+            };
+
+            // Backend dan frontend sama-sama butuh daftar tabel dari folder SDF
+            // (frontend memetakan tiap tabel ke page UDF via payload-nya).
+            if (scope.backend || scope.frontend) {
+                if (!fs.existsSync(schemaDir) || !fs.statSync(schemaDir).isDirectory()) {
+                    console.log(`\n  ERROR: schema folder not found: ${schemaDir}`);
+                    throw stop('schema folder not found');
+                }
+                ctx.tableEntries = buildTableEntries(schemaDir);
+                if (ctx.tableEntries.length === 0) {
+                    console.log(`\n  ERROR: no SDF (.js) files in: ${schemaDir}`);
+                    throw stop('no SDF files');
+                }
+                // Relasi FK lintas-tabel: peta tabel + himpunan tabel parent.
+                ctx.byTable = new Map(ctx.tableEntries.map((e) => [e.table, e]));
+                ctx.parentTables = new Set();
+                for (const e of ctx.tableEntries) {
+                    for (const fk of e.fks) ctx.parentTables.add(fk.parentTable);
+                }
+            }
+
+            // 4) Preview + konfirmasi (sesuai mode).
+            if (ctx.overwrite) {
+                await confirmOverwriteMode(ctx, prompter.ask);
+            } else {
+                await confirmDefaultMode(ctx, prompter.ask);
+            }
+
+            // 5) Eksekusi sesuai scope.
+            if (ctx.scope.backend) {
+                runBackendPipeline(ctx);
+                // Launcher start REST API mandiri (sesuai OS), di folder kerja.
+                ctx.serverStartFile = writeServerStartScript(ctx);
+            }
+            if (ctx.scope.frontend) {
+                runFrontendPipeline(ctx);
+            }
+
+            printFinalSummary(ctx);
+
+            // 6) Tawarkan menjalankan service: runtime server (backend) lalu
+            //    aplikasi frontend, masing-masing di window CMD baru.
+            if (ctx.scope.backend) {
+                await maybeRunServer(ctx, prompter.ask);
+            }
+            if (ctx.scope.frontend) {
+                await maybeRunFrontend(ctx, prompter.ask);
+            }
+        } finally {
+            prompter.close();
+        }
+    }
+};
+
+// Test seam (hanya aktif via env): mengekspos helper internal agar dapat diuji
+// terpisah tanpa menjalankan pipeline penuh. Pada penggunaan CLI normal env ini
+// tidak di-set sehingga export tetap berupa contract murni.
+if (process.env.FASTTRACK_TEST === '1') {
+    module.exports.__test = { parseModel, buildTableEntries, fkColumnsForEntry };
+}