mongofire 6.5.3 → 6.5.6

package/bin/mongofire.cjs

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 'use strict';
 
-// ─── Global error handlers (Windows popup fix) ────────────────────────────────
-// Windows pe unhandled error -> native crash popup. Ye handlers ensure karte hain
-// ki har error console me aaye, popup nahi.
+// Tell the MongoFire core module not to auto-start from mongofire.config.js.
+// Without this flag, requiring the core module would fire autoStart() in the
+// background, which conflicts with the CLI's own controlled start() calls.
+process.env.MONGOFIRE_CLI = '1';
+
 process.on('uncaughtException', (err) => {
-  console.error('\n❌ MongoFire CLI Error:', err.message || err);
+  console.error('\n✖ MongoFire error:', err.message || err);
   if (process.env.MONGOFIRE_DEBUG) console.error(err.stack);
   process.exit(1);
 });
 process.on('unhandledRejection', (reason) => {
-  console.error('\n❌ MongoFire CLI Error:', reason?.message || reason);
+  console.error('\n✖ MongoFire error:', reason?.message || reason);
   if (process.env.MONGOFIRE_DEBUG) console.error(reason?.stack || reason);
   process.exit(1);
 });
@@ -24,791 +26,1122 @@ const command = args[0];
 const flags   = new Set(args.slice(1));
 
 if (flags.has('--esm') && flags.has('--cjs')) {
-  console.error('❌ Use only one: --esm OR --cjs');
+  console.error('✖  Use only one: --esm OR --cjs');
   process.exit(1);
 }
 
-// ─── Load .env early ─────────────────────────────────────────────────────────
-// .env load karo BEFORE config import — warna process.env.ATLAS_URI etc. empty
-// milte hain jab config file evaluate hoti hai. CJS config template bhi apna
-// dotenv.config() call karta hai, lekin CLI se load karna double-safety hai
-// aur ESM configs ke liye zaroori hai jo import hone pe env read karte hain.
+// Load .env early
 (function _loadDotenv() {
-  const envPath = path.join(process.cwd(), '.env');
-  if (!fs.existsSync(envPath)) return;
-  try {
-    require('dotenv').config({ path: envPath });
-  } catch (_) {
-    // dotenv not installed — env vars must be set manually in the shell
-  }
+  const p = path.join(process.cwd(), '.env');
+  if (!fs.existsSync(p)) return;
+  try { require('dotenv').config({ path: p }); } catch (_) {}
 })();
 
-// ─── TTY Detection (Windows fix) ─────────────────────────────────────────────
-// Windows PowerShell/CMD me process.stdin.isTTY undefined hota hai.
-// Agar TTY nahi hai to interactive prompts crash karte hain -> Windows popup.
-// Solution: non-TTY environment me automatically non-interactive mode use karo.
 const IS_TTY = !!process.stdin.isTTY;
 
-// ─── Route commands ───────────────────────────────────────────────────────────
-if (command === 'init') {
-  const hasFlags = flags.has('--esm') || flags.has('--cjs') || flags.has('--force') || flags.has('-f');
-
-  if (!hasFlags && IS_TTY) {
-    // Full interactive mode - sirf real TTY pe
-    doInitInteractive().catch((err) => {
-      console.error('❌ Error:', err.message);
-      process.exit(1);
-    });
-  } else if (!hasFlags && !IS_TTY) {
-    // Non-TTY (Windows piped/scripted) - direct mode with auto-detect
-    console.log('ℹ️  Non-interactive mode (no TTY detected)');
-    console.log('    Use flags for full control: --cjs or --esm, --force\n');
-    doInit({ force: false, moduleSystem: null });
+// ─── Router ───────────────────────────────────────────────────────────────────
+(async () => {
+  if (command === 'init') {
+    const hasFlags = flags.has('--esm') || flags.has('--cjs') || flags.has('--force') || flags.has('-f');
+    if (!hasFlags && IS_TTY) {
+      await doInitWizard();
+    } else {
+      if (!hasFlags) process.stdout.write('ℹ  Non-interactive mode — use --cjs, --esm, --force for control\n\n');
+      doInitDirect({ force: flags.has('--force') || flags.has('-f'), moduleSystem: flags.has('--esm') ? 'esm' : flags.has('--cjs') ? 'cjs' : null, flagForced: flags.has('--esm') || flags.has('--cjs') });
+    }
+  } else if (command === 'config') {
+    if (IS_TTY) await doConfigWizard();
+    else { console.log('ℹ  config requires an interactive terminal.'); process.exit(0); }
+  } else if (command === 'status') {
+    await doStatus();
+  } else if (command === 'clean') {
+    const hasDaysFlag = [...flags].some((f) => f.startsWith('--days='));
+    if (!hasDaysFlag && IS_TTY) await doCleanWizard();
+    else await doClean();
+  } else if (command === 'conflicts') {
+    if (IS_TTY) await doConflictsWizard();
+    else { console.log('ℹ  conflicts requires an interactive terminal.'); process.exit(0); }
+  } else if (command === 'reconcile') {
+    const noFullScan  = flags.has('--no-full-scan');
+    const colArg      = [...flags].find((f) => f.startsWith('--collection='));
+    const singleCol   = colArg ? colArg.split('=')[1] : null;
+    await doReconcile({ fullScan: !noFullScan, collection: singleCol });
+  } else if (command === 'compact') {
+    await doCompact();
+  } else if (command === 'reset-local') {
+    if (IS_TTY) await doResetLocal();
+    else {
+      console.log('ℹ  reset-local requires an interactive terminal (safety guard).');
+      process.exit(0);
+    }
   } else {
-    doInit({
-      force:       flags.has('--force') || flags.has('-f'),
-      moduleSystem: flags.has('--esm') ? 'esm' : flags.has('--cjs') ? 'cjs' : null,
-      flagForced:  flags.has('--esm') || flags.has('--cjs'),
-    });
+    showHelp();
   }
+})().catch((err) => {
+  console.error('\n✖ MongoFire error:', err.message || err);
+  if (process.env.MONGOFIRE_DEBUG) console.error(err.stack);
+  process.exit(1);
+});
 
-} else if (command === 'status') {
-  doStatus().catch((err) => {
-    console.error('❌ Error:', err.message);
-    process.exit(1);
-  });
-
-} else if (command === 'clean') {
-  const hasDaysFlag = [...flags].some((f) => f.startsWith('--days='));
-  if (!hasDaysFlag && IS_TTY) {
-    doCleanInteractive().catch((err) => {
-      console.error('❌ Error:', err.message);
-      process.exit(1);
-    });
-  } else {
-    doClean().catch((err) => {
-      console.error('❌ Error:', err.message);
-      process.exit(1);
-    });
-  }
+// ─── Help ─────────────────────────────────────────────────────────────────────
+function showHelp() {
+  const v = _getVersion();
+  console.log(`
+  \x1b[33m🔥 MongoFire\x1b[0m  \x1b[2mv${v}\x1b[0m
 
-} else if (command === 'conflicts') {
-  if (IS_TTY) {
-    doConflictsInteractive().catch((err) => {
-      console.error('❌ Error:', err.message);
-      process.exit(1);
-    });
-  } else {
-    console.log('ℹ️  conflicts command requires an interactive terminal (TTY).');
-    console.log('    Run directly in PowerShell or CMD window.\n');
-    process.exit(0);
-  }
+  \x1b[1mUsage\x1b[0m
 
-} else if (command === 'reconcile') {
-  doReconcile().catch((err) => {
-    console.error('❌ Error:', err.message);
-    process.exit(1);
-  });
+    \x1b[36mnpx mongofire\x1b[0m \x1b[2m<command> [flags]\x1b[0m
 
-} else {
-  showHelp();
-}
+  \x1b[1mCommands\x1b[0m
 
-// ─── Help ─────────────────────────────────────────────────────────────────────
+    \x1b[36minit\x1b[0m          Interactive setup wizard
+    \x1b[36mconfig\x1b[0m        Update an existing configuration  \x1b[2m(TTY only)\x1b[0m
+    \x1b[36mstatus\x1b[0m        Show pending sync counts
+    \x1b[36mclean\x1b[0m         Delete old sync records
+    \x1b[36mconflicts\x1b[0m     View and resolve conflicts  \x1b[2m(TTY only)\x1b[0m
+    \x1b[36mreconcile\x1b[0m     Recover writes lost from crashes
+    \x1b[36mcompact\x1b[0m       Compact the sync changelog (60\u201380% size reduction)
+    \x1b[36mreset-local\x1b[0m   Safely wipe local DB + all MongoFire state  \x1b[2m(TTY only)\x1b[0m
 
-function showHelp() {
-  console.log(`
-\uD83D\uDD25 MongoFire CLI v${_getVersion()}
+  \x1b[1mFlags for \x1b[36minit\x1b[0m
 
-  npx mongofire init [--force] [--esm|--cjs]
-      Setup wizard (interactive if terminal supports it)
-      --esm    Force ESM templates
-      --cjs    Force CommonJS templates  
-      --force  Overwrite existing config files
+    \x1b[2m--esm\x1b[0m         Force ESM module format
+    \x1b[2m--cjs\x1b[0m         Force CommonJS module format
+    \x1b[2m--force, -f\x1b[0m   Overwrite existing config files
 
-  npx mongofire status
-      Show pending sync operation counts
+  \x1b[1mFlags for \x1b[36mclean\x1b[0m
 
-  npx mongofire clean [--days=N]
-      Delete old synced records (default: 7 days)
-      Example: npx mongofire clean --days=3
+    \x1b[2m--days=N\x1b[0m      Delete records older than N days (1–3650, default 7)
 
-  npx mongofire conflicts
-      View, retry, or dismiss unresolved conflicts
+  \x1b[1mFlags for \x1b[36mreconcile\x1b[0m
 
-  npx mongofire reconcile
-      Recover writes lost from crashes
+    \x1b[2m--no-full-scan\x1b[0m  Skip Phase 2 (only check orphaned docmeta)
+    \x1b[2m--collection=NAME\x1b[0m  Scan a single collection instead of all
 
-  Tip: Run with MONGOFIRE_DEBUG=1 for full error stack traces
+  \x1b[2mTip: set MONGOFIRE_DEBUG=1 for full error stack traces\x1b[0m
 `);
 }
 
 function _getVersion() {
-  try {
-    return require(path.join(__dirname, '..', 'package.json')).version;
-  } catch { return '?'; }
+  try { return require(path.join(__dirname, '..', 'package.json')).version; } catch { return '?'; }
 }
 
-// ─── Inquirer / prompt helper ─────────────────────────────────────────────────
-// Inquirer.js use karo agar installed hai.
-// Fallback: apna readline-based prompter jo Windows pe bhi kaam karta hai.
-
-async function _prompt(questions) {
-  // Try inquirer first
+// ─── Load clack ───────────────────────────────────────────────────────────────
+async function loadClack() {
   try {
-    const inquirer = require('inquirer');
-    // Test ke liye: inquirer v8 prompt function exist karta hai
-    if (typeof inquirer.prompt === 'function') {
-      return await inquirer.prompt(questions);
-    }
-  } catch (_) {
-    // inquirer not installed — use readline fallback
+    return await import('@clack/prompts');
+  } catch {
+    return buildFallbackClack();
   }
-
-  return _readlinePrompt(questions);
 }
 
-async function _readlinePrompt(questions) {
-  // Windows-safe readline wrapper
-  // Key fixes:
-  // 1. process.stdin.resume() call before creating interface
-  // 2. 'close' event handler to resolve hanging promises
-  // 3. Error handler on readline interface
-
-  process.stdin.resume();                                    // Windows fix: stdin resume karo
-
-  const readline = require('readline');
-  const rl = readline.createInterface({
-    input:  process.stdin,
-    output: process.stdout,
-    terminal: IS_TTY,                                        // Windows fix: explicit terminal flag
-  });
-
-  rl.on('error', () => {});                                  // Windows fix: suppress readline errors
-
-  const answers = {};
-
-  try {
-    for (const q of questions) {
-      answers[q.name] = await _askOne(rl, q, answers);
-    }
-  } finally {
-    rl.close();
-    process.stdin.pause();                                   // Windows fix: stdin pause after done
-  }
-
-  return answers;
-}
-
-function _askOne(rl, q, prevAnswers) {
-  return new Promise((resolve) => {
-
-    // 'close' event = stdin closed unexpectedly (Windows pipe issue)
-    // Use default value instead of hanging
-    const onClose = () => resolve(q.default ?? '');
-    rl.once('close', onClose);
-
-    const done = (val) => {
-      rl.removeListener('close', onClose);
-      resolve(val);
-    };
-
-    if (q.type === 'list') {
-      const choices = q.choices || [];
-      const lines   = choices
-        .map((c, i) => `  ${i + 1}. ${typeof c === 'object' ? c.name : c}`)
-        .join('\n');
-      const defIdx  = typeof q.default === 'number' ? q.default : 0;
-
-      const msg = q.message + (typeof q.message === 'function' ? q.message(prevAnswers) : '');
-      rl.question(`\n${msg}\n${lines}\nEnter number [${defIdx + 1}]: `, (ans) => {
-        const trimmed = ans.trim();
-        const idx     = trimmed ? Math.max(0, parseInt(trimmed, 10) - 1) : defIdx;
-        const choice  = choices[idx] ?? choices[defIdx] ?? choices[0];
-        done(typeof choice === 'object' ? choice.value : choice);
-      });
-
-    } else if (q.type === 'confirm') {
-      const defVal  = q.default !== false;
-      const hint    = defVal ? 'Y/n' : 'y/N';
-      const msgText = typeof q.message === 'function' ? q.message(prevAnswers) : q.message;
-      rl.question(`\n${msgText} (${hint}): `, (ans) => {
-        const trimmed = ans.trim().toLowerCase();
-        done(trimmed === '' ? defVal : trimmed === 'y' || trimmed === 'yes');
-      });
-
+// ─── Init Wizard ──────────────────────────────────────────────────────────────
+const DEFAULT_COLLECTIONS = 'orders, products, users';
+
+// ─── Modern info block ────────────────────────────────────────────────────────
+function _info(title, lines, tip) {
+  const W   = 58;
+  const pad = (s) => s.length > W ? s.slice(0, W - 1) + '...' : s;
+  process.stdout.write('|\n');
+  process.stdout.write('|  +- ' + title + '\n');
+  for (const line of lines) {
+    if (line === '') {
+      process.stdout.write('|  |\n');
+    } else if (line.startsWith('✓')) {
+      process.stdout.write('|  |  ' + pad(line) + '\n');
+    } else if (line.startsWith('✕')) {
+      process.stdout.write('|  |  ' + pad(line) + '\n');
+    } else if (line.startsWith('→')) {
+      process.stdout.write('|  |  ' + pad(line) + '\n');
     } else {
-      const msgText = typeof q.message === 'function' ? q.message(prevAnswers) : q.message;
-      const defHint = q.default != null ? ` (${q.default})` : '';
-      rl.question(`\n${msgText}${defHint}: `, (ans) => {
-        done(ans.trim() || q.default || '');
-      });
+      process.stdout.write('|  |  ' + pad(line) + '\n');
     }
-  });
+  }
+  if (tip) {
+    process.stdout.write('|  +- 💡 ' + pad(tip) + '\n');
+  } else {
+    process.stdout.write('|  +-\n');
+  }
 }
 
-// ─── Interactive Init ─────────────────────────────────────────────────────────
-
-async function doInitInteractive() {
-  const cwd    = process.cwd();
-  const exists = fs.existsSync(path.join(cwd, 'mongofire.config.js'));
-
-  console.log('\n\uD83D\uDD25 MongoFire Setup Wizard\n');
-
-  const answers = await _prompt([
-    {
-      type:    'list',
-      name:    'moduleSystem',
-      message: 'Which module system does your project use?',
-      choices: [
-        { name: 'CommonJS  (require / module.exports)', value: 'cjs' },
-        { name: 'ESM       (import / export)',           value: 'esm' },
-        { name: 'Auto-detect from package.json',         value: 'auto' },
+async function doInitWizard() {
+  const p   = await loadClack();
+  const cwd = process.cwd();
+
+  p.intro(` 🔥 MongoFire  v${_getVersion()} `);
+
+  // ── Existing config check (Vite-style) ───────────────────────────────────────
+  const cfgPath    = path.join(cwd, 'mongofire.config.js');
+  const entryPath  = path.join(cwd, 'mongofire.js');
+  const cfgExists  = fs.existsSync(cfgPath);
+  const entryExists = fs.existsSync(entryPath);
+
+  if (cfgExists) {
+    const existingFiles = [
+      cfgExists   && 'mongofire.config.js',
+      entryExists && 'mongofire.js',
+    ].filter(Boolean).join(', ');
+
+    p.note(
+      `${existingFiles} — already exists in this directory`,
+      'Existing setup found'
+    );
+
+    const action = await p.select({
+      message: 'What would you like to do?',
+      options: [
+        { value: 'overwrite', label: 'Overwrite',     hint: 'replace with fresh config — start from scratch' },
+        { value: 'config',    label: 'Update config', hint: 'change collections, interval, or toggle options' },
+        { value: 'cancel',    label: 'Cancel',        hint: 'keep existing files unchanged' },
       ],
-      default: 0,
-    },
-    {
-      type:    'confirm',
-      name:    'force',
-      message: exists
-        ? 'mongofire.config.js already exists. Overwrite it?'
-        : 'Create mongofire.config.js and mongofire.js?',
-      default: !exists,
-    },
-    {
-      type:    'confirm',
-      name:    'realtime',
-      message: 'Enable real-time sync? (Requires Atlas or replica set)',
-      default: false,
-    },
-    {
-      type:    'input',
-      name:    'collections',
-      message: 'Collections to sync (comma-separated)',
-      default: 'users,products',
-    },
-    {
-      type:    'list',
-      name:    'syncInterval',
-      message: 'Polling interval',
-      choices: [
-        { name: '5s   (dev / aggressive)',         value: 5000 },
-        { name: '15s  (balanced)',                  value: 15000 },
-        { name: '30s  (default)',                   value: 30000 },
-        { name: '60s  (conservative)',              value: 60000 },
-      ],
-      default: 2,
-    },
-  ]);
-
-  if (!answers.force) {
-    console.log('\nSetup cancelled — no files changed.\n');
-    process.exit(0);
+      initialValue: 'overwrite',
+    });
+    if (p.isCancel(action) || action === 'cancel') {
+      p.cancel('Cancelled — existing files kept.');
+      return;
+    }
+    if (action === 'config') {
+      p.outro('Opening config wizard...');
+      return doConfigWizard();
+    }
+    // action === 'overwrite' — fall through to full wizard below
   }
 
-  const wasAutoDetected = answers.moduleSystem === 'auto';
-  const moduleSystem = wasAutoDetected
-    ? detectModuleSystem(cwd, null)
-    : answers.moduleSystem;
-
-  const collections = String(answers.collections || 'users,products')
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean);
-
-  doInit({
-    force:         true,
-    moduleSystem,
-    autoDetected:  wasAutoDetected,
-    collections,
-    realtime:     !!answers.realtime,
-    syncInterval: Number(answers.syncInterval) || 30000,
+  // ── Step 1: Module system ────────────────────────────────────────────────────
+  _info('Module System', [
+    'How your project loads and shares code between files.',
+    '',
+    '→ Auto-detect  reads package.json + scans your source files',
+    '→ CommonJS     you write  require() / module.exports',
+    '→ ESM          you write  import / export',
+  ], 'Not sure? Pick Auto-detect — correct for most projects.');
+  const moduleSystem = await p.select({
+    message: 'Module system',
+    options: [
+      { value: 'auto', label: 'Auto-detect', hint: 'recommended — reads your project automatically' },
+      { value: 'cjs',  label: 'CommonJS',    hint: 'require() / module.exports' },
+      { value: 'esm',  label: 'ESM',         hint: 'import / export' },
+    ],
+    initialValue: 'auto',
   });
-}
-
-// ─── Init ─────────────────────────────────────────────────────────────────────
-
-function doInit(options) {
-  const cwd          = process.cwd();
-  const moduleSystem = detectModuleSystem(cwd, options.moduleSystem);
-  // moduleSource:
-  //   'auto-detected' — user picked "Auto-detect" in wizard, OR no flag passed
-  //   'forced'        — user explicitly passed --esm / --cjs flag
-  //   'auto-detected (from package.json)' — auto picked esm/cjs from pkg.type
-  const moduleSource = options.autoDetected
-    ? `auto-detected (${moduleSystem} from package.json)`
-    : options.flagForced
-      ? `forced (--${moduleSystem})`
-      : 'auto-detected';
-
-  const envResult    = ensureEnvFile(path.join(cwd, '.env'));
-  const configResult = writeFileIfNeeded(
-    path.join(cwd, 'mongofire.config.js'),
-    buildConfigTemplate(moduleSystem, options),
-    !!options.force
-  );
-  const entryResult = writeFileIfNeeded(
-    path.join(cwd, 'mongofire.js'),
-    buildEntryTemplate(moduleSystem),
-    !!options.force
-  );
-  const hints = collectPackageHints(cwd);
-
-  printInitSummary({ moduleSystem, moduleSource, force: !!options.force, envResult, configResult, entryResult, hints });
-}
-
-function detectModuleSystem(cwd, manualOverride) {
-  if (manualOverride && manualOverride !== 'auto') return manualOverride;
-
-  const pkg = readPackageJson(cwd);
-  if (pkg?.type === 'module')   return 'esm';
-  if (pkg?.type === 'commonjs') return 'cjs';
+  if (p.isCancel(moduleSystem)) return _cancelled(p);
 
-  const probes = [
-    'index.js', 'app.js', 'server.js', 'main.js',
-    path.join('src', 'index.js'),
-    path.join('src', 'main.js'),
-  ];
-  for (const rel of probes) {
-    const full = path.join(cwd, rel);
-    if (!fs.existsSync(full)) continue;
-    const code = fs.readFileSync(full, 'utf8');
-    if (/\bimport\s.+from\s+['"]/.test(code) || /\bexport\s+default\b/.test(code)) return 'esm';
-    if (/\brequire\(/.test(code) || /\bmodule\.exports\b/.test(code)) return 'cjs';
-  }
-  return 'cjs';
-}
-
-// ─── Template builders ────────────────────────────────────────────────────────
+  // ── Step 2: Real-time sync ───────────────────────────────────────────────────
+  _info('Real-Time Sync', [
+    'Controls how fast changes appear across all connected devices.',
+    '',
+    '✓ Enabled   Atlas Change Streams — changes push within milliseconds',
+    '✕ Disabled  Polling only — devices check every syncInterval',
+    '',
+    'If Change Streams are unavailable, falls back to polling silently.',
+  ], 'Recommended ON for most apps.');
+  const enableRealtime = await p.confirm({
+    message: 'Enable real-time sync?',
+    hint: 'ON = instant push   OFF = polling only',
+    initialValue: true,
+  });
+  if (p.isCancel(enableRealtime)) return _cancelled(p);
 
-function buildConfigTemplate(moduleSystem, opts) {
-  const cols = (opts && opts.collections && opts.collections.length)
-    ? opts.collections.map((c) => `    '${c}',`).join('\n')
-    : `    'users',\n    'products',`;
-  const realtime    = !!(opts && opts.realtime);
-  const syncInterval = (opts && opts.syncInterval) || 30000;
+  // ── Step 3: Multi-tenant ─────────────────────────────────────────────────────
+  _info('Multi-Tenant Mode', [
+    'Controls whether each user syncs only their own private data.',
+    '',
+    '✕ OFF  Cafe system, team app, single business',
+    '       All users share the same data — simple and fast',
+    '',
+    '✓ ON   SaaS platform, per-user notes, multi-business app',
+    '       Each user sees only their own documents',
+  ], 'Keep OFF unless users must have isolated private data.');
+  const enableMultitenant = await p.confirm({
+    message: 'Enable multi-tenant mode?',
+    hint: 'OFF = shared data (default)   ON = per-user isolation',
+    initialValue: false,
+  });
+  if (p.isCancel(enableMultitenant)) return _cancelled(p);
 
-  if (moduleSystem === 'esm') {
-    return [
-      '/**',
-      ' * MongoFire Config (ESM)',
-      ' *',
-      ' * dotenv — .env file se ATLAS_URI etc. load karta hai.',
-      " * 'dotenv/config' import karna ZAROORI hai taake process.env variables",
-      ' * is config ke evaluate hone SE PEHLE set ho jayein.',
-      ' * Install: npm i dotenv',
-      ' */',
-      "import 'dotenv/config';",
-      '',
-      'export default {',
-      "  localUri: process.env.LOCAL_URI || 'mongodb://127.0.0.1:27017',",
-      '  atlasUri: process.env.ATLAS_URI,',
-      "  dbName:   process.env.DB_NAME   || 'myapp',",
-      '',
-      '  collections: [',
-      cols,
-      '  ],',
-      '',
-      '  syncInterval: ' + syncInterval + ',',
-      '  batchSize:    200,',
-      "  syncOwner:    '*',",
-      '  realtime:     ' + realtime + ',',
-      '',
-      '  onSync(result) {',
-      '    if (result.deleted + result.downloaded + result.uploaded > 0) {',
-      '      console.log(`[MongoFire] Synced: \u2191${result.uploaded} \u2193${result.downloaded} DEL:${result.deleted}`);',
-      '    }',
-      '  },',
-      '  onError(err) {',
-      "    console.error('[MongoFire] Sync error:', err.message);",
-      '  },',
-      '};',
-      '',
-    ].join('\n');
-  }
+  // ── Step 4: TypeScript hints ─────────────────────────────────────────────────
+  _info('TypeScript Hints', [
+    'Adds @ts-check + JSDoc types to mongofire.config.js.',
+    '',
+    '✓ Enabled   VS Code shows autocomplete and catches typos',
+    '            Works perfectly in plain JavaScript projects',
+    '            No TypeScript compiler or tsconfig needed',
+    '',
+    '✕ Disabled  Plain config file, no type annotations',
+  ], 'Recommended ON — free autocomplete, zero setup cost.');
+  const enableTypescript = await p.confirm({
+    message: 'Add TypeScript hints?',
+    hint: 'ON = smart autocomplete in VS Code   OFF = plain JS',
+    initialValue: true,
+  });
+  if (p.isCancel(enableTypescript)) return _cancelled(p);
 
-  return [
-    "'use strict';",
-    '/**',
-    ' * MongoFire Config (CommonJS)',
-    ' *',
-    ' * dotenv — .env file se ATLAS_URI etc. load karta hai.',
-    ' * require("dotenv").config() ZAROORI hai taake process.env variables',
-    ' * is config ke evaluate hone SE PEHLE set ho jayein.',
-    ' * Install: npm i dotenv',
-    ' */',
-    "try { require('dotenv').config(); } catch (_) {}",
+  // ── Step 5: Verbose logging ──────────────────────────────────────────────────
+  _info('Verbose Logging', [
+    'Controls how much MongoFire prints to your console.',
     '',
-    'module.exports = {',
-    "  localUri: process.env.LOCAL_URI || 'mongodb://127.0.0.1:27017',",
-    '  atlasUri: process.env.ATLAS_URI,',
-    "  dbName:   process.env.DB_NAME   || 'myapp',",
+    '✕ OFF  Logs only when real changes happen (uploads/downloads)',
+    '       Clean output — good for production',
     '',
-    '  collections: [',
-    cols,
-    '  ],',
+    '✓ ON   Logs every sync cycle even when nothing changed',
+    '       Useful when debugging sync issues during development',
+  ], 'Keep OFF in production. Enable temporarily to debug.');
+  const enableVerbose = await p.confirm({
+    message: 'Enable verbose logging?',
+    hint: 'OFF = clean logs (recommended)   ON = log every cycle',
+    initialValue: false,
+  });
+  if (p.isCancel(enableVerbose)) return _cancelled(p);
+
+  const featureSet = new Set([
+    enableRealtime    && 'realtime',
+    enableMultitenant && 'multitenant',
+    enableTypescript  && 'typescript',
+    enableVerbose     && 'verbose',
+  ].filter(Boolean));
+
+  // ── Step 6: Collections ──────────────────────────────────────────────────────
+  _info('Collections to Sync', [
+    'MongoDB collection names MongoFire will keep in sync.',
     '',
-    '  syncInterval: ' + syncInterval + ',',
-    '  batchSize:    200,',
-    "  syncOwner:    '*',",
-    '  realtime:     ' + realtime + ',',
+    '→ Enter your actual collection names, comma-separated',
+    '→ Must match exactly what your Mongoose models use',
+    '→ Example: orders, products, users, categories',
+  ], 'Press Enter to accept defaults — edit in mongofire.config.js anytime.');
+  const rawCols = await p.text({
+    message: 'Collections to sync',
+    placeholder: DEFAULT_COLLECTIONS,
+    defaultValue: DEFAULT_COLLECTIONS,
+    validate: () => undefined,
+  });
+  if (p.isCancel(rawCols)) return _cancelled(p);
+  const colsRaw     = (rawCols || '').trim() || DEFAULT_COLLECTIONS;
+  const collections = colsRaw.split(',').map((s) => s.trim()).filter(Boolean);
+
+  // ── Step 7: Sync interval ────────────────────────────────────────────────────
+  const realtimeOn = featureSet.has('realtime');
+  _info('Sync Interval', [
+    'How often MongoFire polls Atlas for new changes.',
     '',
-    '  onSync(result) {',
-    '    if (result.deleted + result.downloaded + result.uploaded > 0) {',
-    '      console.log(`[MongoFire] Synced: \u2191${result.uploaded} \u2193${result.downloaded} DEL:${result.deleted}`);',
-    '    }',
-    '  },',
-    '  onError(err) {',
-    "    console.error('[MongoFire] Sync error:', err.message);",
-    '  },',
-    '};',
+    '→ Lower   changes appear faster, more bandwidth used',
+    '→ Higher  less resource usage, slight delay in updates',
     '',
-  ].join('\n');
-}
+    realtimeOn
+      ? '✓ Realtime is ON — polling is just a safety net. 5s is ideal.'
+      : '→ No realtime — 30s is the sweet spot for most apps.',
+  ], 'You can change this in mongofire.config.js at any time.');
+  const intervalOptions = realtimeOn
+    ? [
+        { value: 2000,  label: '2s',  hint: 'aggressive — high bandwidth usage' },
+        { value: 5000,  label: '5s',  hint: 'recommended with Change Streams' },
+        { value: 15000, label: '15s', hint: 'light fallback polling' },
+      ]
+    : [
+        { value: 5000,  label: '5s',  hint: 'fast — great for dev and testing' },
+        { value: 15000, label: '15s', hint: 'balanced — low traffic apps' },
+        { value: 30000, label: '30s', hint: 'recommended for most apps' },
+        { value: 60000, label: '60s', hint: 'conservative — minimal DB load' },
+      ];
+
+  const syncInterval = await p.select({
+    message: 'Sync interval',
+    options: intervalOptions,
+    initialValue: realtimeOn ? 5000 : 30000,
+  });
+  if (p.isCancel(syncInterval)) return _cancelled(p);
 
-function buildEntryTemplate(moduleSystem) {
-  if (moduleSystem === 'esm') {
-    return [
-      "import 'dotenv/config';",
-      "import mongofire from 'mongofire';",
-      "import config from './mongofire.config.js';",
-      '',
-      'export const ready = mongofire.start(config);',
+  // ── Step 8: Owner field (only if multi-tenant) ───────────────────────────────
+  let ownerField = '*';
+  if (featureSet.has('multitenant')) {
+    _info('Owner Field', [
+      'The document field that identifies who owns each record.',
       '',
-      "mongofire.on('online',  () => console.log('[MongoFire] Online'));",
-      "mongofire.on('offline', () => console.log('[MongoFire] Offline \u2014 working locally'));",
-      'mongofire.on(\'sync\', (r) => {',
-      '  if (r.deleted + r.downloaded + r.uploaded > 0) {',
-      '    console.log(`[MongoFire] Synced: \u2191${r.uploaded} \u2193${r.downloaded} DEL:${r.deleted}`);',
-      '  }',
-      '});',
+      '→ Must exist on EVERY document in every synced collection',
+      '→ MongoFire only syncs docs where this field = current user',
+      '→ You must set this field when creating documents in your app',
       '',
-      'export { mongofire };',
-      '',
-    ].join('\n');
+      'Common names: userId, ownerId, createdBy, accountId',
+    ], 'Set req.user._id into this field on every document you create.');
+    const ownerRaw = await p.text({
+      message: 'Owner field name',
+      placeholder: 'userId',
+      defaultValue: 'userId',
+      hint: 'must exist on every synced document',
+    });
+    if (p.isCancel(ownerRaw)) return _cancelled(p);
+    ownerField = (ownerRaw || '').trim() || 'userId';
   }
 
-  return [
-    "'use strict';",
-    "const mongofire = require('mongofire');",
-    "const config    = require('./mongofire.config');",
-    '',
-    'const ready = mongofire.start(config);',
-    '',
-    "mongofire.on('online',  () => console.log('[MongoFire] Online'));",
-    "mongofire.on('offline', () => console.log('[MongoFire] Offline \u2014 working locally'));",
-    'mongofire.on(\'sync\', (r) => {',
-    '  if (r.deleted + r.downloaded + r.uploaded > 0) {',
-    '    console.log(`[MongoFire] Synced: \u2191${r.uploaded} \u2193${r.downloaded} DEL:${r.deleted}`);',
-    '  }',
-    '});',
-    '',
-    'module.exports = { mongofire, ready };',
-    '',
-  ].join('\n');
-}
-
-// ─── .env helper ─────────────────────────────────────────────────────────────
-
-function ensureEnvFile(envPath) {
-  const defaults = [
-    ['ATLAS_URI', 'mongodb+srv://USERNAME:PASSWORD@cluster0.xxxxx.mongodb.net/'],
-    ['LOCAL_URI', 'mongodb://127.0.0.1:27017'],
-    ['DB_NAME',   'myapp'],
+  // ── Step 9: Summary ───────────────────────────────────────────────────────────
+  const on  = (v) => v ? '● Enabled'  : '○ Disabled';
+  const summaryLines = [
+    `Module system    ${moduleSystem === 'auto' ? 'Auto-detect' : moduleSystem.toUpperCase()}`,
+    `Real-time sync   ${on(enableRealtime)}`,
+    `Multi-tenant     ${on(enableMultitenant)}`,
+    `TypeScript hints ${on(enableTypescript)}`,
+    `Verbose logging  ${on(enableVerbose)}`,
+    `Sync interval    ${syncInterval}ms`,
+    `Collections      ${collections.join(', ')}`,
   ];
+  if (featureSet.has('multitenant')) summaryLines.push(`Owner field      ${ownerField}`);
+  p.note(summaryLines.join('\n'), 'Configuration Summary');
 
-  if (!fs.existsSync(envPath)) {
-    let out = '# MongoFire\n';
-    for (const [k, v] of defaults) out += `${k}=${v}\n`;
-    fs.writeFileSync(envPath, out, 'utf8');
-    return { action: 'created', added: defaults.map(([k]) => k) };
+  const proceed = await p.confirm({
+    message: 'Looks good — create these files?',
+    initialValue: true,
+  });
+  if (p.isCancel(proceed) || !proceed) {
+    p.cancel('Cancelled — no files changed.');
+    return;
   }
 
-  const env     = fs.readFileSync(envPath, 'utf8');
-  const missing = defaults.filter(([k]) => !new RegExp(`^\\s*${escapeRE(k)}\\s*=`, 'm').test(env));
-  if (!missing.length) return { action: 'unchanged', added: [] };
-
-  let patch = env.endsWith('\n') ? '' : '\n';
-  patch += '\n# MongoFire\n';
-  for (const [k, v] of missing) patch += `${k}=${v}\n`;
-  fs.appendFileSync(envPath, patch, 'utf8');
-  return { action: 'updated', added: missing.map(([k]) => k) };
-}
+  // ── Write files ──────────────────────────────────────────────────────────────
+  const wasAuto        = moduleSystem === 'auto';
+  const resolvedModule = wasAuto ? detectModuleSystem(cwd, null) : moduleSystem;
+  const opts           = { collections, realtime: enableRealtime, syncInterval, ownerField, verbose: enableVerbose, typescript: enableTypescript };
+
+  const envResult   = ensureEnvFile(path.join(cwd, '.env'));
+  const cfgResult   = writeFileIfNeeded(path.join(cwd, 'mongofire.config.js'), buildConfigTemplate(resolvedModule, opts), true);
+  const entryResult = writeFileIfNeeded(path.join(cwd, 'mongofire.js'), buildEntryTemplate(resolvedModule, opts), true);
+  const hints       = collectPackageHints(cwd);
+
+  // Show clear per-file error if write failed (Windows permission issues etc)
+  const failures = [
+    cfgResult.action   === 'failed' && { file: 'mongofire.config.js', error: cfgResult.error },
+    entryResult.action === 'failed' && { file: 'mongofire.js',        error: entryResult.error },
+  ].filter(Boolean);
+
+  if (failures.length > 0) {
+    const errLines = failures.map((f) =>
+      '✕  ' + f.file.padEnd(24) + '' + f.error + ''
+    );
+    errLines.push('');
+    errLines.push('Tip: close the file in VS Code or any editor, then run init again.');
+    p.note(errLines.join('\n'), 'Could not write files');
+    p.cancel('Setup incomplete — some files could not be written.');
+    return;
+  }
 
-function writeFileIfNeeded(filePath, content, force) {
-  const exists = fs.existsSync(filePath);
-  if (exists && !force) return { action: 'skipped' };
-  fs.writeFileSync(filePath, content, 'utf8');
-  return { action: exists ? 'overwritten' : 'created' };
-}
+  const noteLines = [
+    _fileRow('.env',                envResult.action),
+    _fileRow('mongofire.config.js', cfgResult.action),
+    _fileRow('mongofire.js',        entryResult.action),
+  ];
+  if (hints.length) noteLines.push('', ...hints.map((h) => '⚠  ' + h));
+  p.note(noteLines.join('\n'), 'Files created');
+
+  const steps = [
+    `Fill in ATLAS_URI inside .env`,
+    resolvedModule === 'esm'
+      ? `Add import './mongofire.js' to your app entry point`
+      : `Add require('./mongofire') to your app entry point`,
+    `Replace app.listen() with startApp(app, port):\n`+
+    `      ${resolvedModule === 'esm'
+      ? "import { startApp } from './mongofire.js';  startApp(app, process.env.PORT || 3000);"
+      : "const { startApp } = require('./mongofire');  startApp(app, process.env.PORT || 3000);"}`,
+    `Add Schema.plugin(plugin('name')) to each model — import plugin from mongofire.js`,
+    `DO NOT call mongoose.connect() — MongoFire owns the local connection`,
+  ];
+  p.note(steps.map((s, i) => `${i + 1}.  ${s}`).join('\n'), 'Next steps');
 
-function collectPackageHints(cwd) {
-  const pkg = readPackageJson(cwd);
-  const all = Object.assign({}, pkg?.dependencies, pkg?.devDependencies, pkg?.peerDependencies);
-  const hints = [];
-  if (!all.mongoose) hints.push('mongoose not found — install: npm i mongoose');
-  if (!all.dotenv)   hints.push('dotenv not installed — REQUIRED for .env loading: npm i dotenv');
-  return hints;
+  p.outro(`✓ Setup complete!  ${resolvedModule.toUpperCase()} · ${wasAuto ? 'auto-detected' : 'manual'}`);
 }
 
-function printInitSummary(info) {
-  console.log('');
-  printResultLine('.env',                 info.envResult.action,    info.envResult.added);
-  printResultLine('mongofire.config.js',  info.configResult.action);
-  printResultLine('mongofire.js',         info.entryResult.action);
-
-  console.log('\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501');
-  console.log('\uD83D\uDD25 MongoFire ready (' + info.moduleSystem.toUpperCase() + ', ' + info.moduleSource + ')');
-
-  if (!info.force && (info.configResult.action === 'skipped' || info.entryResult.action === 'skipped')) {
-    console.log('\u2139\uFE0F  Existing files kept. Use --force to regenerate.');
-  }
-
-  console.log('\nNext steps:');
-  console.log('  1. Set ATLAS_URI in .env');
-  console.log('  2. Install dotenv if not already: npm i dotenv');
-  console.log('  3. Add your collections to mongofire.config.js');
-  if (info.moduleSystem === 'esm') {
-    console.log("  4. Schema plugin:  userSchema.plugin(mongofire.plugin('users'))");
-    console.log("  5. App entry:      import { ready } from './mongofire.js'; await ready;");
-  } else {
-    console.log("  4. Schema plugin:  UserSchema.plugin(mongofire.plugin('users'))");
-    console.log("  5. App entry:      await require('./mongofire').ready");
-  }
+// ─── Config Wizard ────────────────────────────────────────────────────────────
+async function doConfigWizard() {
+  const p       = await loadClack();
+  const cwd     = process.cwd();
+  const cfgPath = path.join(cwd, 'mongofire.config.js');
 
-  if (info.hints.length) {
-    console.log('\nHints:');
-    for (const h of info.hints) console.log('  \u26A0\uFE0F  ' + h);
+  if (!fs.existsSync(cfgPath)) {
+    console.log('\n✖  No mongofire.config.js found — run npx mongofire init first.\n');
+    process.exit(1);
   }
-  console.log('\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n');
-}
 
-function printResultLine(name, action, added) {
-  const icon  = { created: '\u2705', updated: '\u2705', overwritten: '\u267B\uFE0F', skipped: '\u26A0\uFE0F', unchanged: '\u2713' };
-  const label = { created: 'created', updated: 'updated', overwritten: 'overwritten', skipped: 'exists (skipped)', unchanged: 'unchanged' };
-  console.log((icon[action] || ' ') + ' ' + name + ' ' + (label[action] || action));
-  if (added && added.length) console.log('   + ' + added.join(', '));
-}
-
-// ─── Interactive Clean ────────────────────────────────────────────────────────
-
-async function doCleanInteractive() {
-  console.log('\n\uD83E\uDDF9 MongoFire Clean\n');
-
-  const answers = await _prompt([
-    {
-      type:    'list',
-      name:    'days',
-      message: 'Delete synced records older than:',
-      choices: [
-        { name: '1 day   (aggressive)',   value: 1 },
-        { name: '3 days',                 value: 3 },
-        { name: '7 days  (default)',      value: 7 },
-        { name: '14 days',                value: 14 },
-        { name: '30 days (conservative)', value: 30 },
+  p.intro(`\x1b[33m 🔥 MongoFire \x1b[0m\x1b[2m config \x1b[0m`);
+
+  const section = await p.select({
+    message: 'What do you want to change?',
+    options: [
+      { value: 'collections', label: 'Collections to sync' },
+      { value: 'interval',    label: 'Sync interval' },
+      { value: 'realtime',    label: 'Real-time sync toggle' },
+      { value: 'multitenant', label: 'Multi-tenant owner field' },
+      { value: 'regenerate',  label: 'Regenerate all files', hint: 'runs full wizard' },
+    ],
+  });
+  if (p.isCancel(section)) return _cancelled(p);
+  if (section === 'regenerate') { p.outro(''); return doInitWizard(); }
+
+  let content = '';
+  try { content = fs.readFileSync(cfgPath, 'utf8'); } catch (_) {}
+
+  if (section === 'collections') {
+    const match   = content.match(/collections:\s*\[([\s\S]*?)\]/);
+    const current = match ? match[1].replace(/['"\s]/g, '').split(',').filter(Boolean).join(', ') : 'users, products';
+    const rawCols = await p.text({ message: 'Collections to sync', defaultValue: current, placeholder: current });
+    if (p.isCancel(rawCols)) return _cancelled(p);
+    const cols    = rawCols.split(',').map((s) => s.trim()).filter(Boolean);
+    const newList = cols.map((c) => `    '${c}',`).join('\n');
+    fs.writeFileSync(cfgPath, content.replace(/collections:\s*\[([\s\S]*?)\]/, `collections: [\n${newList}\n  ]`), 'utf8');
+    p.outro(`\x1b[32mUpdated\x1b[0m  collections → ${cols.join(', ')}`);
+
+  } else if (section === 'interval') {
+    const syncInterval = await p.select({
+      message: 'New sync interval',
+      options: [
+        { value: 5000,  label: '5s',  hint: 'dev' },
+        { value: 15000, label: '15s', hint: 'balanced' },
+        { value: 30000, label: '30s', hint: 'recommended' },
+        { value: 60000, label: '60s', hint: 'conservative' },
       ],
-      default: 2,
-    },
-    {
-      type:    'confirm',
-      name:    'confirm',
-      message: 'Confirm delete? This cannot be undone.',
-      default: false,
-    },
-  ]);
-
-  if (!answers.confirm) {
-    console.log('\nCancelled — nothing deleted.\n');
-    process.exit(0);
+      initialValue: 30000,
+    });
+    if (p.isCancel(syncInterval)) return _cancelled(p);
+    const updated = content.replace(/syncInterval:\s*\d+/, `syncInterval: ${syncInterval}`);
+    if (updated === content) {
+      p.cancel('✖  Could not find syncInterval in config — edit manually.');
+      return;
+    }
+    fs.writeFileSync(cfgPath, updated, 'utf8');
+    p.outro(`\x1b[32mUpdated\x1b[0m  syncInterval → ${syncInterval}ms`);
+
+  } else if (section === 'realtime') {
+    const isOn     = /realtime:\s*true/.test(content);
+    const realtime = await p.confirm({ message: 'Enable real-time sync?', initialValue: !isOn });
+    if (p.isCancel(realtime)) return _cancelled(p);
+    const updated = content.replace(/realtime:\s*(true|false)/, `realtime: ${realtime}`);
+    if (updated === content) {
+      p.cancel('✖  Could not find realtime field in config — edit manually.');
+      return;
+    }
+    fs.writeFileSync(cfgPath, updated, 'utf8');
+    p.outro(`\x1b[32mUpdated\x1b[0m  realtime → ${realtime}`);
+
+  } else if (section === 'multitenant') {
+    const owner = await p.text({ message: "Owner field path  (use '*' to disable)", defaultValue: 'userId', placeholder: 'userId' });
+    if (p.isCancel(owner)) return _cancelled(p);
+    const updated = content.replace(/syncOwner:\s*['"][^'"]*['"]/, `syncOwner: '${owner}'`);
+    if (updated === content) {
+      p.cancel('✖  Could not find syncOwner in config — edit manually.');
+      return;
+    }
+    fs.writeFileSync(cfgPath, updated, 'utf8');
+    p.outro(`\x1b[32mUpdated\x1b[0m  syncOwner → ${owner}`);
   }
+}
 
-  flags.add('--days=' + answers.days);
-  await doClean();
+// ─── Init direct (flag mode) ──────────────────────────────────────────────────
+function doInitDirect(options) {
+  const cwd    = process.cwd();
+  const ms     = detectModuleSystem(cwd, options.moduleSystem);
+  const source = options.flagForced ? `--${ms}` : 'auto-detected';
+  const opts   = { collections: ['users', 'products'], realtime: false, syncInterval: 30000, ownerField: '*' };
+
+  const envResult   = ensureEnvFile(path.join(cwd, '.env'));
+  const cfgResult   = writeFileIfNeeded(path.join(cwd, 'mongofire.config.js'), buildConfigTemplate(ms, opts), !!options.force);
+  const entryResult = writeFileIfNeeded(path.join(cwd, 'mongofire.js'), buildEntryTemplate(ms, {}), !!options.force);
+  const hints       = collectPackageHints(cwd);
+
+  console.log(`\x1b[33m  🔥 MongoFire\x1b[0m  \x1b[2mv${_getVersion()}\x1b[0m\n`);
+  console.log(_fileRow('.env',               envResult.action));
+  console.log(_fileRow('mongofire.config.js', cfgResult.action));
+  console.log(_fileRow('mongofire.js',        entryResult.action));
+  if (!options.force && (cfgResult.action === 'skipped' || entryResult.action === 'skipped'))
+    console.log('\n\x1b[2m  Existing files kept — use --force to regenerate.\x1b[0m');
+  if (hints.length) { console.log(''); hints.forEach((h) => console.log(`\x1b[33m  ⚠\x1b[0m  ${h}`)); }
+  console.log(`\n\x1b[32m  Done!\x1b[0m  \x1b[2m${ms.toUpperCase()} · ${source}\x1b[0m\n`);
 }
 
 // ─── Status ───────────────────────────────────────────────────────────────────
-
 async function doStatus() {
+  const p       = await loadClack();
   const cwd     = process.cwd();
   const cfgPath = resolveConfigPath(cwd);
-  if (!cfgPath) {
-    console.error('❌ mongofire.config.js not found. Run: npx mongofire init');
-    process.exit(1);
-  }
+  if (!cfgPath) return _noConfig(p);
+
+  p.intro(`\x1b[33m 🔥 MongoFire \x1b[0m\x1b[2m status \x1b[0m`);
 
+  const spin = p.spinner();
+  spin.start('Connecting…');
   const config    = await loadConfig(cfgPath, cwd);
   const mongofire = requireMongofire();
-
   await mongofire.start(config);
   const s = await mongofire.status();
+  spin.stop('Connected');
+
+  const onlineLabel = s.online ? '\x1b[32m● online\x1b[0m' : '\x1b[31m● offline\x1b[0m';
+  p.note(
+    [
+      `Atlas       ${onlineLabel}`,
+      ``,
+      `Pending     \x1b[1m${s.pending}\x1b[0m  \x1b[2munsynced operations\x1b[0m`,
+      `  Creates   ${s.creates}`,
+      `  Updates   ${s.updates}`,
+      `  Deletes   ${s.deletes}`,
+    ].join('\n'),
+    'Sync state'
+  );
 
-  console.log('\n\uD83D\uDCCA MongoFire Status');
-  console.log('\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500');
-  console.log('  Online:    ' + (s.online ? '\uD83D\uDFE2 Yes' : '\uD83D\uDD34 No (offline)'));
-  console.log('  Pending:   ' + s.pending + ' total unsynced');
-  console.log('    Creates: ' + s.creates);
-  console.log('    Updates: ' + s.updates);
-  console.log('    Deletes: ' + s.deletes + '\n');
+  p.outro(s.pending === 0 ? '\x1b[32mAll caught up\x1b[0m' : `\x1b[33m${s.pending} operation(s) pending\x1b[0m`);
 
   await mongofire.stop();
   process.exit(0);
 }
 
 // ─── Clean ────────────────────────────────────────────────────────────────────
+async function doCleanWizard() {
+  const p = await loadClack();
+  p.intro(`\x1b[33m 🔥 MongoFire \x1b[0m\x1b[2m clean \x1b[0m`);
+
+  const days = await p.select({
+    message: 'Delete records synced longer than',
+    options: [
+      { value: 1,  label: '1 day',   hint: 'aggressive' },
+      { value: 3,  label: '3 days' },
+      { value: 7,  label: '7 days',  hint: 'recommended' },
+      { value: 14, label: '14 days' },
+      { value: 30, label: '30 days', hint: 'conservative' },
+    ],
+    initialValue: 7,
+  });
+  if (p.isCancel(days)) return _cancelled(p);
+
+  const ok = await p.confirm({ message: `Delete records older than ${days} day(s) — this cannot be undone`, initialValue: false });
+  if (p.isCancel(ok) || !ok) { p.cancel('Cancelled — nothing deleted.'); return; }
+
+  // Pass days directly — no outer-scope flags mutation needed.
+  await _runClean(p, days);
+}
 
 async function doClean() {
+  const p = await loadClack();
+  p.intro(`\x1b[33m 🔥 MongoFire \x1b[0m\x1b[2m clean \x1b[0m`);
   const daysArg = [...flags].find((f) => f.startsWith('--days='));
   const days    = daysArg ? parseInt(daysArg.split('=')[1], 10) : 7;
+  await _runClean(p, days);
+}
 
-  if (isNaN(days) || days < 1) {
-    console.error('❌ Invalid --days value. Example: npx mongofire clean --days=7');
+async function _runClean(p, days) {
+  // Validate: must be integer, 1–3650 (10 years max to guard against typos).
+  if (!Number.isInteger(days) || days < 1 || days > 3650) {
+    console.error('✖  Invalid --days value (must be 1–3650)');
     process.exit(1);
   }
 
   const cwd     = process.cwd();
   const cfgPath = resolveConfigPath(cwd);
-  if (!cfgPath) {
-    console.error('❌ mongofire.config.js not found. Run: npx mongofire init');
-    process.exit(1);
-  }
+  if (!cfgPath) return _noConfig(p);
 
+  const spin = p.spinner();
+  spin.start(`Deleting records older than ${days} day(s)…`);
   const config    = await loadConfig(cfgPath, cwd);
   const mongofire = requireMongofire();
-
   await mongofire.start(config);
-  console.log('\uD83E\uDDF9 Cleaning records older than ' + days + ' days...');
   const count = await mongofire.clean(days);
-  console.log('\u2705 Deleted ' + count + ' old record(s)');
+  spin.stop(`Deleted ${count} record(s)`);
+
+  p.outro(count > 0 ? `\x1b[32m${count} record(s) removed\x1b[0m` : '\x1b[2mNothing to clean\x1b[0m');
   await mongofire.stop();
   process.exit(0);
 }
 
-// ─── Interactive Conflicts ────────────────────────────────────────────────────
-
-async function doConflictsInteractive() {
+// ─── Conflicts ────────────────────────────────────────────────────────────────
+async function doConflictsWizard() {
+  const p       = await loadClack();
   const cwd     = process.cwd();
   const cfgPath = resolveConfigPath(cwd);
-  if (!cfgPath) {
-    console.error('❌ mongofire.config.js not found. Run: npx mongofire init');
-    process.exit(1);
-  }
+  if (!cfgPath) return _noConfig(p);
+
+  p.intro(`\x1b[33m 🔥 MongoFire \x1b[0m\x1b[2m conflicts \x1b[0m`);
 
+  const spin = p.spinner();
+  spin.start('Loading conflicts…');
   const config    = await loadConfig(cfgPath, cwd);
   const mongofire = requireMongofire();
-
   await mongofire.start(config);
   const list = await mongofire.conflicts();
+  spin.stop(`${list.length} conflict(s) found`);
 
   if (!list.length) {
-    console.log('\n\u2705 No unresolved conflicts.\n');
+    p.outro('\x1b[32mNo unresolved conflicts\x1b[0m');
     await mongofire.stop();
     process.exit(0);
   }
 
-  console.log('\n\u26A0\uFE0F  ' + list.length + ' unresolved conflict(s):\n');
-  for (const c of list) {
-    console.log('  \u2022 ' + c.collection + '/' + c.docId + '  op:' + c.type + '  v' + c.version + '  opId:' + c.opId);
-    if (c.lastError) console.log('    Error: ' + c.lastError);
-  }
-
-  const { action } = await _prompt([
-    {
-      type:    'list',
-      name:    'action',
-      message: 'What do you want to do?',
-      choices: [
-        { name: 'Retry all   (reset to pending, sync will re-attempt)', value: 'retry_all'    },
-        { name: 'Dismiss all (discard — accept local state)',           value: 'dismiss_all'  },
-        { name: 'Pick one to retry',                                    value: 'pick_retry'   },
-        { name: 'Pick one to dismiss',                                  value: 'pick_dismiss' },
-        { name: 'Do nothing',                                           value: 'nothing'      },
-      ],
-      default: 0,
-    },
-  ]);
+  const rows = list.map((c) =>
+    [`\x1b[1m${c.collection}/${c.docId}\x1b[0m  \x1b[2mop:${c.type}  v${c.version}\x1b[0m`, c.lastError ? `  \x1b[31m${c.lastError}\x1b[0m` : ''].filter(Boolean).join('\n')
+  ).join('\n\n');
+  p.note(rows, `${list.length} unresolved conflict(s)`);
+
+  const action = await p.select({
+    message: 'How do you want to resolve?',
+    options: [
+      { value: 'retry_all',    label: 'Retry all',     hint: 'reset to pending, sync re-attempts' },
+      { value: 'dismiss_all',  label: 'Dismiss all',   hint: 'discard — keep local state' },
+      { value: 'pick_retry',   label: 'Pick one to retry' },
+      { value: 'pick_dismiss', label: 'Pick one to dismiss' },
+      { value: 'nothing',      label: 'Do nothing' },
+    ],
+  });
+  if (p.isCancel(action)) return _cancelled(p);
 
   if (action === 'nothing') {
-    console.log('\nNo changes made.\n');
+    p.outro('\x1b[2mNo changes made\x1b[0m');
   } else if (action === 'retry_all') {
+    const s2 = p.spinner(); s2.start('Retrying…');
     for (const c of list) await mongofire.retryConflict(c.opId);
-    console.log('\n\u2705 Retried ' + list.length + ' conflict(s).\n');
+    s2.stop(`Retried ${list.length} conflict(s)`);
+    p.outro('\x1b[32mAll conflicts reset to pending\x1b[0m');
   } else if (action === 'dismiss_all') {
+    const s2 = p.spinner(); s2.start('Dismissing…');
     for (const c of list) await mongofire.dismissConflict(c.opId);
-    console.log('\n\u2705 Dismissed ' + list.length + ' conflict(s).\n');
+    s2.stop(`Dismissed ${list.length} conflict(s)`);
+    p.outro('\x1b[32mAll conflicts dismissed\x1b[0m');
   } else {
-    const { opId } = await _prompt([
-      {
-        type:    'list',
-        name:    'opId',
-        message: 'Select conflict:',
-        choices: list.map((c) => ({
-          name:  c.collection + '/' + c.docId + '  ' + c.type + '  v' + c.version,
-          value: c.opId,
-        })),
-        default: 0,
-      },
-    ]);
-    if (action === 'pick_retry') {
-      await mongofire.retryConflict(opId);
-      console.log('\n\u2705 Conflict reset to pending.\n');
-    } else {
-      await mongofire.dismissConflict(opId);
-      console.log('\n\u2705 Conflict dismissed.\n');
-    }
+    const opId = await p.select({
+      message: 'Select conflict',
+      options: list.map((c) => ({ value: c.opId, label: `${c.collection}/${c.docId}`, hint: `${c.type}  v${c.version}` })),
+    });
+    if (p.isCancel(opId)) return _cancelled(p);
+    if (action === 'pick_retry') { await mongofire.retryConflict(opId); p.outro('\x1b[32mConflict reset to pending\x1b[0m'); }
+    else { await mongofire.dismissConflict(opId); p.outro('\x1b[32mConflict dismissed\x1b[0m'); }
   }
 
   await mongofire.stop();
   process.exit(0);
 }
 
-// ─── Reconcile ────────────────────────────────────────────────────────────────
-
-async function doReconcile() {
+// ─── Compact ──────────────────────────────────────────────────────────────────
+async function doCompact() {
+  const p       = await loadClack();
   const cwd     = process.cwd();
   const cfgPath = resolveConfigPath(cwd);
-  if (!cfgPath) {
-    console.error('❌ mongofire.config.js not found. Run: npx mongofire init');
+  if (!cfgPath) return _noConfig(p);
+
+  p.intro(`\x1b[33m 🔥 MongoFire \x1b[0m\x1b[2m compact \x1b[0m`);
+
+  const daysArg = [...flags].find((f) => f.startsWith('--days='));
+  const days    = daysArg ? parseInt(daysArg.split('=')[1], 10) : 7;
+  const colArg  = [...flags].find((f) => f.startsWith('--collection='));
+  const col     = colArg ? colArg.split('=')[1] : null;
+
+  if (!Number.isInteger(days) || days < 1 || days > 3650) {
+    console.error('✖  Invalid --days value (must be 1–3650)');
     process.exit(1);
   }
 
+  const spin = p.spinner();
+  spin.start(`Compacting changelog (retention: ${days} day(s)${col ? `, collection: ${col}` : ''})…`);
+
   const config    = await loadConfig(cfgPath, cwd);
   const mongofire = requireMongofire();
+  await mongofire.start(config);
+  const result = await mongofire.compact({ retentionDays: days, collection: col || undefined, verbose: false });
+  spin.stop(`Done — scanned ${result.scanned}, deleted ${result.deleted}, kept ${result.kept} (${result.durationMs}ms)`);
 
+  p.outro(
+    result.deleted > 0
+      ? `\x1b[32m${result.deleted} superseded row(s) removed\x1b[0m`
+      : '\x1b[2mNothing to compact — changelog is already lean\x1b[0m'
+  );
+  await mongofire.stop();
+  process.exit(0);
+}
+
+// ─── Reconcile ────────────────────────────────────────────────────────────────
+async function doReconcile(opts = {}) {
+  const p       = await loadClack();
+  const cwd     = process.cwd();
+  const cfgPath = resolveConfigPath(cwd);
+  if (!cfgPath) return _noConfig(p);
+
+  p.intro(`\x1b[33m 🔥 MongoFire \x1b[0m\x1b[2m reconcile \x1b[0m`);
+
+  const fullScan  = opts.fullScan !== false;
+  const scanLabel = fullScan ? 'full scan' : 'Phase 1 only (--no-full-scan)';
+
+  const spin = p.spinner();
+  spin.start(`Scanning for lost writes… \x1b[2m(${scanLabel})\x1b[0m`);
+  const config    = await loadConfig(cfgPath, cwd);
+  const mongofire = requireMongofire();
   await mongofire.start(config);
-  console.log('\n\uD83D\uDD0D Running reconciliation scan...\n');
 
-  const results = await mongofire.reconcile({ verbose: true });
+  const reconcileArg = opts.collection
+    ? opts.collection
+    : { fullScan, verbose: true };
+
+  const results = await mongofire.reconcile(reconcileArg, { fullScan, verbose: true });
   const total   = results.reduce((s, r) => s + (r.totalQueued || 0), 0);
+  spin.stop('Scan complete');
 
-  console.log('\n\uD83D\uDCCA Reconciliation Results');
-  console.log('\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500');
-  for (const r of results) {
-    if (r.error) {
-      console.log('  \u274C ' + r.collection + ': ' + r.error);
-    } else {
-      console.log('  ' + r.collection + ': P1=' + r.phase1.queued + ' P2=' + r.phase2.queued + ' queued');
-    }
-  }
-  console.log('\n  Total re-queued: ' + total);
-  console.log(total > 0 ? '  \u2705 Lost writes recovered.\n' : '  \u2705 No untracked operations found.\n');
+  const rows = results.map((r) => {
+    if (r.error) return `\x1b[31m✖\x1b[0m  ${r.collection}  \x1b[2m${r.error}\x1b[0m`;
+    const q = (r.phase1?.queued || 0) + (r.phase2?.queued || 0);
+    return `${q > 0 ? '\x1b[33m↻\x1b[0m' : '\x1b[32m✓\x1b[0m'}  \x1b[1m${r.collection}\x1b[0m  \x1b[2mP1:${r.phase1?.queued || 0}  P2:${r.phase2?.queued || 0} re-queued\x1b[0m`;
+  }).join('\n');
+  p.note(rows, 'Results');
 
+  p.outro(total > 0 ? `\x1b[33m${total} lost write(s) recovered\x1b[0m` : '\x1b[32mNo untracked operations found\x1b[0m');
   await mongofire.stop();
   process.exit(0);
 }
 
-// ─── Helpers ─────────────────────────────────────────────────────────────────
+// ─── Config templates ─────────────────────────────────────────────────────────
+function buildConfigTemplate(ms, opts = {}) {
+  const cols         = (opts.collections?.length ? opts.collections : ['orders', 'products', 'users']).map((c) => `    '${c}',`).join('\n');
+  const realtime     = !!opts.realtime;
+  const syncInterval = opts.syncInterval || 30000;
+  const ownerField   = (opts.ownerField && opts.ownerField !== '*') ? opts.ownerField : '*';
+  const tsCheck      = opts.typescript ? '\n// @ts-check\n/** @type {import("mongofire").SyncConfig} */' : '';
+  const verbose      = !!opts.verbose;
+  const syncLog      = verbose
+    ? "    console.log(`[MongoFire] ↑${result.uploaded} ↓${result.downloaded} DEL:${result.deleted}`);"
+    : "    if (result.deleted + result.downloaded + result.uploaded > 0) {\n      console.log(`[MongoFire] Synced: ↑${result.uploaded} ↓${result.downloaded} DEL:${result.deleted}`);\n    }";
+
+  const body = [
+    `  // ── Required ─────────────────────────────────────────────────────────`,
+    `  localUri:     process.env.LOCAL_URI || 'mongodb://127.0.0.1:27017',`,
+    `  atlasUri:     process.env.ATLAS_URI,`,
+    `  dbName:       process.env.DB_NAME   || 'myapp',`,
+    ``,
+    `  collections: [`,
+    cols,
+    `  ],`,
+    ``,
+    `  // ── Sync behaviour ───────────────────────────────────────────────────`,
+    `  syncInterval: ${syncInterval},           // ms — minimum 500`,
+    `  batchSize:    200,               // docs per upload batch (1–10000)`,
+    `  realtime:     ${realtime},            // Atlas Change Streams — instant push`,
+    `  syncOwner:    '${ownerField}',        // '*' = all data · 'userId' = per-user isolation`,
+    ``,
+    `  // ── Maintenance (safe defaults — change when needed) ─────────────────`,
+    `  cleanDays:        7,             // auto-delete synced records older than N days`,
+    `  reconcileOnStart: true,          // repair writes lost to crashes on startup`,
+    `  verbose:          ${String(verbose).padEnd(5)},         // log every sync cycle (useful for debugging)`,
+    ``,
+    `  // ── Advanced (disabled by default — uncomment to enable) ─────────────`,
+    `  // autoCompact: true,             // compact changelog (60–80% size reduction)`,
+    `  // compactEvery: 100,             // run compaction every N sync cycles`,
+    `  // compactRetentionDays: 7,       // keep rows newer than this after compaction`,
+    `  // rateLimiter: {                 // protect Atlas from sync storms`,
+    `  //   tokenBucket:    { capacity: 100, refillRate: 50 },`,
+    `  //   circuitBreaker: { failureThreshold: 5, timeout: 30000 },`,
+    `  // },`,
+    ownerField === '*'
+      ? `  // syncOwner: 'userId',          // uncomment for multi-tenant (per-user sync)`
+      : `  // multi-tenant ON: only syncs docs where document.${ownerField} === syncOwner value`,
+    ``,
+    `  // ── Callbacks ────────────────────────────────────────────────────────`,
+    `  onSync(result) {`,
+    syncLog,
+    `  },`,
+    `  onError(err) {`,
+    `    console.error('[MongoFire] Sync error:', err.message);`,
+    `  },`,
+  ].join('\n');
 
-function requireMongofire() {
+  if (ms === 'esm') {
+    return `${tsCheck}\nimport 'dotenv/config';\n\n// MongoFire configuration (ESM)\nexport default {\n${body}\n};\n`;
+  }
+  return `${tsCheck}\n'use strict';\ntry { require('dotenv').config(); } catch (_) {}\n\n// MongoFire configuration (CommonJS)\nmodule.exports = {\n${body}\n};\n`;
+}
+
+function buildEntryTemplate(ms, opts = {}) {
+  const syncLog = opts.verbose
+    ? `_mongofire.on('sync', (r) => console.log(\`🔄 [MongoFire] Synced: ↑\${r.uploaded} ↓\${r.downloaded} DEL:\${r.deleted}\`));`
+    : `_mongofire.on('sync', (r) => {\n  if (r.uploaded + r.downloaded + r.deleted > 0) {\n    console.log(\`🔄 [MongoFire] Sync complete — ↑\${r.uploaded} uploaded  ↓\${r.downloaded} downloaded  🗑 \${r.deleted} deleted\`);\n  }\n});`;
+
+  if (ms === 'esm') {
+    return [
+      `// mongofire.js — ESM production entry point`,
+      `//`,
+      `// ⚠️  DO NOT call mongoose.connect() — MongoFire handles this automatically.`,
+      `//`,
+      `// server.js usage:`,
+      `//   import { startApp } from './mongofire.js';`,
+      `//   startApp(app, process.env.PORT || 3000);`,
+      `//`,
+      `// model.js usage:`,
+      `//   import { plugin } from './mongofire.js';`,
+      `//   UserSchema.plugin(plugin('users'));`,
+      ``,
+      `import { createRequire }               from 'module';`,
+      `import { fileURLToPath, pathToFileURL } from 'url';`,
+      `import path from 'path';`,
+      `import fs   from 'fs';`,
+      ``,
+      `const require   = createRequire(import.meta.url);`,
+      `const __dirname = path.dirname(fileURLToPath(import.meta.url));`,
+      ``,
+      `// Load .env synchronously — dotenv is CJS, always safe to require()`,
+      `try {`,
+      `  const e = [path.join(process.cwd(),'.env'), path.join(__dirname,'.env')].find(p => fs.existsSync(p));`,
+      `  if (e) require('dotenv').config({ path: e });`,
+      `} catch (_) {}`,
+      ``,
+      `const _mongofire = require('mongofire');`,
+      ``,
+      `_mongofire.on('localReady', () => console.log('✅ [MongoFire] Local MongoDB connected'));`,
+      `_mongofire.on('online',  () => console.log('🌐 [MongoFire] Atlas connected — sync active'));`,
+      `_mongofire.on('offline', () => console.log('📴 [MongoFire] Atlas offline — changes queued locally'));`,
+      syncLog,
+      `_mongofire.on('error', (err) => console.error('❌ [MongoFire] Error:', err?.message || err));`,
+      ``,
+      `// loadConfigFile() auto-detects CJS/ESM — safe on Node 22+ (no ERR_INTERNAL_ASSERTION)`,
+      `async function _loadAndStart() {`,
+      `  const result = await _mongofire.loadConfigFile([process.cwd(), __dirname]);`,
+      `  if (!result) { console.error('\\n❌ mongofire.config.js not found. Run: npx mongofire init\\n'); process.exit(1); }`,
+      `  if (!result.config?.collections?.length) { console.error('\\n❌ mongofire.config.js has no collections.\\n'); process.exit(1); }`,
+      `  return _mongofire.start(result.config);`,
+      `}`,
+      `const _startPromise = _loadAndStart();`,
+      ``,
+      `export async function startApp(app, port = 3000) {`,
+      `  await _startPromise.catch(() => {});`,
+      `  try {`,
+      `    await _mongofire.localReady;`,
+      `  } catch (err) {`,
+      `    console.error('\\n❌ [MongoFire] Local MongoDB failed to connect.\\n' +`,
+      `      \`   Reason: \${err?.message || err}\\n\` +`,
+      `      '   Server will NOT start in a broken state.\\n');`,
+      `    process.exit(1);`,
+      `  }`,
+      `  return new Promise((resolve, reject) => {`,
+      `    const server = app.listen(Number(port) || 3000, (err) => {`,
+      `      if (err) { console.error('❌ Server listen failed:', err.message); reject(err); process.exit(1); }`,
+      `      console.log(\`🚀 [MongoFire] Server ready on port \${port}\`);`,
+      `      resolve(server);`,
+      `    });`,
+      `    server.on('error', (err) => { console.error('❌ Server error:', err.message); reject(err); process.exit(1); });`,
+      `  });`,
+      `}`,
+      ``,
+      `export function plugin(collectionName, options = {}) {`,
+      `  return _mongofire.plugin(collectionName, options);`,
+      `}`,
+      ``,
+      `export const localReady = _mongofire.localReady;`,
+      `export const ready      = _startPromise;`,
+      `export { _mongofire as mongofire };`,
+      `export default _mongofire;`,
+      ``,
+    ].join('\n');
+  }
+
+  return [
+    `// mongofire.js — CJS production entry point`,
+    `//`,
+    `// ⚠️  DO NOT call mongoose.connect() — MongoFire handles this automatically.`,
+    `//`,
+    `// server.js usage:`,
+    `//   const { startApp } = require('./mongofire');`,
+    `//   startApp(app, process.env.PORT || 3000);`,
+    `//`,
+    `// model.js usage:`,
+    `//   const { plugin } = require('./mongofire');`,
+    `//   UserSchema.plugin(plugin('users'));`,
+    ``,
+    `'use strict';`,
+    `const _mongofire = require('mongofire');`,
+    `const _config    = require('./mongofire.config');`,
+    ``,
+    `_mongofire.on('localReady', () => console.log('✅ [MongoFire] Local MongoDB connected'));`,
+    `_mongofire.on('online',  () => console.log('🌐 [MongoFire] Atlas connected — sync active'));`,
+    `_mongofire.on('offline', () => console.log('📴 [MongoFire] Atlas offline — changes queued locally'));`,
+    syncLog,
+    `_mongofire.on('error', (err) => console.error('❌ [MongoFire] Error:', err?.message || err));`,
+    ``,
+    `const _startPromise = _mongofire.start(_config);`,
+    ``,
+    `async function startApp(app, port = 3000) {`,
+    `  try {`,
+    `    await _mongofire.localReady;`,
+    `  } catch (err) {`,
+    `    console.error('\\n❌ [MongoFire] Local MongoDB failed to connect.\\n' +`,
+    `      \`   Reason: \${err?.message || err}\\n\` +`,
+    `      '   Server will NOT start in a broken state.\\n');`,
+    `    process.exit(1);`,
+    `  }`,
+    `  return new Promise((resolve, reject) => {`,
+    `    const server = app.listen(Number(port) || 3000, (err) => {`,
+    `      if (err) { console.error('❌ Server listen failed:', err.message); reject(err); process.exit(1); }`,
+    `      console.log(\`🚀 [MongoFire] Server ready on port \${port}\`);`,
+    `      resolve(server);`,
+    `    });`,
+    `    server.on('error', (err) => { console.error('❌ Server error:', err.message); reject(err); process.exit(1); });`,
+    `  });`,
+    `}`,
+    ``,
+    `function plugin(collectionName, options = {}) {`,
+    `  return _mongofire.plugin(collectionName, options);`,
+    `}`,
+    ``,
+    `module.exports = { startApp, plugin, mongofire: _mongofire, ready: _startPromise, localReady: _mongofire.localReady };`,
+    ``,
+  ].join('\n');
+}
+
+// ─── File helpers ─────────────────────────────────────────────────────────────
+function ensureEnvFile(envPath) {
+  const defaults = [
+    ['ATLAS_URI', 'mongodb+srv://USERNAME:PASSWORD@cluster0.xxxxx.mongodb.net/'],
+    ['LOCAL_URI', 'mongodb://127.0.0.1:27017'],
+    ['DB_NAME',   'myapp'],
+  ];
+  if (!fs.existsSync(envPath)) {
+    fs.writeFileSync(envPath, '# MongoFire\n' + defaults.map(([k, v]) => `${k}=${v}`).join('\n') + '\n', 'utf8');
+    return { action: 'created' };
+  }
+  const env     = fs.readFileSync(envPath, 'utf8');
+  const missing = defaults.filter(([k]) => !new RegExp(`^\\s*${escapeRE(k)}\\s*=`, 'm').test(env));
+  if (!missing.length) return { action: 'unchanged' };
+  fs.appendFileSync(envPath, '\n# MongoFire\n' + missing.map(([k, v]) => `${k}=${v}`).join('\n') + '\n', 'utf8');
+  return { action: 'updated' };
+}
+
+function writeFileIfNeeded(filePath, content, force) {
+  const exists = fs.existsSync(filePath);
+  if (exists && !force) return { action: 'skipped' };
+
+  // Write to a temp file first, then rename — avoids Windows permission
+  // errors when overwriting a file that may be open in another process.
+  const tmpPath = filePath + '.mftmp';
+  try {
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    // On Windows, renameSync fails if dest exists — remove it first
+    if (exists) {
+      try { fs.unlinkSync(filePath); } catch (_) {}
+    }
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    // Fallback: direct write (works on most systems)
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    fs.writeFileSync(filePath, content, { encoding: 'utf8', flag: 'w' });
+  }
+  return { action: exists ? 'overwritten' : 'created' };
+}
+
+function collectPackageHints(cwd) {
+  const pkg = readPackageJson(cwd);
+  const all = Object.assign({}, pkg?.dependencies, pkg?.devDependencies, pkg?.peerDependencies);
+  const out = [];
+  if (!all.mongoose) out.push('mongoose not installed — npm i mongoose');
+  if (!all.dotenv)   out.push('dotenv not installed — npm i dotenv');
+  return out;
+}
+
+function _fileRow(name, action) {
+  const icons  = { created: '\x1b[32m+\x1b[0m', overwritten: '\x1b[33m~\x1b[0m', skipped: '\x1b[2m–\x1b[0m', unchanged: '\x1b[2m–\x1b[0m', updated: '\x1b[32m+\x1b[0m' };
+  const labels = { created: '\x1b[2mcreated\x1b[0m', overwritten: '\x1b[33mupdated\x1b[0m', skipped: '\x1b[2mexists\x1b[0m', unchanged: '\x1b[2munchanged\x1b[0m', updated: '\x1b[2mupdated\x1b[0m' };
+  return `  ${icons[action] || ' '}  ${name.padEnd(24)}${labels[action] || action}`;
+}
+
+// ─── Reset Local ──────────────────────────────────────────────────────────────
+// Safe interactive wipe of the local MongoDB database.
+// Drops all _mf_* internal collections plus the configured data collections so
+// that the next startup triggers a clean bootstrap from Atlas, with no stale ops.
+async function doResetLocal() {
+  const p       = await loadClack();
+  const cwd     = process.cwd();
+  const cfgPath = resolveConfigPath(cwd);
+  if (!cfgPath) return _noConfig(p);
+
+  p.intro(`\x1b[33m 🔥 MongoFire \x1b[0m\x1b[2m reset-local \x1b[0m`);
+
+  p.note(
+    [
+      '\x1b[1mThis will permanently delete:\x1b[0m',
+      '  • All MongoFire internal collections (_mf_changetrack, _mf_docmeta,',
+      '    _mf_sync_state, _mf_ops)',
+      '  • All configured data collections listed in mongofire.config.js',
+      '',
+      'The next startup will re-bootstrap from Atlas.',
+      '\x1b[31mAny unsynced local changes will be lost.\x1b[0m',
+    ].join('\n'),
+    'WARNING'
+  );
+
+  const ok = await p.confirm({
+    message: 'Are you sure you want to reset the entire local database?',
+    initialValue: false,
+  });
+  if (p.isCancel(ok) || !ok) { p.cancel('Cancelled — nothing was deleted.'); return; }
+
+  const spin = p.spinner();
+  spin.start('Connecting to local MongoDB…');
+
+  let config;
   try {
-    return require(path.join(__dirname, '..', 'dist', 'src', 'index.cjs'));
-  } catch (_) {
+    config = await loadConfig(cfgPath, cwd);
+  } catch (err) {
+    spin.stop('Failed to load config');
+    p.cancel(`Config error: ${err.message}`);
+    process.exit(1);
+  }
+
+  const mongofire = requireMongofire();
+  await mongofire.start(config);
+
+  const localDb   = mongofire._conn?.local || mongofire.conn?.local;
+  const userCols  = Array.isArray(config.collections) ? config.collections : [];
+  const mfCols    = ['_mf_changetrack', '_mf_docmeta', '_mf_sync_state', '_mf_ops', '_mf_devices'];
+  const allToDrop = [...new Set([...mfCols, ...userCols])];
+
+  spin.start(`Dropping ${allToDrop.length} collection(s)…`);
+
+  let dropped = 0, failed = 0;
+  for (const col of allToDrop) {
     try {
-      return require(path.join(__dirname, '..', 'src', 'index.cjs'));
+      await localDb.collection(col).drop();
+      dropped++;
     } catch (err) {
-      console.error('❌ MongoFire load failed:', err.message);
-      process.exit(1);
+      // collection may not exist — that is fine
+      if (!err.message?.includes('ns not found') && !err.codeName?.includes('NamespaceNotFound')) {
+        failed++;
+        console.error(`\n✖  Failed to drop "${col}":`, err.message);
+      }
     }
   }
+
+  spin.stop(`Dropped ${dropped} collection(s)${failed ? `, ${failed} error(s)` : ''}`);
+
+  p.outro(
+    failed === 0
+      ? '\x1b[32mLocal database reset complete.\x1b[0m  Start your app to re-bootstrap from Atlas.'
+      : `\x1b[33mReset finished with ${failed} error(s).\x1b[0m  Check logs above.`
+  );
+
+  await mongofire.stop();
+  process.exit(0);
+}
+
+// ─── Shared utils ─────────────────────────────────────────────────────────────
+function _cancelled(p) { p.cancel('Cancelled.'); process.exit(0); }
+function _noConfig(p)  { p.cancel('No mongofire.config.js found — run npx mongofire init first.'); process.exit(1); }
+
+function detectModuleSystem(cwd, override) {
+  if (override && override !== 'auto') return override;
+  const pkg = readPackageJson(cwd);
+  if (pkg?.type === 'module')   return 'esm';
+  if (pkg?.type === 'commonjs') return 'cjs';
+  const probes = ['index.js', 'app.js', 'server.js', 'main.js', path.join('src', 'index.js'), path.join('src', 'main.js')];
+  for (const rel of probes) {
+    const full = path.join(cwd, rel);
+    if (!fs.existsSync(full)) continue;
+    const code = fs.readFileSync(full, 'utf8');
+    if (/\bimport\s.+from\s+['"]/.test(code) || /\bexport\s+default\b/.test(code)) return 'esm';
+    if (/\brequire\(/.test(code) || /\bmodule\.exports\b/.test(code)) return 'cjs';
+  }
+  return 'cjs';
+}
+
+function requireMongofire() {
+  try { return require(path.join(__dirname, '..', 'dist', 'src', 'index.cjs')); } catch (_) {}
+  try { return require(path.join(__dirname, '..', 'src', 'index.cjs')); } catch (err) {
+    console.error('✖  MongoFire core load failed:', err.message); process.exit(1);
+  }
 }
 
 function resolveConfigPath(cwd) {
@@ -819,22 +1152,19 @@ function resolveConfigPath(cwd) {
   return null;
 }
 
-async function loadConfig(configPath, cwd) {
-  const ext = path.extname(configPath).toLowerCase();
-  if (ext === '.mjs') return loadESM(configPath);
-  if (ext === '.cjs') return require(configPath);
-  if (isESMProject(cwd)) return loadESM(configPath);
-  try {
-    return require(configPath);
-  } catch (err) {
-    if (err && err.code === 'ERR_REQUIRE_ESM') return loadESM(configPath);
-    throw err;
-  }
+// AUTO-DETECT: always use dynamic import() for config files.
+// This works for CJS projects, ESM projects ("type":"module"), .cjs, .mjs,
+// and all Node 14+ versions without ERR_INTERNAL_ASSERTION or ERR_REQUIRE_ESM.
+// import() wraps CJS module.exports as { default: ... } — we unwrap it below.
+// There is no longer any need to branch on extension or package.json "type".
+async function loadConfig(configPath) {
+  const mod = await import(pathToFileURL(configPath).href);
+  return (mod.default !== undefined) ? mod.default : mod;
 }
 
+// Kept as alias for any internal callers that still reference loadESM directly.
 async function loadESM(filePath) {
-  const mod = await import(pathToFileURL(filePath).href);
-  return mod.default || mod;
+  return loadConfig(filePath);
 }
 
 function readPackageJson(cwd) {
@@ -843,10 +1173,65 @@ function readPackageJson(cwd) {
   try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
 }
 
-function isESMProject(cwd) {
-  return readPackageJson(cwd)?.type === 'module';
-}
+function escapeRE(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
 
-function escapeRE(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// ─── Minimal fallback (if @clack/prompts not available) ───────────────────────
+function buildFallbackClack() {
+  const readline = require('readline');
+  let rl;
+  function getRL() {
+    if (!rl) {
+      process.stdin.resume();
+      rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: IS_TTY });
+      rl.on('error', () => {});
+    }
+    return rl;
+  }
+  function ask(q) {
+    return new Promise((res) => {
+      const r = getRL();
+      r.once('close', () => res(''));
+      r.question(q, (a) => res(a.trim()));
+    });
+  }
+  return {
+    isCancel: () => false,
+    intro:  (t) => console.log(`\n┌  ${t}\n│`),
+    outro:  (m) => { console.log(`│\n└  ${m}\n`); if (rl) rl.close(); },
+    cancel: (m) => { console.log(`│\n└  ${m}\n`); if (rl) rl.close(); },
+    note:   (body, title) => { if (title) console.log(`│\n│  ${title}`); body.split('\n').forEach((l) => console.log(`│  ${l}`)); },
+    spinner: () => ({ start: (m) => process.stdout.write(`│\n│  ${m} `), stop: (m) => console.log(`→ ${m}`) }),
+    async select({ message, options, initialValue }) {
+      console.log(`│\n◇  ${message}`);
+      options.forEach((o, i) => {
+        const hint  = o.hint ? `\x1b[2m  —  ${o.hint}\x1b[0m` : '';
+        const mark  = o.value === initialValue ? ' \x1b[33m(default)\x1b[0m' : '';
+        console.log(`│  ${i + 1}. ${o.label}${mark}${hint}`);
+      });
+      const def = options.findIndex((o) => o.value === initialValue);
+      const ans = await ask(`│  Enter number [${def >= 0 ? def + 1 : 1}]: `);
+      const idx = ans ? Math.max(0, parseInt(ans, 10) - 1) : (def >= 0 ? def : 0);
+      return options[idx]?.value ?? options[0]?.value;
+    },
+    async multiselect({ message, options }) {
+      console.log(`│\n◇  ${message}  (comma-separated numbers, blank = none)`);
+      options.forEach((o, i) => console.log(`│  ${i + 1}. ${o.label}${o.hint ? '  (' + o.hint + ')' : ''}`));
+      const ans = await ask('│  Numbers: ');
+      if (!ans.trim()) return [];
+      return ans.split(',').map((s) => options[parseInt(s.trim(), 10) - 1]?.value).filter(Boolean);
+    },
+    async text({ message, defaultValue, placeholder }) {
+      const hint = defaultValue ? ` (default: ${defaultValue})` : placeholder ? ` e.g. ${placeholder}` : '';
+      const ans  = await ask(`│\n◇  ${message}${hint}\n│  `);
+      return (ans || '').trim() || defaultValue || '';
+    },
+    async confirm({ message, initialValue, hint }) {
+      const defaultYes = initialValue !== false;
+      if (hint) console.log(`│  \x1b[2m${hint}\x1b[0m`);
+      const ans = await ask(`│\n◇  ${message}  (${defaultYes ? 'Y/n' : 'y/N'}) `);
+      const t   = (ans || '').trim().toLowerCase();
+      if (t === '') return defaultYes;
+      return t === 'y' || t === 'yes';
+    },
+  };
 }