mongofire 6.5.1 → 6.5.3

package/bin/mongofire.cjs

@@ -0,0 +1,852 @@
+#!/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.
+process.on('uncaughtException', (err) => {
+  console.error('\n❌ MongoFire CLI 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);
+  if (process.env.MONGOFIRE_DEBUG) console.error(reason?.stack || reason);
+  process.exit(1);
+});
+
+const fs   = require('fs');
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const args    = process.argv.slice(2);
+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');
+  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.
+(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
+  }
+})();
+
+// ─── 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 });
+  } 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'),
+    });
+  }
+
+} 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);
+    });
+  }
+
+} 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);
+  }
+
+} else if (command === 'reconcile') {
+  doReconcile().catch((err) => {
+    console.error('❌ Error:', err.message);
+    process.exit(1);
+  });
+
+} else {
+  showHelp();
+}
+
+// ─── Help ─────────────────────────────────────────────────────────────────────
+
+function showHelp() {
+  console.log(`
+\uD83D\uDD25 MongoFire CLI v${_getVersion()}
+
+  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
+
+  npx mongofire status
+      Show pending sync operation counts
+
+  npx mongofire clean [--days=N]
+      Delete old synced records (default: 7 days)
+      Example: npx mongofire clean --days=3
+
+  npx mongofire conflicts
+      View, retry, or dismiss unresolved conflicts
+
+  npx mongofire reconcile
+      Recover writes lost from crashes
+
+  Tip: Run with MONGOFIRE_DEBUG=1 for full error stack traces
+`);
+}
+
+function _getVersion() {
+  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
+  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 _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');
+      });
+
+    } 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 || '');
+      });
+    }
+  });
+}
+
+// ─── 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' },
+      ],
+      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);
+  }
+
+  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,
+  });
+}
+
+// ─── 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';
+
+  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 ────────────────────────────────────────────────────────
+
+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;
+
+  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');
+  }
+
+  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 (_) {}",
+    '',
+    'module.exports = {',
+    "  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');
+}
+
+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);',
+      '',
+      "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}`);',
+      '  }',
+      '});',
+      '',
+      'export { mongofire };',
+      '',
+    ].join('\n');
+  }
+
+  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'],
+  ];
+
+  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 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) };
+}
+
+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' };
+}
+
+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;
+}
+
+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");
+  }
+
+  if (info.hints.length) {
+    console.log('\nHints:');
+    for (const h of info.hints) console.log('  \u26A0\uFE0F  ' + h);
+  }
+  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 },
+      ],
+      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);
+  }
+
+  flags.add('--days=' + answers.days);
+  await doClean();
+}
+
+// ─── Status ───────────────────────────────────────────────────────────────────
+
+async function doStatus() {
+  const cwd     = process.cwd();
+  const cfgPath = resolveConfigPath(cwd);
+  if (!cfgPath) {
+    console.error('❌ mongofire.config.js not found. Run: npx mongofire init');
+    process.exit(1);
+  }
+
+  const config    = await loadConfig(cfgPath, cwd);
+  const mongofire = requireMongofire();
+
+  await mongofire.start(config);
+  const s = await mongofire.status();
+
+  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');
+
+  await mongofire.stop();
+  process.exit(0);
+}
+
+// ─── Clean ────────────────────────────────────────────────────────────────────
+
+async function doClean() {
+  const daysArg = [...flags].find((f) => f.startsWith('--days='));
+  const days    = daysArg ? parseInt(daysArg.split('=')[1], 10) : 7;
+
+  if (isNaN(days) || days < 1) {
+    console.error('❌ Invalid --days value. Example: npx mongofire clean --days=7');
+    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);
+  }
+
+  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)');
+  await mongofire.stop();
+  process.exit(0);
+}
+
+// ─── Interactive Conflicts ────────────────────────────────────────────────────
+
+async function doConflictsInteractive() {
+  const cwd     = process.cwd();
+  const cfgPath = resolveConfigPath(cwd);
+  if (!cfgPath) {
+    console.error('❌ mongofire.config.js not found. Run: npx mongofire init');
+    process.exit(1);
+  }
+
+  const config    = await loadConfig(cfgPath, cwd);
+  const mongofire = requireMongofire();
+
+  await mongofire.start(config);
+  const list = await mongofire.conflicts();
+
+  if (!list.length) {
+    console.log('\n\u2705 No unresolved conflicts.\n');
+    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,
+    },
+  ]);
+
+  if (action === 'nothing') {
+    console.log('\nNo changes made.\n');
+  } else if (action === 'retry_all') {
+    for (const c of list) await mongofire.retryConflict(c.opId);
+    console.log('\n\u2705 Retried ' + list.length + ' conflict(s).\n');
+  } else if (action === 'dismiss_all') {
+    for (const c of list) await mongofire.dismissConflict(c.opId);
+    console.log('\n\u2705 Dismissed ' + list.length + ' conflict(s).\n');
+  } 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');
+    }
+  }
+
+  await mongofire.stop();
+  process.exit(0);
+}
+
+// ─── Reconcile ────────────────────────────────────────────────────────────────
+
+async function doReconcile() {
+  const cwd     = process.cwd();
+  const cfgPath = resolveConfigPath(cwd);
+  if (!cfgPath) {
+    console.error('❌ mongofire.config.js not found. Run: npx mongofire init');
+    process.exit(1);
+  }
+
+  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 total   = results.reduce((s, r) => s + (r.totalQueued || 0), 0);
+
+  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');
+
+  await mongofire.stop();
+  process.exit(0);
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+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 load failed:', err.message);
+      process.exit(1);
+    }
+  }
+}
+
+function resolveConfigPath(cwd) {
+  for (const f of ['mongofire.config.js', 'mongofire.config.mjs', 'mongofire.config.cjs']) {
+    const full = path.join(cwd, f);
+    if (fs.existsSync(full)) return full;
+  }
+  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;
+  }
+}
+
+async function loadESM(filePath) {
+  const mod = await import(pathToFileURL(filePath).href);
+  return mod.default || mod;
+}
+
+function readPackageJson(cwd) {
+  const p = path.join(cwd, 'package.json');
+  if (!fs.existsSync(p)) return null;
+  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, '\\$&');
+}