letfixit 0.1.0

package/server/ios_bridge.js

@@ -0,0 +1,181 @@
+// ── iOS bridge ────────────────────────────────────────────────────────────────
+// Connected-device performance capture for iOS — physical devices (xcrun
+// devicectl, Xcode 15+) and the Simulator (xcrun simctl). Render metrics come
+// from a per-iteration Instruments trace (`xcrun xctrace record`, Core Animation
+// template), which yields an FPS series we convert to frame-time percentiles +
+// jank.
+//
+// ⚠️  Unlike the Android path, this cannot be verified without a Mac + device/
+// simulator on hand. Commands follow the documented Xcode 15+ CLI; parsing is
+// defensive and degrades to null metrics (never throws) so the report still
+// renders. The xctrace export schema varies by Xcode version — parseFpsExport()
+// is the spot most likely to need tuning on real hardware.
+const { execFile, spawn } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function xc(args, { timeout = 30000 } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile('xcrun', args, { timeout, maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) return reject(new Error((stderr || err.message || '').toString().trim()));
+      resolve(stdout || '');
+    });
+  });
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function isAvailable() {
+  try { await xc(['xctrace', 'version']); return true; }
+  catch { try { await xc(['simctl', 'help']); return true; } catch { return false; } }
+}
+
+// ── Device discovery ───────────────────────────────────────────────────────────
+// `xctrace list devices` lists physical devices and simulators in one shot.
+function parseXctraceDevices(text) {
+  const out = [];
+  let section = null;
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (/^==\s*Devices\s*==/.test(line)) { section = 'device'; continue; }
+    if (/^==\s*Devices Offline\s*==/.test(line)) { section = 'offline'; continue; }
+    if (/^==\s*Simulators\s*==/.test(line)) { section = 'simulator'; continue; }
+    if (!line || section === 'offline' || section == null) continue;
+    // "iPhone 15 Pro (17.5) (ABCDEF01-2345-...)"  or  "My Mac (14.5) (UUID)"
+    const m = line.match(/^(.*?)\s*\(([\d.]+)\)\s*\(([0-9A-Fa-f-]{8,})\)\s*$/);
+    if (!m) continue;
+    const [, name, osVersion, id] = m;
+    // Under Devices, keep only real iOS-device UDIDs — "8hex-16hex" (A12+) or a
+    // 40-hex legacy id. The host Mac uses a standard 8-4-4-4-12 UUID, so this
+    // reliably drops it (name heuristics miss custom-named Macs like "…MacBook…").
+    if (section === 'device') {
+      const isIosUdid = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{16}$/.test(id) || /^[0-9A-Fa-f]{40}$/.test(id);
+      if (!isIosUdid) continue;
+    }
+    out.push({ platform: 'ios', id, model: name.trim(), osVersion, kind: section });
+  }
+  return out;
+}
+
+async function listDevices() {
+  try {
+    const text = await xc(['xctrace', 'list', 'devices']);
+    return parseXctraceDevices(text);
+  } catch { return []; }
+}
+
+async function deviceInfo(dev) {
+  return { brand: 'Apple', model: dev.model, os: 'iOS', osVersion: dev.osVersion || '', sdk: '', abi: 'arm64' };
+}
+
+async function isInstalled(dev, bundleId) {
+  try {
+    if (dev.kind === 'simulator') {
+      const out = await xc(['simctl', 'get_app_container', dev.id, bundleId]).catch(() => '');
+      return !!out.trim();
+    }
+    const out = await xc(['devicectl', 'device', 'info', 'apps', '--device', dev.id]).catch(() => '');
+    return out.includes(bundleId);
+  } catch { return true; } // don't block the run on an uncertain check
+}
+
+async function terminate(dev, bundleId) {
+  try {
+    if (dev.kind === 'simulator') await xc(['simctl', 'terminate', dev.id, bundleId]);
+    // devicectl has no clean force-stop for arbitrary apps; the next xctrace
+    // --launch starts a fresh instance, which is sufficient for iteration.
+  } catch (_) {}
+}
+
+// ── Capture (Instruments / xctrace) ─────────────────────────────────────────────
+// begin: launch the app under an Instruments recording. capture: stop, export,
+// and parse the FPS series → frame-time percentiles.
+async function beginCapture(dev, bundleId) {
+  const tracePath = path.join(os.tmpdir(), `parityfix-${Date.now()}.trace`);
+  // Boot the simulator if needed so the launch/record succeeds.
+  if (dev.kind === 'simulator') {
+    await xc(['simctl', 'bootstatus', dev.id, '-b']).catch(() => {});
+  }
+  // xctrace records AND launches the app; we stop it (SIGINT) when the user is done.
+  const args = ['xctrace', 'record', '--template', 'Core Animation',
+    '--device', dev.id, '--output', tracePath, '--launch', '--', bundleId];
+  const proc = spawn('xcrun', args, { stdio: 'ignore' });
+  const failed = new Promise((resolve) => proc.on('error', () => resolve(true)));
+  await Promise.race([sleep(1200), failed]); // let recording spin up
+  return { proc, tracePath };
+}
+
+async function endCapture(dev, bundleId, ctx) {
+  const empty = { jankPct: null, p50: null, p90: null, p99: null, fpsAvg: null, fpsMin: null, pssMb: null, cpuPct: null, gpuMemMb: null };
+  if (!ctx || !ctx.proc) return empty;
+  // Stop the recording gracefully so xctrace finalizes the .trace bundle.
+  try { ctx.proc.kill('SIGINT'); } catch (_) {}
+  await new Promise((resolve) => {
+    let done = false;
+    const finish = () => { if (!done) { done = true; resolve(); } };
+    ctx.proc.on('exit', finish);
+    setTimeout(finish, 12000); // don't hang if xctrace lingers
+  });
+
+  let fps = [];
+  try {
+    if (fs.existsSync(ctx.tracePath)) {
+      // Export the FPS-estimate table to XML, then pull the numbers.
+      const xml = await xc(['xctrace', 'export', '--input', ctx.tracePath,
+        '--xpath', '/trace-toc/run[@number="1"]/data/table[@schema="core-animation-fps-estimate"]']).catch(() => '');
+      fps = parseFpsExport(xml);
+    }
+  } catch (_) {}
+  try { fs.rmSync(ctx.tracePath, { recursive: true, force: true }); } catch (_) {}
+
+  if (fps.length === 0) return empty;
+  return { ...empty, ...fpsToMetrics(fps) };
+}
+
+// ── Pure parsers / math ──────────────────────────────────────────────────────
+// Pull FPS sample values out of an xctrace XML export. Schema differs across
+// Xcode versions, so we accept several shapes and fall back to any <fps>NN</fps>.
+function parseFpsExport(xml) {
+  if (!xml) return [];
+  const vals = [];
+  const re = /<fps[^>]*>([\d.]+)<\/fps>/gi;
+  let m;
+  while ((m = re.exec(xml))) { const v = parseFloat(m[1]); if (v > 0) vals.push(v); }
+  if (vals.length === 0) {
+    // Fallback: some exports emit fps inside a generic <value fmt="… fps">NN</value>.
+    const re2 = /<value[^>]*fps[^>]*>([\d.]+)<\/value>/gi;
+    while ((m = re2.exec(xml))) { const v = parseFloat(m[1]); if (v > 0) vals.push(v); }
+  }
+  return vals;
+}
+
+function percentile(sortedAsc, p) {
+  if (!sortedAsc.length) return 0;
+  const idx = Math.min(sortedAsc.length - 1, Math.floor((p / 100) * sortedAsc.length));
+  return sortedAsc[idx];
+}
+
+// Convert an FPS series to the common metric shape. Frame time = 1000/fps, so a
+// LOW fps percentile is a HIGH (worst) frame time — p90 frame time uses the 10th
+// fps percentile, etc. Jank = share of samples under 55fps.
+function fpsToMetrics(fps) {
+  const round = (n) => Math.round(n * 10) / 10;
+  const ascFps = [...fps].sort((a, b) => a - b);
+  const frameMs = (f) => (f > 0 ? 1000 / f : 0);
+  const jank = fps.filter((f) => f < 55).length;
+  return {
+    fpsAvg: round(fps.reduce((a, b) => a + b, 0) / fps.length),
+    fpsMin: round(Math.min(...fps)),
+    jankPct: round((jank / fps.length) * 100),
+    p50: round(frameMs(percentile(ascFps, 50))),
+    p90: round(frameMs(percentile(ascFps, 10))), // 10th-pctile fps → 90th-pctile frame time
+    p99: round(frameMs(percentile(ascFps, 1))),
+  };
+}
+
+module.exports = {
+  isAvailable, listDevices, deviceInfo, isInstalled,
+  beginCapture, endCapture, terminate,
+  parseXctraceDevices, parseFpsExport, fpsToMetrics,
+};

package/server/model_config.js

@@ -0,0 +1,54 @@
+// ── Ultron n0-beta — model identity & locations ──────────────────────────────
+// Single source of truth for the local model: its display name, on-disk path,
+// readiness check, and the encrypted-chunk manifest loader. Everything else
+// (setup script, server, ai_proxy) imports from here so the model can be
+// renamed / relocated in one place.
+const path = require('path');
+const fs = require('fs');
+
+const ROOT = path.join(__dirname, '..');
+
+const MODEL_NAME = 'Ultron n0-beta';
+const MODEL_ID   = 'ultron-n0-beta';
+const MODEL_DIR  = path.join(ROOT, 'bin', 'ultron');
+const MODEL_PATH = path.join(MODEL_DIR, `${MODEL_ID}.gguf`);
+const MIN_BYTES  = 100 * 1024 * 1024;   // real model is ~2.4 GB; guards against stubs
+
+// Max size per encrypted chunk. Smaller chunks host/mirror well, download in
+// parallel-friendly pieces, and resume cheaply. Override with PARITYFIX_CHUNK_MB.
+const CHUNK_MAX_BYTES = (parseInt(process.env.PARITYFIX_CHUNK_MB, 10) || 300) * 1024 * 1024;
+
+// Shown once after setup and available via /api/ai-status.
+const DISCLAIMER =
+  `${MODEL_NAME} is an initial Q4-quantized, fully-local model — fast and private, ` +
+  `but it can make mistakes or hallucinate. Treat its suggestions as hints: review ` +
+  `before applying, and add a cloud fallback key for higher-stakes analysis.`;
+
+function isReady() {
+  try { return fs.existsSync(MODEL_PATH) && fs.statSync(MODEL_PATH).size > MIN_BYTES; }
+  catch { return false; }
+}
+
+function sizeGB() {
+  try { return parseFloat((fs.statSync(MODEL_PATH).size / (1024 ** 3)).toFixed(2)); }
+  catch { return 0; }
+}
+
+// The encrypted-chunk manifest describes where the 3 chunks live and how to
+// decrypt/verify them. The real file is git-ignored (it carries Drive IDs); an
+// .example template is committed. Returns null if none is present.
+function loadManifest() {
+  const candidates = [
+    process.env.PARITYFIX_MODEL_MANIFEST,
+    path.join(ROOT, 'config', 'model.manifest.json'),
+  ].filter(Boolean);
+  for (const p of candidates) {
+    try { if (fs.existsSync(p)) return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) {}
+  }
+  return null;
+}
+
+module.exports = {
+  MODEL_NAME, MODEL_ID, MODEL_DIR, MODEL_PATH, MIN_BYTES, CHUNK_MAX_BYTES,
+  DISCLAIMER, isReady, sizeGB, loadManifest,
+};

package/server/report_template.js

@@ -0,0 +1,169 @@
+// ── ADB performance report (self-contained HTML) ─────────────────────────────
+// Produces a single HTML file with Chart.js line/bar charts, a score /100, AI
+// suggestions and a metrics table. Opened directly in any browser — no debug
+// mode, no dashboard required. Styled to the ParityFix magenta theme.
+
+const esc = (s) => String(s ?? '').replace(/[&<>"]/g, (c) => (
+  { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]
+));
+
+const GRADE_COLOR = { excellent: '#46d6a0', good: '#46d6a0', fair: '#f2c14e', poor: '#ff4d6d' };
+
+function buildReport({ app, module, deviceInfo, iterations, metrics, score, issues, suggestions, generatedAt }) {
+  const labels = iterations.map((_, i) => `Run ${i + 1}`);
+  const series = (k) => JSON.stringify(iterations.map((it) => it[k] ?? null));
+  const gradeColor = GRADE_COLOR[score.grade] || '#ff00e9';
+
+  const suggestionItems = suggestions.map((s) => `
+    <li>
+      <strong>${esc(s.title || 'Suggestion')}</strong>
+      ${s.detail ? `<p>${esc(s.detail)}</p>` : ''}
+      <span class="tag ${s.source === 'local' ? 'tag-ai' : 'tag-code'}">${s.source === 'local' ? '✦ AI' : '🧮 code'}</span>
+    </li>`).join('');
+
+  const issueItems = issues.length
+    ? issues.map((i) => `<li><span class="pill pill-${i.area}">${esc(i.area)}</span> ${esc(i.text)}</li>`).join('')
+    : '<li class="ok">No issues detected — every parameter within budget. 🎉</li>';
+
+  // Render null metrics as "n/a" (neutral) so a parameter the platform didn't
+  // capture isn't shown as a passing 0.
+  const na = (v, unit) => (v == null ? { text: 'n/a', cls: 'na' } : { text: `${v}${unit}`, cls: null });
+  const cell = (v, unit, bad) => { const c = na(v, unit); return { text: c.text, cls: c.cls || (bad ? 'bad' : 'good') }; };
+  const metricRows = [
+    ['Frame jank', cell(metrics.jankPct, '%', metrics.jankPct > 5)],
+    ['p50 frame time', cell(metrics.p50, ' ms', false)],
+    ['p90 frame time', cell(metrics.p90, ' ms', metrics.p90 > 16.6)],
+    ['p99 frame time', cell(metrics.p99, ' ms', metrics.p99 > 40)],
+    ['Peak memory (PSS)', cell(metrics.peakMemMb, ' MB', metrics.peakMemMb > 250)],
+    ['Memory growth', cell(metrics.memGrowthMb, ' MB', metrics.memGrowthMb > 10)],
+    ['Avg CPU', cell(metrics.cpuPct, '%', metrics.cpuPct > 40)],
+    ...(metrics.gpuMemMb != null ? [['Avg GPU memory', cell(metrics.gpuMemMb, ' MB', false)]] : []),
+  ].map(([k, c]) => `<tr><td>${k}</td><td class="${c.cls}">${c.text}</td></tr>`).join('');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>ParityFix Report — ${esc(app)} · ${esc(module)}</title>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
+<style>
+  :root{--bg:#18171f;--surface:#201f2a;--surface2:#2a2836;--border:#3a3848;
+    --text:#aca7cb;--hi:#fff;--muted:#8b86a6;--accent:#ff00e9;--sage:#46d6a0;--warn:#f2c14e;--danger:#ff4d6d;--high:#ff9457}
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{background:var(--bg);color:var(--text);font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Inter,sans-serif;padding:28px;line-height:1.5}
+  .wrap{max-width:1000px;margin:0 auto}
+  header{display:flex;align-items:center;gap:16px;margin-bottom:6px}
+  .logo{width:34px;height:34px;border-radius:9px;background:linear-gradient(135deg,#ff00e9,#ff00d5);display:flex;align-items:center;justify-content:center;font-weight:800;color:#fff}
+  h1{font-size:20px;color:var(--hi);font-weight:800}
+  h1 .fx{color:var(--accent)}
+  .sub{color:var(--muted);font-size:13px;margin-bottom:22px}
+  .grid{display:grid;grid-template-columns:220px 1fr;gap:18px;margin-bottom:24px}
+  .score-card{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:22px;text-align:center}
+  .score-num{font-size:56px;font-weight:800;line-height:1;color:${gradeColor}}
+  .score-grade{text-transform:uppercase;letter-spacing:.08em;font-size:12px;font-weight:700;color:${gradeColor};margin-top:6px}
+  .subscores{display:flex;flex-direction:column;gap:8px;margin-top:16px;text-align:left}
+  .subscore{display:flex;justify-content:space-between;font-size:12px}
+  .bar{height:6px;border-radius:3px;background:var(--surface2);margin-top:3px;overflow:hidden}
+  .bar > span{display:block;height:100%;border-radius:3px}
+  .panel{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:18px}
+  .panel h2{font-size:12px;text-transform:uppercase;letter-spacing:.07em;color:var(--muted);margin-bottom:14px;font-weight:700}
+  canvas{max-height:230px}
+  .charts{display:grid;grid-template-columns:1fr 1fr;gap:18px;margin-bottom:24px}
+  ul{list-style:none}
+  .issues li,.suggest li{padding:10px 0;border-bottom:1px solid var(--border);font-size:13px}
+  .suggest li strong{color:var(--hi);display:block;margin-bottom:2px}
+  .suggest li p{color:var(--text);font-size:12.5px;margin-top:2px}
+  .tag{display:inline-block;font-size:10px;font-weight:700;padding:2px 8px;border-radius:999px;margin-top:6px}
+  .tag-ai{background:rgba(255,0,233,.16);color:#ff66f1}
+  .tag-code{background:var(--surface2);color:var(--muted)}
+  .pill{display:inline-block;font-size:10px;font-weight:700;padding:2px 8px;border-radius:999px;text-transform:uppercase;margin-right:6px}
+  .pill-render{background:rgba(255,148,87,.16);color:var(--high)}
+  .pill-memory{background:rgba(255,77,109,.16);color:var(--danger)}
+  .pill-cpu{background:rgba(242,193,78,.16);color:var(--warn)}
+  .ok{color:var(--sage)}
+  table{width:100%;border-collapse:collapse;font-size:13px}
+  td{padding:8px 10px;border-bottom:1px solid var(--border)}
+  td:last-child{text-align:right;font-variant-numeric:tabular-nums;font-weight:600}
+  .good{color:var(--sage)} .bad{color:var(--danger)} .na{color:var(--muted)}
+  .two{display:grid;grid-template-columns:1fr 1fr;gap:18px;margin-bottom:24px}
+  footer{color:var(--muted);font-size:11px;margin-top:26px;padding-top:16px;border-top:1px solid var(--border)}
+  @media(max-width:760px){.grid,.charts,.two{grid-template-columns:1fr}}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header>
+    <div class="logo">P</div>
+    <div>
+      <h1>Parity<span class="fx">Fix</span> — Performance Report</h1>
+    </div>
+  </header>
+  <div class="sub">
+    App <strong style="color:var(--hi)">${esc(app)}</strong> · Module <strong style="color:var(--hi)">${esc(module)}</strong>
+    · ${esc(deviceInfo.brand)} ${esc(deviceInfo.model)}, ${esc(deviceInfo.os)} ${esc(deviceInfo.osVersion)} (${esc(deviceInfo.abi)})
+    · ${iterations.length} iterations
+  </div>
+
+  <div class="grid">
+    <div class="score-card">
+      <div class="score-num">${score.overall}</div>
+      <div style="color:var(--muted);font-size:12px">out of 100</div>
+      <div class="score-grade">${esc(score.grade)}</div>
+      <div class="subscores">
+        ${[['Render', score.render, 'var(--high)'], ['Memory', score.memory, 'var(--danger)'], ['CPU', score.cpu, 'var(--warn)']]
+          .map(([k, v, c]) => v == null
+            ? `<div><div class="subscore"><span>${k}</span><span class="na">n/a</span></div><div class="bar"></div></div>`
+            : `<div><div class="subscore"><span>${k}</span><span>${v}</span></div><div class="bar"><span style="width:${v}%;background:${c}"></span></div></div>`).join('')}
+      </div>
+    </div>
+    <div class="panel issues">
+      <h2>Detected issues</h2>
+      <ul>${issueItems}</ul>
+    </div>
+  </div>
+
+  <div class="charts">
+    <div class="panel"><h2>Frame time per iteration (ms)</h2><canvas id="frameChart"></canvas></div>
+    <div class="panel"><h2>Jank % per iteration</h2><canvas id="jankChart"></canvas></div>
+    <div class="panel"><h2>Memory PSS per iteration (MB)</h2><canvas id="memChart"></canvas></div>
+    <div class="panel"><h2>CPU % per iteration</h2><canvas id="cpuChart"></canvas></div>
+  </div>
+
+  <div class="two">
+    <div class="panel suggest">
+      <h2>Suggested improvements</h2>
+      <ul>${suggestionItems}</ul>
+    </div>
+    <div class="panel">
+      <h2>Aggregated metrics</h2>
+      <table><tbody>${metricRows}</tbody></table>
+    </div>
+  </div>
+
+  <footer>Generated by ParityFix — Local AI-Powered Performance Analyzer · ${esc(generatedAt)}</footer>
+</div>
+
+<script>
+  const labels = ${JSON.stringify(labels)};
+  const grid = 'rgba(172,167,203,.12)', tick = '#8b86a6';
+  const base = (extra={}) => ({responsive:true,plugins:{legend:{labels:{color:'#aca7cb',boxWidth:12}}},
+    scales:{x:{grid:{color:grid},ticks:{color:tick}},y:{grid:{color:grid},ticks:{color:tick},beginAtZero:true}},...extra});
+  const line = (id,datasets)=>new Chart(document.getElementById(id),{type:'line',data:{labels,datasets},options:base()});
+  const bar = (id,label,data,color)=>new Chart(document.getElementById(id),{type:'bar',
+    data:{labels,datasets:[{label,data,backgroundColor:color}]},options:base({plugins:{legend:{display:false}}})});
+
+  line('frameChart',[
+    {label:'p50',data:${series('p50')},borderColor:'#46d6a0',backgroundColor:'#46d6a0',tension:.3},
+    {label:'p90',data:${series('p90')},borderColor:'#ff9457',backgroundColor:'#ff9457',tension:.3},
+    {label:'p99',data:${series('p99')},borderColor:'#ff4d6d',backgroundColor:'#ff4d6d',tension:.3},
+  ]);
+  bar('jankChart','Jank %',${series('jankPct')},'#ff00e9');
+  line('memChart',[{label:'PSS (MB)',data:${series('pssMb')},borderColor:'#ff00e9',backgroundColor:'rgba(255,0,233,.15)',fill:true,tension:.3}]);
+  bar('cpuChart','CPU %',${series('cpuPct')},'#f2c14e');
+</script>
+</body>
+</html>`;
+}
+
+module.exports = { buildReport };