@progen-labs/spectra 0.0.0-stage → 0.1.1

package/server/api.js

@@ -0,0 +1,292 @@
+/**
+ * The Spectra backend API, framework-agnostic so it can be mounted by either
+ * the Vite dev plugin (server/plugin.js) or the standalone dashboard server
+ * (server/dashboard.js). `handle(req, res, next)` is Connect-style and expects
+ * `req.url` to be relative to the API root (the `/api` prefix already removed).
+ *
+ *   GET  /status            connection, tabs, recording state, probe info
+ *   POST /connect           {mode:'launch'|'attach', url?, browserURL?, headless?}
+ *   POST /disconnect        POST /select-page {id}
+ *   POST /navigate {url}    POST /reload
+ *   POST /record/start      {mode, cpuThrottle?, saveTrace?, settleMs?}
+ *   POST /record/stop
+ *   GET  /reports           GET/DELETE /reports/:id
+ *   POST /reports/:id/trace write the raw trace (GET downloads it)
+ *   GET  /reports/:id/page.jpg  screenshot behind the report's page map
+ *   GET  /evaluations       GET /evaluations/:id   golden-path aggregates
+ *   GET  /source?path=      a source file (read-only, inside known roots)
+ *   GET  /git/commit?rev=   author/subject/date of HEAD or a commit hash
+ *   POST /compare/pdf       {comparison, kind} -> application/pdf
+ *   GET  /events            Server-Sent Events: state + new reports
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { COMPARE_VERSION } from '../shared/compare.js';
+import {
+  DEFAULT_TARGET_URL,
+  FRONTEND_ROOT,
+  REPORTS_DIR,
+  SOURCE_ROOTS,
+  TARGET_NAME,
+} from './config.js';
+import { gitInfo, isValidRev } from './git.js';
+import { pdfFileName, renderComparisonPdf } from './pdf/render.js';
+import {
+  PerfSession,
+  deleteReport,
+  listReports,
+  pageImageFile,
+  readReport,
+} from './recorder.js';
+
+const MAX_SOURCE_BYTES = 1024 * 1024;
+
+function send(res, status, body) {
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'application/json');
+  res.setHeader('Cache-Control', 'no-store');
+  res.end(JSON.stringify(body));
+}
+
+async function readBody(req) {
+  const chunks = [];
+  for await (const c of req) chunks.push(c);
+  const text = Buffer.concat(chunks).toString('utf8');
+  return text ? JSON.parse(text) : {};
+}
+
+function readSource(rel) {
+  if (
+    !rel ||
+    rel.includes('\0') ||
+    path.isAbsolute(rel) ||
+    rel.split(/[\\/]/).includes('..')
+  )
+    return null;
+  for (const root of SOURCE_ROOTS) {
+    const abs = path.join(root, rel);
+    let real;
+    try {
+      real = fs.realpathSync(abs);
+    } catch {
+      continue;
+    }
+    if (
+      !real.startsWith(fs.realpathSync(root) + path.sep) ||
+      !fs.statSync(real).isFile()
+    )
+      continue;
+    const size = fs.statSync(real).size;
+    const fd = fs.openSync(real, 'r');
+    try {
+      const buf = Buffer.alloc(Math.min(size, MAX_SOURCE_BYTES));
+      fs.readSync(fd, buf, 0, buf.length, 0);
+      return {
+        path: rel,
+        root,
+        absolutePath: real,
+        size,
+        truncated: size > MAX_SOURCE_BYTES,
+        content: buf.toString('utf8'),
+      };
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  return null;
+}
+
+/** List saved golden-path evaluation aggregates (newest first). */
+function listEvaluations() {
+  let files = [];
+  try {
+    files = fs.readdirSync(REPORTS_DIR);
+  } catch {
+    return [];
+  }
+  return files
+    .filter(f => f.startsWith('evaluation-') && f.endsWith('.json'))
+    .sort()
+    .reverse()
+    .map(f => {
+      try {
+        const data = JSON.parse(
+          fs.readFileSync(path.join(REPORTS_DIR, f), 'utf8'),
+        );
+        return {
+          id: data.id,
+          createdAt: data.createdAt,
+          target: data.target,
+          url: data.url,
+          pathCount: Array.isArray(data.paths) ? data.paths.length : 0,
+          passed: Array.isArray(data.paths)
+            ? data.paths.filter(p => p.ok).length
+            : 0,
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function readEvaluation(id) {
+  if (!/^evaluation-[\w-]+$/.test(id)) return null;
+  try {
+    return JSON.parse(
+      fs.readFileSync(path.join(REPORTS_DIR, `${id}.json`), 'utf8'),
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Routes that act on the session and then answer with its fresh status. */
+const ACTIONS = {
+  'POST /connect': (session, body) => session.connect(body),
+  'POST /disconnect': session => session.disconnect(),
+  'POST /select-page': (session, body) => session.selectPage(body.id),
+  'POST /navigate': (session, body) => session.navigate(body.url, body.signIn),
+  'POST /reload': session => session.reload(),
+  'POST /record/start': (session, body) => session.start(body),
+};
+
+/**
+ * Build a Spectra API instance: its own PerfSession, an SSE client set, a
+ * Connect-style `handle`, and a `dispose` for shutdown.
+ */
+export function createApi() {
+  const session = new PerfSession();
+  const clients = new Set();
+  const broadcast = (event, data) => {
+    const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const res of clients) res.write(payload);
+  };
+  session.on('state', s => broadcast('state', s));
+  session.on('report', r => broadcast('report', r));
+
+  async function handle(req, res, next) {
+    const url = new URL(req.url, 'http://localhost');
+    const route = `${req.method} ${url.pathname}`;
+    try {
+      if (route === 'GET /status')
+        return send(res, 200, {
+          ...(await session.status()),
+          defaultUrl: DEFAULT_TARGET_URL,
+          defaultName: TARGET_NAME,
+        });
+      if (route === 'POST /record/stop') {
+        const report = await session.stop();
+        return send(res, 200, { id: report.id });
+      }
+      if (route in ACTIONS) {
+        await ACTIONS[route](session, await readBody(req));
+        return send(res, 200, await session.status());
+      }
+      if (route === 'GET /reports') return send(res, 200, listReports());
+      if (route === 'GET /evaluations')
+        return send(res, 200, listEvaluations());
+      const evalRoute = /^\/evaluations\/(evaluation-[\w-]+)$/.exec(url.pathname);
+      if (evalRoute) {
+        const data = readEvaluation(evalRoute[1]);
+        return data
+          ? send(res, 200, data)
+          : send(res, 404, { error: 'No such evaluation' });
+      }
+      const traceRoute = /^\/reports\/([\w-]+)\/trace$/.exec(url.pathname);
+      if (traceRoute) {
+        const [, id] = traceRoute;
+        const { path: file, size } = session.writeTrace(id);
+        if (req.method === 'POST')
+          return send(res, 200, { ok: true, path: file, size });
+        res.writeHead(200, {
+          'Content-Type': 'application/json',
+          'Content-Length': size,
+          'Content-Disposition': `attachment; filename="${id}.trace.json"`,
+        });
+        return fs.createReadStream(file).pipe(res);
+      }
+      const pageRoute = /^\/reports\/([\w-]+)\/page\.jpg$/.exec(url.pathname);
+      if (pageRoute) {
+        const file = pageImageFile(pageRoute[1]);
+        if (!fs.existsSync(file))
+          return send(res, 404, { error: 'No page image for this report' });
+        res.writeHead(200, {
+          'Content-Type': 'image/jpeg',
+          'Content-Length': fs.statSync(file).size,
+        });
+        return fs.createReadStream(file).pipe(res);
+      }
+      if (url.pathname.startsWith('/reports/')) {
+        const id = decodeURIComponent(url.pathname.slice('/reports/'.length));
+        if (req.method === 'DELETE')
+          return send(res, 200, (deleteReport(id), { ok: true }));
+        const report = readReport(id);
+        return report
+          ? send(res, 200, report)
+          : send(res, 404, { error: 'No such report' });
+      }
+      if (route === 'GET /git/commit') {
+        const rev = url.searchParams.get('rev') || 'HEAD';
+        const info = isValidRev(rev) ? gitInfo(FRONTEND_ROOT, rev) : null;
+        return info
+          ? send(res, 200, info)
+          : send(res, 404, {
+              error: `No commit “${rev}” in this repository (use a commit hash).`,
+            });
+      }
+      if (route === 'POST /compare/pdf') {
+        const { comparison, kind } = await readBody(req);
+        if (
+          comparison?.version !== COMPARE_VERSION ||
+          !Array.isArray(comparison.metrics)
+        ) {
+          return send(res, 400, {
+            error: 'Not a comparison produced by this tool.',
+          });
+        }
+        const type = kind === 'detailed' ? 'detailed' : 'summary';
+        const pdf = await renderComparisonPdf(comparison, type);
+        res.writeHead(200, {
+          'Content-Type': 'application/pdf',
+          'Content-Length': pdf.length,
+          'Content-Disposition': `attachment; filename="${pdfFileName(comparison, type)}"`,
+          'Cache-Control': 'no-store',
+        });
+        return res.end(pdf);
+      }
+      if (route === 'GET /source') {
+        const file = readSource(url.searchParams.get('path'));
+        return file
+          ? send(res, 200, file)
+          : send(res, 404, {
+              error: 'Source file not found in the known roots',
+            });
+      }
+      if (route === 'GET /events') {
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache, no-transform',
+          Connection: 'keep-alive',
+        });
+        res.write(`event: hello\ndata: {}\n\n`);
+        clients.add(res);
+        const heartbeat = setInterval(() => res.write(': ping\n\n'), 25_000);
+        req.on('close', () => {
+          clearInterval(heartbeat);
+          clients.delete(res);
+        });
+        return undefined;
+      }
+    } catch (err) {
+      return send(res, 500, { error: err.message });
+    }
+    return next ? next() : send(res, 404, { error: 'Not found' });
+  }
+
+  async function dispose() {
+    await session.disconnect().catch(() => {});
+  }
+
+  return { session, handle, dispose };
+}

package/server/chrome.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import puppeteer from 'puppeteer-core';
+import { CHROME_PROFILE_DIR } from './config.js';
+
+const CANDIDATES = {
+  darwin: [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  ],
+  linux: [
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+  ],
+  win32: [
+    `${process.env.PROGRAMFILES}\\Google\\Chrome\\Application\\chrome.exe`,
+    `${process.env['PROGRAMFILES(X86)']}\\Google\\Chrome\\Application\\chrome.exe`,
+    `${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
+  ],
+};
+
+export function findChrome() {
+  if (process.env.CHROME_PATH) return process.env.CHROME_PATH;
+  return (
+    (CANDIDATES[os.platform()] || []).find(p => p && fs.existsSync(p)) || null
+  );
+}
+
+/**
+ * Starts a dedicated Chrome. Its profile lives in .chrome-profile/ so logins
+ * (session cookies) survive between sessions, and it is separate from
+ * your everyday browser profile.
+ */
+export async function launchChrome({ headless = false } = {}) {
+  const executablePath = findChrome();
+  if (!executablePath) {
+    throw new Error(
+      'Chrome was not found. Set CHROME_PATH to its executable, or start Chrome with --remote-debugging-port=9222 and use “Attach”.',
+    );
+  }
+  fs.mkdirSync(CHROME_PROFILE_DIR, { recursive: true });
+  const options = {
+    executablePath,
+    headless: headless ? 'new' : false,
+    userDataDir: CHROME_PROFILE_DIR,
+    defaultViewport: null,
+    ignoreDefaultArgs: ['--enable-automation'],
+    args: [
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--window-size=1600,1000',
+      '--enable-precise-memory-info',
+      '--disable-background-timer-throttling',
+      '--disable-renderer-backgrounding',
+      ...(process.env.PERF_CHROME_ARGS
+        ? process.env.PERF_CHROME_ARGS.split(' ')
+        : []),
+    ],
+  };
+  try {
+    return await puppeteer.launch(options);
+  } catch (err) {
+    // A second Chrome on the same profile (e.g. the UI's window while running the CLI) cannot start.
+    const locked = ['SingletonLock', 'lockfile'].some(f =>
+      fs.existsSync(path.join(CHROME_PROFILE_DIR, f)),
+    );
+    throw new Error(
+      locked
+        ? `Chrome could not start because another Chrome is already using the profile ${CHROME_PROFILE_DIR}. Close that window (Close Chrome in the UI), or use a separate profile: PERF_CHROME_PROFILE_DIR=/tmp/perf-chrome-2.`
+        : `Chrome failed to start (${err.message}). Check CHROME_PATH (${executablePath}).`,
+    );
+  }
+}
+
+export function attachChrome(browserURL) {
+  return puppeteer.connect({ browserURL, defaultViewport: null });
+}

package/server/cli.js

@@ -0,0 +1,94 @@
+/**
+ * Headless / scripted profiling:
+ *
+ *   npm run profile -- --url http://localhost:3000/ --mode load
+ *   npm run profile -- --url http://localhost:5188/ --duration 8 --throttle 4
+ *   npm run profile -- --url ... --scenario ./scenario.mjs   # export default async page => {…}
+ *
+ * The report is saved in reports/ and can be opened in the UI (npm run dev).
+ */
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { PerfSession, readReport } from './recorder.js';
+import { REPORTS_DIR } from './config.js';
+
+const args = process.argv.slice(2);
+const opt = (name, fallback) => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? fallback : (args[i + 1] ?? true);
+};
+const flag = name => args.includes(`--${name}`);
+
+const url = opt('url');
+if (!url || flag('help')) {
+  console.log(
+    'usage: npm run profile -- --url <page> [--mode live|load] [--duration seconds] [--throttle 4] [--scenario file.mjs] [--headed] [--save-trace] [--sign-in "http://host/login/?redirect={url}"]',
+  );
+  process.exit(url ? 0 : 1);
+}
+const mode = opt('mode', 'live');
+const duration = Number(opt('duration', 8)) * 1000;
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+const session = new PerfSession();
+try {
+  await session.connect({
+    mode: 'launch',
+    url,
+    headless: !flag('headed'),
+    signIn: opt('sign-in'),
+  });
+  await sleep(1500);
+  await session.reload(); // make sure the probe was installed before the app loaded
+  await sleep(1000);
+  await session.start({
+    mode,
+    cpuThrottle: Number(opt('throttle', 1)),
+    saveTrace: flag('save-trace'),
+  });
+  let report;
+  if (mode === 'live') {
+    const scenario = opt('scenario');
+    if (scenario) {
+      const mod = await import(pathToFileURL(path.resolve(scenario)).href);
+      await mod.default(session.page);
+    } else await sleep(duration);
+    report = await session.stop();
+  } else {
+    // Page-load recordings stop themselves shortly after the load event.
+    const id = await new Promise((resolve, reject) => {
+      session.once('report', r => resolve(r.id));
+      session.on('state', s => s.error && reject(new Error(s.error)));
+    });
+    report = readReport(id);
+  }
+  console.log(
+    `\nReport ${report.id} (${report.meta.attribution}, ${report.meta.sampleCount} samples)`,
+  );
+  console.log(
+    `TBT ${report.vitals.tbtMs}ms · long tasks ${report.vitals.longTaskCount} · CLS ${report.vitals.cls} · FCP ${report.vitals.fcpMs}ms · LCP ${report.vitals.lcpMs}ms · forced layouts ${report.totals.forcedLayoutCount}`,
+  );
+  console.log('\nCulprits:');
+  for (const f of report.findings.slice(0, 15)) {
+    console.log(` [${f.severity}] (${f.category}) ${f.title}`);
+    for (const c of f.culprits) {
+      const line = c.line
+        ? `:${c.lineKind === 'located' ? '≈' : ''}${c.line}`
+        : '';
+      console.log(
+        `      ↳ ${c.fn}()  ${c.file || 'unknown'}${line}${c.ms ? `  ${c.ms}ms` : ''}${c.note ? `  (${c.note})` : ''}`,
+      );
+    }
+  }
+  // When launched by the installed CLI the bin sets PERF_REPORTS_DIR; in a dev
+  // checkout it is unset. Tailor the "how to view it" hint to each.
+  const installed = !!process.env.PERF_REPORTS_DIR;
+  console.log(
+    `\nSaved ${path.join(REPORTS_DIR, report.id)}.json — view it with: ${
+      installed ? 'spectra dashboard' : 'npm run dev'
+    }`,
+  );
+} finally {
+  await session.disconnect();
+}
+process.exit(0);

package/server/config.js

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { detectFramework } from './framework.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export const TOOL_ROOT = path.resolve(here, '..');
+
+/** Frontend project root. Prefer `PERF_FRONTEND_DIR`, fall back to legacy var. */
+export const FRONTEND_ROOT = path.resolve(
+  process.env.PERF_FRONTEND_DIR || process.env.FRONTEND_DIR || path.join(TOOL_ROOT, '../..'),
+);
+
+/** Where source files are looked up when showing a file (first match wins). */
+export const SOURCE_ROOTS = [
+  FRONTEND_ROOT,
+  path.join(TOOL_ROOT, 'fixtures/demo-app'),
+];
+
+export const REPORTS_DIR =
+  process.env.PERF_REPORTS_DIR || path.join(TOOL_ROOT, 'reports');
+
+/**
+ * Dedicated Chrome profile so logins survive between runs. Keyed per profiled
+ * project and kept in the OS temp dir — never inside the installed package
+ * (node_modules) or committed into the user's repo.
+ */
+const profileKey = crypto
+  .createHash('sha1')
+  .update(FRONTEND_ROOT)
+  .digest('hex')
+  .slice(0, 8);
+export const CHROME_PROFILE_DIR =
+  process.env.PERF_CHROME_PROFILE_DIR ||
+  path.join(os.tmpdir(), 'spectra-chrome', `${path.basename(FRONTEND_ROOT)}-${profileKey}`);
+
+export const DEFAULT_TARGET_URL =
+  process.env.PERF_TARGET_URL || 'http://localhost:3000/';
+
+/** Human-friendly name for the profiled target (used in the UI and PDF). */
+let inferredName = 'target-frontend';
+try {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(FRONTEND_ROOT, 'package.json'), 'utf8'),
+  );
+  if (pkg && pkg.name) inferredName = pkg.name;
+} catch {
+  // ignore
+}
+
+export const TARGET_NAME =
+  process.env.PERF_TARGET_NAME || process.env.FRONTEND_NAME || inferredName;
+
+/** Detect framework/bundler info for the frontend root */
+export const FRAMEWORK = detectFramework(FRONTEND_ROOT);
+

package/server/dashboard.js

@@ -0,0 +1,154 @@
+/**
+ * Standalone dashboard server for installed Spectra: serves the prebuilt UI
+ * (dist/) and mounts the same backend API as the Vite dev plugin, so an npm
+ * consumer gets the full dashboard — culprits, PDF export, commit compare,
+ * live recording — with no dev toolchain.
+ *
+ * Run directly (node server/dashboard.js [--port N] [--open]) or import
+ * startDashboard().
+ */
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createApi } from './api.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(here, '..');
+const DIST = process.env.SPECTRA_DASHBOARD_DIST || path.join(PKG_ROOT, 'dist');
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json',
+  '.map': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+};
+
+function serveStatic(res, pathname) {
+  const rel = decodeURIComponent(pathname).replace(/^\/+/, '');
+  const safe = path.normalize(rel);
+  if (safe.startsWith('..') || path.isAbsolute(safe)) {
+    res.statusCode = 403;
+    return res.end('Forbidden');
+  }
+  let file = safe ? path.join(DIST, safe) : path.join(DIST, 'index.html');
+  // SPA fallback: unknown path with no file extension serves the app shell.
+  if (!fs.existsSync(file) || fs.statSync(file).isDirectory()) {
+    file = path.join(DIST, 'index.html');
+  }
+  if (!fs.existsSync(file)) {
+    res.statusCode = 404;
+    return res.end('Not found');
+  }
+  const ext = path.extname(file).toLowerCase();
+  res.writeHead(200, {
+    'Content-Type': MIME[ext] || 'application/octet-stream',
+    'Cache-Control': ext === '.html' ? 'no-store' : 'public, max-age=3600',
+  });
+  fs.createReadStream(file).pipe(res);
+}
+
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    const onError = err => {
+      server.removeListener('error', onError);
+      reject(err);
+    };
+    server.once('error', onError);
+    server.listen(port, host, () => {
+      server.removeListener('error', onError);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Start the dashboard. Tries `port`, then a few above it if busy.
+ * @returns {Promise<{ url:string, port:number, close:()=>Promise<void> }>}
+ */
+export async function startDashboard({ port = 4321, host = '127.0.0.1' } = {}) {
+  if (!fs.existsSync(path.join(DIST, 'index.html'))) {
+    throw new Error(
+      `dashboard assets not found at ${DIST}. In a dev checkout, build them first with "npm run build".`,
+    );
+  }
+  const api = createApi();
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, 'http://localhost');
+    if (u.pathname === '/api' || u.pathname.startsWith('/api/')) {
+      req.url = req.url.slice('/api'.length) || '/';
+      return api.handle(req, res, null);
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.statusCode = 405;
+      return res.end('Method not allowed');
+    }
+    serveStatic(res, u.pathname);
+  });
+
+  let chosen = port;
+  for (let i = 0; i < 10; i++) {
+    try {
+      await listen(server, chosen, host);
+      break;
+    } catch (err) {
+      if (err.code === 'EADDRINUSE' && i < 9) {
+        chosen += 1;
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  const url = `http://localhost:${chosen}`;
+  const close = async () => {
+    await api.dispose();
+    await new Promise(r => server.close(r));
+  };
+  return { url, port: chosen, close };
+}
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'darwin'
+      ? 'open'
+      : process.platform === 'win32'
+        ? 'start'
+        : 'xdg-open';
+  try {
+    spawn(cmd, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+  } catch {
+    /* best effort */
+  }
+}
+
+// Direct invocation: node server/dashboard.js [--port N] [--open]
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  const args = process.argv.slice(2);
+  const pi = args.indexOf('--port');
+  const port = pi !== -1 ? Number(args[pi + 1]) : Number(process.env.PORT) || 4321;
+  const { url, close } = await startDashboard({ port });
+  console.log(`\nSpectra dashboard running at ${url}`);
+  console.log('Reports and evaluations from this project are listed there.');
+  console.log('Press Ctrl+C to stop.\n');
+  if (args.includes('--open')) openBrowser(url);
+  const shutdown = async () => {
+    await close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}