letfixit 0.1.0

package/server/index.js

@@ -0,0 +1,619 @@
+#!/usr/bin/env node
+require('dotenv').config();
+const express = require('express');
+const { WebSocketServer, WebSocket } = require('ws');
+const http = require('http');
+const path = require('path');
+const { spawn } = require('child_process');
+const os = require('os');
+const readline = require('readline');
+
+const flutterBridge = require('./flutter_bridge');
+const androidBridge = require('./android_bridge');
+const engine = require('./analysis_engine');
+const deviceDb = require('./device_db');
+const session = require('./session_manager');
+const { classifyWidget } = require('./widget_gpu_classifier');
+const { getModuleAnalysis, aiStatus } = require('./ai_proxy');
+const deviceReview = require('./device_review');
+const androidLive = require('./android_live');
+const adb = require('./adb_bridge');
+const model = require('./model_config');
+
+const PORT          = parseInt(process.env.DASHBOARD_PORT || '8081', 10);
+const LOCAL_AI_PORT = parseInt(process.env.LOCAL_AI_PORT  || '8080', 10);
+const ENABLE_LOCAL_AI = process.env.ENABLE_LOCAL_AI !== 'false';
+
+// llama-server is installed system-wide via: curl -LsSf https://llama.app/install.sh | sh
+// Model weights: bin/ultron/ultron-n0-beta.gguf — installed by `npm run setup`.
+const MODEL_PATH = model.MODEL_PATH;
+
+// ── Terminal styling + branded startup ─────────────────────────────────────────
+const C = { reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', mag: '\x1b[95m', grn: '\x1b[92m', yel: '\x1b[93m', cyan: '\x1b[96m' };
+const col = (x, s) => `${x}${s}${C.reset}`;
+const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function bannerBox(lines) {
+  const w = Math.max(...lines.map((l) => stripAnsi(l).length));
+  console.log(col(C.mag, '  ╔' + '═'.repeat(w + 2) + '╗'));
+  for (const l of lines) console.log(col(C.mag, '  ║ ') + l + ' '.repeat(w - stripAnsi(l).length) + col(C.mag, ' ║'));
+  console.log(col(C.mag, '  ╚' + '═'.repeat(w + 2) + '╝'));
+}
+
+function printWelcome() {
+  console.log('');
+  bannerBox([
+    '',
+    col(C.bold + C.mag, '✦  P A R I T Y F I X') + col(C.dim, '                      v0.1.0'),
+    col(C.reset, 'AI-based realtime performance analysis & suggestions'),
+    col(C.dim, 'Flutter  ·  Android  ·  iOS      powered by Ultron n0-beta'),
+    '',
+  ]);
+  console.log('');
+}
+
+// "Ultron n0-beta initializing…" — starts the local model and waits briefly for
+// it to answer, without blocking the whole boot on weight loading.
+async function initUltron() {
+  if (!ENABLE_LOCAL_AI) {
+    console.log('  ' + col(C.dim, 'Ultron n0-beta is disabled (ENABLE_LOCAL_AI=false) — using cloud fallback if configured.\n'));
+    return;
+  }
+  if (!model.isReady()) {
+    console.log('  ' + col(C.yel, '⚠  Ultron n0-beta not installed.') + ' Run ' + col(C.cyan, 'npm run setup') + ' to download it.');
+    const s = aiStatus();
+    console.log('  ' + col(C.dim, s.anyAvailable ? 'A cloud fallback key is set — analysis will use it for now.\n' : 'No AI provider yet — findings will show without suggestions until setup.\n'));
+    return;
+  }
+
+  process.stdout.write('  ' + col(C.mag, '✦ Ultron n0-beta') + col(C.dim, ' initializing'));
+  startLlamafile();
+  // Poll health for a few seconds; don't hang the boot if weights are still loading.
+  let ok = false;
+  for (let i = 0; i < 8 && !ok; i++) { process.stdout.write(col(C.dim, '.')); ok = await isLlamaHealthy(); if (!ok) await sleep(500); }
+  process.stdout.write('\n');
+  if (ok) {
+    console.log('  ' + col(C.grn, '✓ ready') + col(C.dim, `  — ${model.MODEL_NAME} running locally on :${LOCAL_AI_PORT} (${model.sizeGB()} GB, private)`));
+  } else {
+    console.log('  ' + col(C.yel, '… still loading') + col(C.dim, '  — weights load in the background (first start can take ~20s).'));
+  }
+  console.log('  ' + col(C.dim, model.DISCLAIMER.split(' — ')[0] + ' — treat suggestions as hints.\n'));
+}
+
+// ── Interactive startup ───────────────────────────────────────────────────────
+// On launch: choose framework → paste Flutter VM link → validate the connection
+// before the dashboard starts. flutter_bridge.js reads process.env.FLUTTER_VM_URL
+// lazily at connect() time, so setting it here is enough.
+const ask = (rl, q) => new Promise((res) => rl.question(q, (a) => res(a)));
+
+/** Accepts a bare port, an http(s):// VM URI, or a ws(s):// URL → normalized ws URL. */
+function normalizeVMUrl(input) {
+  let s = (input || '').trim().replace(/^['"]|['"]$/g, '');
+  if (!s) return null;
+  if (/^\d+$/.test(s)) return `ws://127.0.0.1:${s}/ws`;         // just a port
+  s = s.replace(/^http:/i, 'ws:').replace(/^https:/i, 'wss:');  // http → ws
+  if (!/^wss?:\/\//i.test(s)) s = 'ws://' + s;                  // bare host:port
+  if (!/\/ws$/.test(s)) s = s.endsWith('/') ? s + 'ws' : s + '/ws'; // ensure /ws
+  return s;
+}
+
+/** Opens a throwaway WS to the VM Service and calls getVersion to confirm it's live. */
+function validateVM(url) {
+  return new Promise((resolve) => {
+    let ws, done = false;
+    const finish = (ok) => { if (done) return; done = true; try { ws && ws.close(); } catch (_) {} resolve(ok); };
+    try { ws = new WebSocket(url); } catch { return resolve(false); }
+    const timer = setTimeout(() => finish(false), 6000);
+    ws.on('open', () => ws.send(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getVersion' })));
+    ws.on('message', (raw) => {
+      try { const m = JSON.parse(raw); if (m.id === 1) { clearTimeout(timer); finish(!!m.result); } } catch (_) {}
+    });
+    ws.on('error', () => { clearTimeout(timer); finish(false); });
+    ws.on('close', () => { clearTimeout(timer); finish(false); });
+  });
+}
+
+async function chooseFramework(rl) {
+  while (true) {
+    console.log(`
+  What do you want to analyze?
+    1) Flutter                          (VM Service — live dashboard)
+    2) Android native — live debug monitor (over adb, no SDK — live dashboard)
+    3) Connected Device Performance Test (Android / iOS — any app, iteration report)
+    4) Website                          (work in progress)`);
+    const a = (await ask(rl, '  → Select [1-4]: ')).trim().toLowerCase();
+    if (a === '1' || a === 'flutter') return 'flutter';
+    if (a === '2' || a === 'android-live' || a === 'android') return 'android-live';
+    if (a === '3' || a === 'device' || a === 'ios' || a === 'adb') return 'device';
+    if (a === '4' || a === 'website') { console.log('  ⚠️  Website support is a work in progress — please reselect.'); continue; }
+    console.log('  ⚠️  Invalid choice — enter 1, 2, 3, or 4.');
+  }
+}
+
+// Pick a device + package for the Android live monitor.
+async function promptAndroidLive(rl) {
+  if (!(await adb.isAvailable())) {
+    console.log('\n  ❌ `adb` not found. Install Android platform-tools (or set ADB_PATH in .env).');
+    return null;
+  }
+  const devices = await adb.listDevices();
+  if (devices.length === 0) {
+    console.log('\n  ⚠️  No devices in `device` state. Enable USB debugging + authorize, then retry.');
+    return null;
+  }
+  let dev = devices[0];
+  if (devices.length > 1) {
+    console.log('\n  Connected devices:');
+    devices.forEach((d, i) => console.log(`    ${i + 1}) ${d.model} (${d.serial})`));
+    const pick = parseInt(await ask(rl, `  → Select device [1-${devices.length}]: `), 10);
+    dev = devices[pick - 1] || devices[0];
+  }
+  const fg = await adb.foregroundPackage(dev.serial);
+  const prompt = fg
+    ? `  📦 App package [${fg}]: `
+    : '  📦 App package (e.g. com.example.app): ';
+  const pkg = ((await ask(rl, prompt)).trim() || fg || '').trim();
+  if (!pkg) { console.log('  ⚠️  No package — cancelled.'); return null; }
+  console.log(`  ✅ Will stream ${pkg} from ${dev.model}. Open the dashboard and switch the platform toggle to Android.`);
+  return { serial: dev.serial, pkg };
+}
+
+async function promptAndValidateVM(rl) {
+  while (true) {
+    console.log('\n  Start your app with:  flutter run --vm-service-port=8181 --disable-service-auth-codes');
+    const input = await ask(rl, '  🔌 Paste the Flutter VM Service link (or just the port): ');
+    const url = normalizeVMUrl(input);
+    if (!url) { console.log('  ⚠️  Empty input — try again.'); continue; }
+    process.stdout.write(`  ⏳ Checking ${url} ... `);
+    const ok = await validateVM(url);
+    if (ok) {
+      console.log('✅ connected');
+      process.env.FLUTTER_VM_URL = url;
+      return url;
+    }
+    console.log('❌ no response');
+    console.log('     Make sure the app is running and the link/port is correct, then try again.');
+  }
+}
+
+async function interactiveSetup() {
+  // Non-interactive (CI / background): fall back to env or default, don't block.
+  if (!process.stdin.isTTY) {
+    if (!process.env.FLUTTER_VM_URL) process.env.FLUTTER_VM_URL = 'ws://127.0.0.1:8181/ws';
+    console.log(`  ↳ Non-interactive start — using ${process.env.FLUTTER_VM_URL}`);
+    return { mode: 'flutter' };
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const framework = await chooseFramework(rl);
+  let result = { mode: framework };
+  if (framework === 'flutter') {
+    await promptAndValidateVM(rl);
+  } else if (framework === 'android-live') {
+    // Live streaming monitor — configured here, started once the server is up.
+    result.android = await promptAndroidLive(rl);
+  } else if (framework === 'device') {
+    // Self-contained review: runs iterations, writes an HTML report, opens it.
+    // Falls through afterwards so the dashboard also comes up and serves /reports.
+    await deviceReview.run((q) => ask(rl, q), { port: PORT }).catch((e) => console.error('  ❌ Device review failed:', e.message));
+  }
+  rl.close();
+  return result;
+}
+
+// ── "exit" command listener ───────────────────────────────────────────────────
+function startCommandListener() {
+  if (!process.stdin.isTTY) return;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  console.log('  💡 Type "exit" (or Ctrl+C) to stop the analyzer and local AI.\n');
+  rl.on('line', (line) => {
+    const cmd = line.trim().toLowerCase();
+    if (cmd === 'exit' || cmd === 'quit' || cmd === 'q') { rl.close(); shutdown(); }
+  });
+}
+
+// ── Nemotron local AI auto-start ──────────────────────────────────────────────
+let llamaProc = null;
+
+async function isLlamaHealthy() {
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 1500);
+    const res = await fetch(`http://localhost:${LOCAL_AI_PORT}/health`, { signal: ctrl.signal });
+    clearTimeout(t);
+    return res.ok;
+  } catch (_) {
+    return false;
+  }
+}
+
+async function startLlamafile() {
+  if (!ENABLE_LOCAL_AI) return;
+
+  if (!model.isReady()) {
+    // initUltron() already messaged the user; stay quiet here.
+    return;
+  }
+
+  // Reuse an already-running model (e.g. after a server restart) instead of
+  // spawning a duplicate that would fail to bind the port.
+  if (await isLlamaHealthy()) return;
+
+  // Cap CPU usage: use at most half the cores (min 2) so realtime profiling and
+  // the dashboard stay responsive while the model runs. Overridable via LOCAL_AI_THREADS.
+  const threadCap = parseInt(process.env.LOCAL_AI_THREADS || '', 10) ||
+    Math.max(2, Math.floor(os.cpus().length / 2));
+
+  // 'llama' CLI is installed via: curl -LsSf https://llama.app/install.sh | sh
+  // shell:true resolves ~/.local/bin in PATH on all shells without hardcoding paths.
+  const cmd = `llama serve --model "${MODEL_PATH}" --port ${LOCAL_AI_PORT} --threads ${threadCap} --log-disable`;
+  try {
+    llamaProc = spawn(cmd, { stdio: 'ignore', detached: false, shell: true });
+  } catch (err) {
+    console.error('  ❌ llama serve failed to start:', err.message);
+    console.log('  ↳ Install llama.cpp: curl -LsSf https://llama.app/install.sh | sh');
+    console.log('  ↳ Continuing without local AI — cloud API fallback will be used.');
+    return;
+  }
+
+  llamaProc.on('error', (err) => {
+    if (err.code === 'ENOENT') {
+      console.error('  ❌ llama not in PATH. Install: curl -LsSf https://llama.app/install.sh | sh');
+    } else {
+      console.error(`  ❌ ${model.MODEL_NAME} error:`, err.message);
+    }
+    llamaProc = null;
+  });
+
+  llamaProc.on('exit', (code) => {
+    if (code !== 0 && code !== null) console.log(`  ⚠️  ${model.MODEL_NAME} exited (code ${code})`);
+    llamaProc = null;
+  });
+}
+
+function stopLlamafile() {
+  if (llamaProc) { llamaProc.kill(); llamaProc = null; }
+}
+
+// ── Express + WebSocket ───────────────────────────────────────────────────────
+const app = express();
+app.use(express.json());
+app.use(express.static(path.join(__dirname, '../dashboard/dist')));
+// Generated device performance reports (self-contained HTML, opened in a browser).
+app.use('/reports', express.static(deviceReview.REPORTS_DIR));
+
+// Auto-detected device (OS/arch) from the connected Flutter VM. Precise
+// GPU/RAM comes from the user picking a target device in the dashboard.
+let detectedDevice = null;
+
+// ── Device DB + module-test REST API ──────────────────────────────────────────
+app.get('/api/devices', (_req, res) => {
+  res.json({
+    devices: deviceDb.listDevices(),
+    configs: deviceDb.listUniqueConfigs(),
+    detected: detectedDevice,
+  });
+});
+
+app.get('/api/session', (_req, res) => {
+  res.json({ session: session.snapshot(), detected: detectedDevice });
+});
+
+// Live widget tree from the Flutter inspector, annotated with per-node GPU cost.
+function normalizeTreeNode(node, depth = 0) {
+  if (!node || depth > 60) return null;
+  const rawName = node.widgetRuntimeType || node.description || node.type || 'Widget';
+  const name = String(rawName).split(/[\s(<[]/)[0] || 'Widget'; // strip "-[GlobalKey#..]" etc.
+  const info = classifyWidget(name);
+  const kids = Array.isArray(node.children) ? node.children : [];
+  return {
+    name,
+    gpuCost: info.cost,
+    riskyTiers: info.risky,
+    note: info.note,
+    children: kids.map((c) => normalizeTreeNode(c, depth + 1)).filter(Boolean),
+  };
+}
+
+app.get('/api/widget-tree', async (_req, res) => {
+  try {
+    const raw = await flutterBridge.getWidgetTree();
+    if (!raw) {
+      return res.json({ tree: null, hint: 'Widget inspector unavailable. Connect a Flutter app running in debug mode.' });
+    }
+    res.json({ tree: normalizeTreeNode(raw) });
+  } catch (err) {
+    res.json({ tree: null, hint: err.message });
+  }
+});
+
+app.post('/api/session/start', (req, res) => {
+  const { module, targetDeviceIds } = req.body || {};
+  session.start(module, Array.isArray(targetDeviceIds) ? targetDeviceIds : []);
+  res.json({ session: session.snapshot() });
+});
+
+app.post('/api/session/next-run', (_req, res) => {
+  session.nextRun();
+  res.json({ session: session.snapshot() });
+});
+
+app.post('/api/session/stop', (_req, res) => {
+  session.stop();
+  res.json({ session: session.snapshot() });
+});
+
+app.post('/api/session/reset', (_req, res) => {
+  session.reset();
+  res.json({ ok: true });
+});
+
+// The single AI call — only fires after ≥5 completed runs.
+app.post('/api/session/analyze', async (_req, res) => {
+  const s = session.getState();
+  if (!s || s.runs.length < s.requiredRuns) {
+    return res.status(400).json({ error: `Need at least ${s ? s.requiredRuns : 5} completed runs before analysis.` });
+  }
+  s.status = 'analyzing';
+  broadcast({ _type: 'session', session: sessionSnapshot() });
+
+  const agg = session.aggregate();
+  const ai = await getModuleAnalysis(agg);
+  s.analysis = { ...agg, ai };
+  s.status = 'done';
+  broadcast({ _type: 'session', session: sessionSnapshot() });
+  res.json({ analysis: s.analysis });
+});
+
+app.get('/api/ai-status', (_req, res) => {
+  const modelReady = model.isReady();
+  res.json({
+    localAI: {
+      enabled:     ENABLE_LOCAL_AI,
+      running:     llamaProc !== null,
+      modelReady,
+      modelSizeGB: model.sizeGB(),
+      port:        LOCAL_AI_PORT,
+      model:       model.MODEL_NAME,
+      disclaimer:  model.DISCLAIMER,
+      hint:        !modelReady ? 'Run `npm run setup` to download the model.' : null,
+    },
+    cloudAI: {
+      groq:   !!process.env.GROQ_API_KEY,
+      gemini: !!process.env.GEMINI_API_KEY,
+      claude: !!process.env.CLAUDE_API_KEY,
+    },
+    anyAIAvailable: (ENABLE_LOCAL_AI && modelReady) ||
+                    !!process.env.GROQ_API_KEY ||
+                    !!process.env.GEMINI_API_KEY ||
+                    !!process.env.CLAUDE_API_KEY,
+  });
+});
+
+// Instant, code-based advice for a single widget (used by the Widget Tree on
+// tap). Zero CPU — pure classifier lookup. Pass ?ai=1 to also escalate to the
+// local LLM for a deeper, device-agnostic suggestion.
+app.get('/api/widget-advice', async (req, res) => {
+  const name = String(req.query.name || '').trim();
+  if (!name) return res.status(400).json({ error: 'name required' });
+  const info = classifyWidget(name);
+  const advice = {
+    widget: name,
+    gpuCost: info.cost,
+    riskyTiers: info.risky,
+    note: info.note,
+    source: 'code',
+  };
+
+  if (req.query.ai === '1' && info.cost !== 'low') {
+    try {
+      const { getAISuggestion } = require('./ai_proxy');
+      const ai = await getAISuggestion({
+        rule: 'widget_advice',
+        widget: name,
+        title: `${name}: ${info.cost} GPU cost widget`,
+        metric: { value: info.cost, unit: 'gpu-cost', budget: 'low' },
+        hypothesis: info.note,
+      });
+      if (ai) advice.ai = ai;
+    } catch (_) {}
+  }
+  res.json(advice);
+});
+
+// Deeper analysis of a single finding, triggered explicitly by the user
+// ("Deep analyze" button). An LLM call here is intentional — it's user-driven,
+// not per-finding automatic, so it doesn't hammer the CPU passively.
+app.post('/api/deep-analyze', async (req, res) => {
+  const finding = req.body || {};
+  if (!finding.rule && !finding.title) return res.status(400).json({ error: 'finding required' });
+  try {
+    const { getAISuggestion } = require('./ai_proxy');
+    const ai = await getAISuggestion(finding);
+    if (!ai) return res.json({ ok: false, error: 'No AI provider available or all failed.' });
+    res.json({ ok: true, ...ai });
+  } catch (err) {
+    res.json({ ok: false, error: err.message });
+  }
+});
+
+app.get('*', (_req, res) => {
+  const index = path.join(__dirname, '../dashboard/dist/index.html');
+  res.sendFile(index, (err) => {
+    if (err) res.status(404).send('Dashboard not built. Run: npm run build');
+  });
+});
+
+const server = http.createServer(app);
+const wss    = new WebSocketServer({ server, path: '/ws' });
+
+function broadcast(data) {
+  const msg = JSON.stringify(data);
+  wss.clients.forEach((c) => { if (c.readyState === 1) c.send(msg); });
+}
+
+function sessionSnapshot() {
+  return session.snapshot();
+}
+
+// Track bridge states so new dashboard clients get current status immediately
+const bridgeStatus = {
+  flutter: { connected: false, url: process.env.FLUTTER_VM_URL || 'ws://127.0.0.1:8181/ws' },
+  android: { connected: false },
+};
+
+wss.on('connection', (ws) => {
+  // Send current bridge status, detected device, and any active session to every
+  // new dashboard client right away.
+  ws.send(JSON.stringify({ _type: 'status', ...bridgeStatus, detected: detectedDevice }));
+  const snap = sessionSnapshot();
+  if (snap) ws.send(JSON.stringify({ _type: 'session', session: snap }));
+
+  ws.on('message', (raw) => {
+    try {
+      const event = JSON.parse(raw);
+      handleAppEvent(event);
+    } catch (_) {}
+  });
+});
+
+// Rebuild events fire once per widget build (can be hundreds/sec) — far too
+// noisy to stream raw. We tally them per widget and flush aggregated per-second
+// counts to the dashboard below. Everything else streams live.
+const _rebuildTally = new Map();
+
+// Every incoming app event: (1) feed the active module-test session,
+// (2) forward raw telemetry to the dashboard so the live panels update,
+// (3) run the passive rule engine and broadcast any finding for the junk feed.
+// (NO real-time AI — AI only runs in the module test flow.)
+function handleAppEvent(event) {
+  session.ingest(event);
+
+  if (event.event === 'rebuild') {
+    const w = event.widget || 'Unknown';
+    _rebuildTally.set(w, (_rebuildTally.get(w) || 0) + 1);
+  } else if (event.event) {
+    // frame / memory / api / error / state → straight to the live panels
+    broadcast(event);
+  }
+
+  const finding = engine.processEvent(event);
+  if (finding) {
+    finding.aiProcessed = true; // no per-finding AI; card renders rule text only
+    broadcast(finding);
+  }
+}
+
+// Flush aggregated rebuild counts once per second so the Rebuild Tracker shows
+// a true "rebuilds / second" rate instead of a flood of single events.
+setInterval(() => {
+  if (_rebuildTally.size === 0) return;
+  for (const [widget, count] of _rebuildTally) {
+    broadcast({
+      platform: 'flutter',
+      event: 'rebuild',
+      timestamp: Date.now(),
+      widget,
+      severity: count > 30 ? 'critical' : count > 10 ? 'high' : count > 5 ? 'medium' : 'low',
+      metric: { value: count, unit: 'rebuilds/s', budget: 10 },
+    });
+  }
+  _rebuildTally.clear();
+}, 1000).unref();
+
+flutterBridge.on('event',  (event) => handleAppEvent(event));
+flutterBridge.on('device', (d) => {
+  detectedDevice = d;
+  broadcast({ _type: 'status', ...bridgeStatus, detected: detectedDevice });
+  console.log(`  📱 Detected: ${d.os || '?'} / ${d.arch || '?'}`);
+});
+flutterBridge.on('status', (s) => {
+  bridgeStatus.flutter = { connected: s.connected, url: s.url };
+  broadcast({ _type: 'status', ...bridgeStatus, detected: detectedDevice });
+  if (s.connected) console.log('  📡 Flutter VM connected — data flowing to dashboard');
+});
+
+androidBridge.on('event',  (event) => handleAppEvent(event));
+androidBridge.on('status', (s) => {
+  bridgeStatus.android = { connected: s.connected };
+  broadcast({ _type: 'status', ...bridgeStatus, detected: detectedDevice });
+});
+
+// Android native live monitor (adb) — streams into the same pipeline.
+androidLive.on('event',  (event) => handleAppEvent(event));
+androidLive.on('status', (s) => {
+  bridgeStatus.android = { connected: s.connected };
+  broadcast({ _type: 'status', ...bridgeStatus, detected: detectedDevice });
+  if (s.connected) console.log('  📡 Android live monitor connected — data flowing to dashboard');
+});
+
+// Broadcast module-test session state changes to all dashboard clients.
+session.on('update', (snap) => broadcast({ _type: 'session', session: snap }));
+
+// ── Error handler ─────────────────────────────────────────────────────────────
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    console.error(`
+  ❌ Port ${PORT} is already in use.
+     Kill the existing process first:
+       lsof -ti :${PORT} | xargs kill
+     Or set a different port in .env:
+       DASHBOARD_PORT=7001
+`);
+  } else {
+    console.error('  ❌ Server error:', err.message);
+  }
+  process.exit(1);
+});
+
+// ── Startup ───────────────────────────────────────────────────────────────────
+async function main() {
+  printWelcome();
+  // "Ultron n0-beta initializing…" — warms the local model up front (idempotent)
+  // so it's ready by the time analysis needs it, and owns the AI startup output.
+  await initUltron();
+
+  const setup = await interactiveSetup();
+
+  server.listen(PORT, () => {
+    console.log('');
+    console.log(`  ${col(C.mag, '📊 Dashboard')} → ${col(C.cyan, `http://localhost:${PORT}`)}`);
+    if (setup && setup.mode === 'android-live') {
+      console.log('  ' + col(C.dim, '📡 Android live monitor starting — switch the dashboard platform toggle to Android.'));
+    } else if (!setup || setup.mode === 'flutter') {
+      console.log('  ' + col(C.dim, '⏳ Waiting for your app to connect…'));
+    }
+    console.log('');
+
+    flutterBridge.connect();
+    androidBridge.start();
+
+    // Start the Android native live monitor if the user chose it and picked an app.
+    if (setup && setup.mode === 'android-live' && setup.android) {
+      androidLive.start(setup.android.serial, setup.android.pkg).catch((e) =>
+        console.error('  ❌ Android live monitor failed:', e.message));
+    }
+
+    startCommandListener();
+  });
+}
+
+// ── Graceful shutdown (Ctrl+C / SIGTERM / "exit") ─────────────────────────────
+let shuttingDown = false;
+function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.log('\n  👋 Stopping ParityFix — shutting down local AI and server...');
+  try { androidLive.stop(); } catch (_) {}
+  stopLlamafile();
+  server.close(() => {
+    console.log('  ✅ Stopped. Bye!');
+    process.exit(0);
+  });
+  // Safety net if server.close() hangs on lingering sockets.
+  setTimeout(() => process.exit(0), 3000).unref();
+}
+process.on('SIGINT',  shutdown);
+process.on('SIGTERM', shutdown);
+
+main();