pageproof 0.1.0

package/src/lifecycle.js

@@ -0,0 +1,445 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import chokidar from 'chokidar';
+import { materializeAssets, resolveAssets, watchedAssetPaths } from './assets.js';
+import { buildWithPandoc, writeErrorPage } from './pandoc.js';
+import { commandExists, delay, isWsl, writeJson } from './util.js';
+import { createPreviewServer } from './server.js';
+
+const mediaExtensions = new Set([
+  '.svg',
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.pdf',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.otf'
+]);
+
+export async function runSession(options) {
+  const sourceFile = path.resolve(options.file);
+  if (!commandExists('pandoc')) throw new Error('Missing required program: pandoc');
+  if (isWsl() && !commandExists('cmd.exe')) throw new Error('Missing required program: cmd.exe');
+
+  const sourceDir = path.dirname(sourceFile);
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mdpreview-'));
+  const debug = Boolean(options.debug);
+  const logFile = options.logFile ?? (debug ? path.join(tempDir, 'session.log') : undefined);
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const state = createSessionState({ sourceFile, logFile });
+  const reporter = createReporter({ sourceFile, debug, logFile, stdout });
+  const handleBrowserLog = createBrowserLogHandler({
+    tempDir,
+    logFile,
+    debugBrowser: debug,
+    onEntry: (entry) => {
+      if (entry.buildId === state.buildId) state.browserReport = entry;
+      if (!state.firstBrowserWarningReported && (entry.ok === false || entry.errors?.length)) {
+        state.firstBrowserWarningReported = true;
+        stdout.write(`Warning: ${entry.errors?.length || 1} browser errors while rendering\n`);
+      }
+    }
+  });
+  let shuttingDown = false;
+  let started = false;
+  let watcher;
+  let serverHandle;
+  let noClientTimer;
+  let closeGraceTimer;
+  let cssFiles = [];
+
+  const cleanup = async (exitCode = 0, cleanupOptions = {}) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    clearTimeout(noClientTimer);
+    clearTimeout(closeGraceTimer);
+    await serverHandle?.close().catch(() => {});
+    await watcher?.close().catch(() => {});
+    if (started) {
+      const reason = cleanupOptions.reason ?? (exitCode === 0 ? 'browser closed' : 'error');
+      if (reason === 'browser closed' || reason === 'interrupted') stdout.write(`Stopped: ${reason}\n`);
+      await writeServerLog(logFile, { type: 'shutdown', reason });
+    }
+    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    if (!options.noExit && !cleanupOptions.noExit && cleanupOptions.exit !== false) process.exit(exitCode);
+  };
+
+  const build = createBuildScheduler(async () => {
+    const buildId = ++state.buildId;
+    const startedAt = new Date();
+    state.lastBuildStartedAt = startedAt.toISOString();
+    state.pandocSpawnError = undefined;
+    state.browserReport = undefined;
+    await writeServerLog(logFile, {
+      type: 'build-started',
+      buildId,
+      sourceFile,
+      startedAt: state.lastBuildStartedAt
+    });
+    let result;
+    try {
+      result = await buildWithPandoc({
+        sourceFile,
+        tempDir,
+        cssFiles,
+        log: null,
+        debugBrowser: debug,
+        buildId
+      });
+    } catch (error) {
+      state.pandocSpawnError = error?.message || String(error);
+      result = {
+        ok: false,
+        diagnostics: '',
+        stderr: ''
+      };
+      await writePandocFailurePage({ tempDir, sourceFile, cssFiles, debug, buildId, error: state.pandocSpawnError });
+    }
+    const finishedAt = new Date();
+    state.diagnostics = result.diagnostics;
+    state.stderr = result.stderr;
+    state.lastBuildOk = result.ok;
+    await writeServerLog(logFile, {
+      type: 'build-finished',
+      buildId,
+      ok: result.ok,
+      sourceFile,
+      startedAt: startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
+      durationMs: finishedAt.getTime() - startedAt.getTime(),
+      diagnostics: result.diagnostics,
+      stderr: result.stderr || undefined,
+      error: state.pandocSpawnError
+    });
+    if (serverHandle) serverHandle.broadcastReload();
+    return result;
+  });
+
+  try {
+    const resolvedAssets = await resolveAssets(options.selections ?? {});
+    cssFiles = (await materializeAssets(resolvedAssets, tempDir)).cssFiles;
+    await build.runNow();
+    if (state.pandocSpawnError) throw new Error(state.pandocSpawnError);
+    if (state.lastBuildOk === false) throw new Error(initialBuildFailureMessage(state));
+
+    let url;
+    serverHandle = createPreviewServer({
+      tempDir,
+      sourceDir,
+      getDiagnostics: () => state.diagnostics,
+      getStatus: () => sessionStatus(state, serverHandle?.clients.size ?? 0),
+      onBrowserLog: handleBrowserLog,
+      onFirstClient: async () => {
+        clearTimeout(noClientTimer);
+        if (options.readyFile) await writeJson(options.readyFile, {
+          url,
+          tempDir,
+          logFile,
+          pid: process.pid
+        });
+      },
+      onClientConnected: () => clearTimeout(closeGraceTimer),
+      onAllClientsGone: () => {
+        clearTimeout(closeGraceTimer);
+        closeGraceTimer = setTimeout(() => cleanup(0, { reason: 'browser closed' }), 3000);
+      }
+    });
+    const address = await serverHandle.listen();
+    url = `http://localhost:${address.port}/`;
+    started = true;
+    reporter.start(state, url);
+
+    watcher = chokidar.watch(watchTargets(sourceFile, resolvedAssets), {
+      ignoreInitial: true,
+      awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 25 }
+    });
+    watcher.on('all', (_eventName, changedPath) => {
+      if (mediaExtensions.has(path.extname(changedPath).toLowerCase())) {
+        serverHandle.broadcastReload();
+      } else {
+        const assetChanged = watchedAssetPaths(resolvedAssets).includes(changedPath);
+        if (assetChanged) {
+          materializeAssets(resolvedAssets, tempDir)
+            .then((materialized) => {
+              cssFiles = materialized.cssFiles;
+              build.schedule();
+            })
+            .catch((error) => reportOperationalError(error, { state, logFile, stderr }));
+        } else {
+          build.schedule();
+        }
+      }
+    });
+
+    await launchBrowser(url, options);
+
+    noClientTimer = setTimeout(() => {
+      const seconds = Math.round((options.attachTimeoutMs ?? 30000) / 1000);
+      stderr.write(`Error: browser failed to connect within ${seconds} seconds\n`);
+      cleanup(1, { reason: 'attach timeout' });
+    }, options.attachTimeoutMs ?? 30000);
+
+    process.once('SIGINT', () => cleanup(0, { reason: 'interrupted' }));
+    process.once('SIGTERM', () => cleanup(0, { reason: 'interrupted' }));
+
+    if (options.noExit) return { url, tempDir, cleanup, diagnostics: () => state.diagnostics, status: () => sessionStatus(state, serverHandle?.clients.size ?? 0) };
+    return await new Promise(() => {});
+  } catch (error) {
+    await writeServerLog(logFile, {
+      type: 'startup-error',
+      sourceFile,
+      error: error?.message || String(error)
+    });
+    await cleanup(1, { exit: false });
+    throw error;
+  }
+}
+
+function initialBuildFailureMessage(state) {
+  const stderr = String(state.stderr || '').trim();
+  const detail = stderr || String(state.diagnostics || '').trim() || 'Pandoc failed to produce a preview.';
+  return `Error compiling ${path.basename(state.sourceFile)}:\n${detail}`;
+}
+
+function createSessionState({ sourceFile, logFile }) {
+  return {
+    pid: process.pid,
+    sourceFile,
+    logFile,
+    buildId: 0,
+    diagnostics: '',
+    stderr: '',
+    pandocSpawnError: undefined,
+    lastBuildStartedAt: undefined,
+    lastBuildOk: undefined,
+    browserReport: undefined,
+    firstBrowserWarningReported: false
+  };
+}
+
+function sessionStatus(state, clientCount) {
+  const browserErrors = state.browserReport
+    ? [
+        ...(state.browserReport.error ? [{ message: state.browserReport.error }] : []),
+        ...(state.browserReport.errors ?? [])
+      ]
+    : undefined;
+  const status = {
+    pid: state.pid,
+    browserConnected: clientCount >= 1,
+    timestamp: new Date().toISOString(),
+    pandocSpawnError: state.pandocSpawnError,
+    pandocDiagnostics: String(state.diagnostics || '').trim() || undefined,
+    lastBuildStartedAt: state.lastBuildStartedAt,
+    browserErrors
+  };
+  return Object.fromEntries(Object.entries(status).filter(([, value]) => value !== undefined));
+}
+
+function createReporter({ sourceFile, debug, logFile, stdout }) {
+  let started = false;
+  return {
+    start(state, url) {
+      if (started) return;
+      started = true;
+      if (debug) stdout.write(`Writing log to ${logFile}\n`);
+      if (state.stderr) stdout.write(state.stderr.endsWith('\n') ? state.stderr : `${state.stderr}\n`);
+      stdout.write(`Showing ${path.basename(sourceFile)} at ${url}\n`);
+    }
+  };
+}
+
+async function reportOperationalError(error, { state, logFile, stderr }) {
+  const message = error?.message || String(error);
+  state.pandocSpawnError = message;
+  stderr.write(`${message}\n`);
+  await writeServerLog(logFile, { type: 'operational-error', error: message });
+}
+
+async function writeServerLog(logFile, event) {
+  if (!logFile) return;
+  const entry = {
+    timestamp: new Date().toISOString(),
+    ...event
+  };
+  await fs.appendFile(logFile, `[server] ${JSON.stringify(entry)}\n`).catch((error) => {
+    process.stderr.write(`Failed to write server log: ${error?.message || String(error)}\n`);
+  });
+}
+
+async function writePandocFailurePage({ tempDir, sourceFile, cssFiles, debug, buildId, error }) {
+  await writeErrorPage(
+    path.join(tempDir, 'index.html'),
+    error,
+    {
+      debugBrowser: debug,
+      cssFiles,
+      browserTitle: path.basename(sourceFile),
+      buildId
+    }
+  );
+}
+
+export function createBrowserLogHandler(options) {
+  const { tempDir, logFile, debugBrowser = false, onEntry } = options;
+  let sequence = 0;
+
+  return async function handleBrowserLog(payload = {}) {
+    sequence += 1;
+    const entry = await browserLogEntry({
+      payload,
+      tempDir,
+      sequence,
+      debugBrowser
+    });
+    const line = `[browser] ${JSON.stringify(entry)}\n`;
+
+    if (logFile) {
+      await fs.appendFile(logFile, line).catch((error) => {
+        console.error(`Failed to write browser log: ${error?.message || String(error)}`);
+      });
+      await onEntry?.(entry);
+      return;
+    }
+
+    if (debugBrowser) {
+      process.stdout.write(line);
+      await onEntry?.(entry);
+      return;
+    }
+
+    await onEntry?.(entry);
+  };
+}
+
+async function browserLogEntry({ payload, tempDir, sequence, debugBrowser }) {
+  const entry = {
+    timestamp: new Date().toISOString(),
+    type: stringOr(payload.type, 'browser-event'),
+    buildId: numberOr(payload.buildId),
+    phase: stringOr(payload.phase),
+    ok: typeof payload.ok === 'boolean' ? payload.ok : undefined,
+    url: stringOr(payload.url),
+    pageCount: numberOr(payload.pageCount),
+    renderedTextLength: numberOr(payload.renderedTextLength),
+    sourceTextLength: numberOr(payload.sourceTextLength),
+    renderedTextHead: debugBrowser ? stringOr(payload.renderedTextHead) : undefined,
+    renderedTextTail: stringOr(payload.renderedTextTail),
+    error: stringOr(payload.error),
+    errors: Array.isArray(payload.errors) ? payload.errors.slice(-20).map(normalizeBrowserError) : []
+  };
+
+  if (debugBrowser) {
+    entry.snapshots = {};
+    await writeSnapshot(entry.snapshots, tempDir, sequence, 'document', payload.documentHtml);
+    await writeSnapshot(entry.snapshots, tempDir, sequence, 'pages', payload.pagesHtml);
+    await writeSnapshot(entry.snapshots, tempDir, sequence, 'source', payload.sourceHtml);
+  }
+
+  return Object.fromEntries(Object.entries(entry).filter(([, value]) => value !== undefined));
+}
+
+async function writeSnapshot(snapshots, tempDir, sequence, name, value) {
+  if (typeof value !== 'string' || !value) return;
+  const filePath = path.join(tempDir, `browser-${String(sequence).padStart(4, '0')}-${name}.html`);
+  await fs.writeFile(filePath, value);
+  snapshots[name] = filePath;
+}
+
+function normalizeBrowserError(error) {
+  return {
+    message: stringOr(error?.message, 'Unknown browser error'),
+    source: stringOr(error?.source),
+    line: numberOr(error?.line),
+    column: numberOr(error?.column)
+  };
+}
+
+function stringOr(value, fallback) {
+  if (value === undefined || value === null) return fallback;
+  return String(value);
+}
+
+function numberOr(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}
+
+function watchTargets(sourceFile, resolvedAssets) {
+  const sourceDir = path.dirname(sourceFile);
+  const references = path.join(sourceDir, 'references.bib');
+  return [sourceFile, references, sourceDir, ...watchedAssetPaths(resolvedAssets)];
+}
+
+export function createBuildScheduler(buildFn, debounceMs = 100) {
+  let timer;
+  let running = false;
+  let pending = false;
+
+  async function run() {
+    clearTimeout(timer);
+    if (running) {
+      pending = true;
+      return;
+    }
+    running = true;
+    try {
+      do {
+        pending = false;
+        await buildFn();
+      } while (pending);
+    } finally {
+      running = false;
+    }
+  }
+
+  return {
+    schedule() {
+      clearTimeout(timer);
+      timer = setTimeout(run, debounceMs);
+    },
+    async runNow() {
+      await run();
+    }
+  };
+}
+
+async function launchBrowser(url, options = {}) {
+  if (options.noBrowser || process.env.MDPREVIEW_NO_BROWSER === '1') return;
+  if (isWsl()) {
+    await spawnAndWait('cmd.exe', ['/c', 'start', '', url]);
+    return;
+  }
+  await spawnAndWait('xdg-open', [url]);
+}
+
+function spawnAndWait(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} exited with code ${code}`));
+    });
+    child.unref();
+  });
+}
+
+export async function waitForReadyFile(filePath, timeoutMs = 10000) {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    try {
+      return JSON.parse(await fs.readFile(filePath, 'utf8'));
+    } catch {
+      await delay(50);
+    }
+  }
+  throw new Error(`Timed out waiting for preview session readiness: ${filePath}`);
+}