mongofire 6.5.5 → 6.5.6

package/bin/mongofire.cjs

@@ -0,0 +1,1237 @@
+#!/usr/bin/env node
+'use strict';
+
+// 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 error:', err.message || err);
+  if (process.env.MONGOFIRE_DEBUG) console.error(err.stack);
+  process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+  console.error('\n✖ MongoFire 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
+(function _loadDotenv() {
+  const p = path.join(process.cwd(), '.env');
+  if (!fs.existsSync(p)) return;
+  try { require('dotenv').config({ path: p }); } catch (_) {}
+})();
+
+const IS_TTY = !!process.stdin.isTTY;
+
+// ─── 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 {
+    showHelp();
+  }
+})().catch((err) => {
+  console.error('\n✖ MongoFire error:', err.message || err);
+  if (process.env.MONGOFIRE_DEBUG) console.error(err.stack);
+  process.exit(1);
+});
+
+// ─── Help ─────────────────────────────────────────────────────────────────────
+function showHelp() {
+  const v = _getVersion();
+  console.log(`
+  \x1b[33m🔥 MongoFire\x1b[0m  \x1b[2mv${v}\x1b[0m
+
+  \x1b[1mUsage\x1b[0m
+
+    \x1b[36mnpx mongofire\x1b[0m \x1b[2m<command> [flags]\x1b[0m
+
+  \x1b[1mCommands\x1b[0m
+
+    \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
+
+  \x1b[1mFlags for \x1b[36minit\x1b[0m
+
+    \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
+
+  \x1b[1mFlags for \x1b[36mclean\x1b[0m
+
+    \x1b[2m--days=N\x1b[0m      Delete records older than N days (1–3650, default 7)
+
+  \x1b[1mFlags for \x1b[36mreconcile\x1b[0m
+
+    \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
+
+  \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 '?'; }
+}
+
+// ─── Load clack ───────────────────────────────────────────────────────────────
+async function loadClack() {
+  try {
+    return await import('@clack/prompts');
+  } catch {
+    return buildFallbackClack();
+  }
+}
+
+// ─── 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 {
+      process.stdout.write('|  |  ' + pad(line) + '\n');
+    }
+  }
+  if (tip) {
+    process.stdout.write('|  +- 💡 ' + pad(tip) + '\n');
+  } else {
+    process.stdout.write('|  +-\n');
+  }
+}
+
+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' },
+      ],
+      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
+  }
+
+  // ── 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',
+  });
+  if (p.isCancel(moduleSystem)) return _cancelled(p);
+
+  // ── 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);
+
+  // ── 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);
+
+  // ── 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);
+
+  // ── Step 5: Verbose logging ──────────────────────────────────────────────────
+  _info('Verbose Logging', [
+    'Controls how much MongoFire prints to your console.',
+    '',
+    '✕ OFF  Logs only when real changes happen (uploads/downloads)',
+    '       Clean output — good for production',
+    '',
+    '✓ 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.',
+    '',
+    '→ 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.',
+    '',
+    '→ Lower   changes appear faster, more bandwidth used',
+    '→ Higher  less resource usage, slight delay in updates',
+    '',
+    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);
+
+  // ── 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.',
+      '',
+      '→ 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',
+      '',
+      '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';
+  }
+
+  // ── 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');
+
+  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;
+  }
+
+  // ── 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;
+  }
+
+  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');
+
+  p.outro(`✓ Setup complete!  ${resolvedModule.toUpperCase()} · ${wasAuto ? 'auto-detected' : 'manual'}`);
+}
+
+// ─── Config Wizard ────────────────────────────────────────────────────────────
+async function doConfigWizard() {
+  const p       = await loadClack();
+  const cwd     = process.cwd();
+  const cfgPath = path.join(cwd, 'mongofire.config.js');
+
+  if (!fs.existsSync(cfgPath)) {
+    console.log('\n✖  No mongofire.config.js found — run npx mongofire init first.\n');
+    process.exit(1);
+  }
+
+  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' },
+      ],
+      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}`);
+  }
+}
+
+// ─── 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) 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'
+  );
+
+  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);
+}
+
+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) 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);
+  const count = await mongofire.clean(days);
+  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);
+}
+
+// ─── Conflicts ────────────────────────────────────────────────────────────────
+async function doConflictsWizard() {
+  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 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) {
+    p.outro('\x1b[32mNo unresolved conflicts\x1b[0m');
+    await mongofire.stop();
+    process.exit(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') {
+    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);
+    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);
+    s2.stop(`Dismissed ${list.length} conflict(s)`);
+    p.outro('\x1b[32mAll conflicts dismissed\x1b[0m');
+  } else {
+    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);
+}
+
+// ─── Compact ──────────────────────────────────────────────────────────────────
+async function doCompact() {
+  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 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);
+
+  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');
+
+  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);
+}
+
+// ─── 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');
+
+  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 {
+    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 {
+      await localDb.collection(col).drop();
+      dropped++;
+    } catch (err) {
+      // 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) {
+  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;
+}
+
+// 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) {
+  return loadConfig(filePath);
+}
+
+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 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';
+    },
+  };
+}