pageproof 0.1.0

package/bin/mdpreview.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(error?.message || String(error));
+  process.exitCode = 1;
+});

package/bin/pageproof.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(error?.message || String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pageproof",
+  "version": "0.1.0",
+  "description": "Live Pandoc Markdown preview with paginated browser output.",
+  "type": "module",
+  "author": "Damon Wischik <djw1005@cam.ac.uk>",
+  "keywords": [
+    "markdown",
+    "preview",
+    "pandoc",
+    "pagedjs",
+    "citations",
+    "footnotes",
+    "cli"
+  ],
+  "bin": {
+    "pageproof": "./bin/pageproof.js"
+  },
+  "files": [
+    "assets/",
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "yaml": "^2.9.0"
+  },
+  "license": "SEE LICENSE IN THIRD_PARTY_NOTICES.md",
+  "devDependencies": {
+    "playwright": "^1.60.0"
+  }
+}

package/src/assets.js

@@ -0,0 +1,246 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { packageRoot, pathExists } from './util.js';
+
+export const mandatoryBaseStyles = ['_paged'];
+export const defaultBaseStyles = ['msword'];
+export const defaultCitationStyle = 'european-journal-of-international-law';
+
+const selectors = {
+  style: { ext: 'css' },
+  citations: { ext: 'csl', defaultName: defaultCitationStyle, runtimeName: 'citations.csl' }
+};
+
+export function defaultSelections() {
+  return {
+    styles: [],
+    citations: null
+  };
+}
+
+export async function resolveAsset(kind, name, options = {}) {
+  const selector = selectors[kind];
+  if (!selector) throw new Error(`Unknown asset type: ${kind}`);
+  if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+    throw new Error(`Invalid ${kind} asset name: ${name}`);
+  }
+
+  const filename = `${name}.${selector.ext}`;
+  const homeDir = options.homeDir ?? os.homedir();
+  const candidates = [
+    path.join(homeDir, '.mdpreview', filename),
+    path.join(packageRoot, 'assets', filename)
+  ];
+
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) return candidate;
+  }
+
+  throw new Error(
+    `Missing ${kind} asset "${name}". Looked for ${candidates.join(' and ')}.`
+  );
+}
+
+export async function resolveAssets(selections, options = {}) {
+  const homeDir = options.homeDir ?? os.homedir();
+  const config = await loadConfig(homeDir);
+  const baseStyles = options.baseStyles ?? configBaseStyles(config);
+  const commandStyles = styleSelections(selections);
+  const styleNames = [...mandatoryBaseStyles, ...baseStyles, ...commandStyles];
+  const citationName =
+    selections.citations ?? configCitationStyle(config) ?? selectors.citations.defaultName;
+
+  return {
+    styles: await Promise.all(
+      styleNames.map(async (name) => ({
+        name,
+        path: await resolveAsset('style', name, { ...options, homeDir })
+      }))
+    ),
+    template: path.join(packageRoot, 'assets', 'default.html'),
+    citations: await resolveAsset('citations', citationName, { ...options, homeDir }),
+    favicon: path.join(packageRoot, 'assets', 'favicon.svg'),
+    luaFilter: path.join(packageRoot, 'assets', 'footnotes-inline.lua'),
+    paged: path.join(packageRoot, 'assets', 'vendor', 'paged.polyfill.js'),
+    mathjax: path.join(packageRoot, 'assets', 'vendor', 'mathjax'),
+    mathjaxFonts: path.join(packageRoot, 'assets', 'vendor', 'mathjax-fonts')
+  };
+}
+
+async function loadConfig(homeDir) {
+  const configPath = path.join(homeDir, '.mdpreview', 'config.yaml');
+  if (!(await pathExists(configPath))) return { path: configPath, data: {} };
+  try {
+    return { path: configPath, data: parseYaml(await fs.readFile(configPath, 'utf8')) ?? {} };
+  } catch (error) {
+    throw new Error(`Invalid mdpreview config ${configPath}: ${error?.message || String(error)}`);
+  }
+}
+
+function configBaseStyles(config) {
+  const base = config.data?.styles;
+  if (base === undefined) return [...defaultBaseStyles];
+  if (!Array.isArray(base) || base.some((item) => typeof item !== 'string')) {
+    throw new Error(`Invalid mdpreview config ${config.path}: styles must be a list of style names.`);
+  }
+  return base;
+}
+
+function configCitationStyle(config) {
+  const value = config.data?.citations;
+  if (value === undefined) return null;
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid mdpreview config ${config.path}: citations must be a string.`);
+  }
+  return value;
+}
+
+export async function configuredBaseStyles(homeDir = os.homedir()) {
+  return configBaseStyles(await loadConfig(homeDir));
+}
+
+export async function configuredCitationStyle(homeDir = os.homedir()) {
+  return configCitationStyle(await loadConfig(homeDir)) ?? selectors.citations.defaultName;
+}
+
+export async function availableAssets(options = {}) {
+  const homeDir = options.homeDir ?? os.homedir();
+  const [styles, citations] = await Promise.all([
+    listAvailableAssets('style', homeDir),
+    listAvailableAssets('citations', homeDir)
+  ]);
+  return { styles, citations };
+}
+
+async function listAvailableAssets(kind, homeDir) {
+  const selector = selectors[kind];
+  if (!selector) throw new Error(`Unknown asset type: ${kind}`);
+  const discovered = new Map();
+  const roots = [
+    { source: 'user', dir: path.join(homeDir, '.mdpreview') },
+    { source: 'bundled', dir: path.join(packageRoot, 'assets') }
+  ];
+
+  for (const root of roots) {
+    let files;
+    try {
+      files = await fs.readdir(root.dir, { withFileTypes: true });
+    } catch (error) {
+      if (error?.code === 'ENOENT') continue;
+      throw error;
+    }
+
+    for (const file of files) {
+      if (!file.isFile() || path.extname(file.name) !== `.${selector.ext}`) continue;
+      const name = path.basename(file.name, `.${selector.ext}`);
+      if (!/^[A-Za-z0-9._-]+$/.test(name)) continue;
+      const existing = discovered.get(name) ?? {
+        name,
+        path: path.join(root.dir, file.name),
+        sources: []
+      };
+      existing.sources.push(root.source);
+      if (root.source === 'user') existing.path = path.join(root.dir, file.name);
+      discovered.set(name, existing);
+    }
+  }
+
+  const entries = await Promise.all(
+    [...discovered.values()].map(async (entry) => ({
+      ...entry,
+      description: await describeAsset(kind, entry.path)
+    }))
+  );
+  return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+async function describeAsset(kind, assetPath) {
+  const text = await fs.readFile(assetPath, 'utf8').catch(() => '');
+  if (kind === 'style') return cssDescription(text);
+  if (kind === 'citations') return cslDescription(text);
+  return '';
+}
+
+function cssDescription(text) {
+  const match = text.match(/^\s*\/\*\s*mdpreview-style:\s*([^*]+?)\s*\*\//i);
+  return match ? collapseWhitespace(match[1]) : '';
+}
+
+function cslDescription(text) {
+  return (
+    xmlElementText(text, 'title') ||
+    xmlElementText(text, 'summary') ||
+    xmlElementText(text, 'title-short')
+  );
+}
+
+function xmlElementText(text, elementName) {
+  const match = text.match(new RegExp(`<${elementName}(?:\\s[^>]*)?>([\\s\\S]*?)</${elementName}>`, 'i'));
+  return match ? decodeXml(collapseWhitespace(match[1].replace(/<[^>]*>/g, ''))) : '';
+}
+
+function collapseWhitespace(value) {
+  return String(value).replace(/\s+/g, ' ').trim();
+}
+
+function decodeXml(value) {
+  return value
+    .replaceAll('&amp;', '&')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&quot;', '"')
+    .replaceAll('&apos;', "'");
+}
+
+function styleSelections(selections = {}) {
+  if (Array.isArray(selections.styles)) return selections.styles;
+  if (selections.style) return [selections.style];
+  return [];
+}
+
+export async function materializeAssets(resolvedAssets, tempDir) {
+  const copies = [
+    ...resolvedAssets.styles.map((style, index) => [
+      style.path,
+      styleRuntimeName(style.name, index)
+    ]),
+    [resolvedAssets.template, 'template.html'],
+    [resolvedAssets.citations, 'citations.csl'],
+    [resolvedAssets.favicon, 'favicon.svg'],
+    [resolvedAssets.luaFilter, 'footnotes-inline.lua'],
+    [resolvedAssets.paged, 'paged.polyfill.js']
+  ];
+  const directoryCopies = [
+    [resolvedAssets.mathjax, 'mathjax'],
+    [resolvedAssets.mathjaxFonts, 'mathjax-fonts']
+  ];
+
+  for (const [source, target] of copies) {
+    if (!(await pathExists(source))) throw new Error(`Missing required asset: ${source}`);
+    await fs.copyFile(source, path.join(tempDir, target));
+  }
+  for (const [source, target] of directoryCopies) {
+    if (!(await pathExists(source))) throw new Error(`Missing required asset: ${source}`);
+    await fs.cp(source, path.join(tempDir, target), { recursive: true });
+  }
+
+  return {
+    cssFiles: resolvedAssets.styles.map((style, index) => styleRuntimeName(style.name, index))
+  };
+}
+
+export function watchedAssetPaths(resolvedAssets) {
+  return [
+    ...resolvedAssets.styles.map((style) => style.path),
+    resolvedAssets.template,
+    resolvedAssets.citations,
+    resolvedAssets.favicon,
+    resolvedAssets.luaFilter
+  ];
+}
+
+function styleRuntimeName(name, index) {
+  return `style-${String(index).padStart(2, '0')}-${name}.css`;
+}

package/src/cli.js

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import {
+  availableAssets,
+  configuredBaseStyles,
+  configuredCitationStyle,
+  defaultSelections
+} from './assets.js';
+import { runSession, waitForReadyFile } from './lifecycle.js';
+import { packageRoot } from './util.js';
+
+export function parseArgs(argv) {
+  const options = {
+    detached: false,
+    debug: false,
+    session: false,
+    selections: defaultSelections()
+  };
+  const files = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help') options.help = true;
+    else if (arg === '--styles') options.styles = true;
+    else if (arg === '--show-skill') options.showSkill = true;
+    else if (arg === '--detached') options.detached = true;
+    else if (arg === '--debug') options.debug = true;
+    else if (arg === '--session') options.session = true;
+    else if (arg.startsWith('--ready-file=')) options.readyFile = arg.slice('--ready-file='.length);
+    else if (arg.startsWith('--log-file=')) options.logFile = arg.slice('--log-file='.length);
+    else if (arg.startsWith('--style=')) options.selections.styles.push(arg.slice('--style='.length));
+    else if (arg.startsWith('--citations=')) options.selections.citations = arg.slice('--citations='.length);
+    else if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}`);
+    else files.push(arg);
+  }
+
+  if (options.styles && files.length) throw new Error('--styles does not accept a Markdown file.');
+  if (options.showSkill && files.length) throw new Error('--show-skill does not accept a Markdown file.');
+  if (!options.help && !options.styles && !options.showSkill) {
+    if (files.length !== 1) throw new Error('Expected exactly one Markdown file.');
+    options.file = path.resolve(files[0]);
+  }
+  return options;
+}
+
+export async function runCli(argv) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    console.log(helpText());
+    return;
+  }
+  if (options.styles) {
+    console.log(await stylesText());
+    return;
+  }
+  if (options.showSkill) {
+    process.stdout.write(await skillText());
+    return;
+  }
+
+  if (options.detached && !options.session) {
+    await runDetached(options);
+    return;
+  }
+
+  await runSession(options);
+}
+
+export async function runDetached(options) {
+  const tempDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'mdpreview-session-'));
+  const readyFile = path.join(tempDir, 'ready.json');
+  const childStdout = path.join(tempDir, 'child.stdout');
+  const childStderr = path.join(tempDir, 'child.stderr');
+  const out = fs.openSync(childStdout, 'a');
+  const err = fs.openSync(childStderr, 'a');
+  const childArgs = [
+    path.join(packageRoot, 'bin', 'pageproof.js'),
+    '--session',
+    `--ready-file=${readyFile}`,
+    ...options.selections.styles.map((style) => `--style=${style}`),
+    ...(options.selections.citations ? [`--citations=${options.selections.citations}`] : []),
+    ...(options.debug ? ['--debug'] : []),
+    options.file
+  ];
+  const child = spawn(process.execPath, childArgs, {
+    detached: true,
+    stdio: ['ignore', out, err]
+  });
+  fs.closeSync(out);
+  fs.closeSync(err);
+  child.unref();
+
+  let ready;
+  try {
+    ready = await waitForReadyFile(readyFile);
+  } catch (error) {
+    const stderr = await fsp.readFile(childStderr, 'utf8').catch(() => '');
+    if (stderr.trim()) process.stderr.write(stderr);
+    throw error;
+  }
+  const startup = await fsp.readFile(childStdout, 'utf8').catch(() => '');
+  if (startup.trim()) process.stdout.write(startup);
+  console.log(`Preview server is running as PID ${ready.pid} -- use this to check if it's alive`);
+  console.log(`To check for any document errors, fetch ${ready.url}status.json`);
+}
+
+export function helpText() {
+  return `Usage:
+  pageproof FILE.md
+  pageproof --detached FILE.md
+  pageproof --style=NAME [--style=OTHER] FILE.md
+  pageproof --citations=NAME FILE.md
+  pageproof --styles
+  pageproof --show-skill
+
+Options:
+  --citations=NAME Select a CSL citation style.
+  --style=NAME     Add a document extra style. Repeatable.
+  --styles         List available document and citation styles.
+  --show-skill     Print the bundled agent skill file.`;
+}
+
+export async function skillText() {
+  return fsp.readFile(path.join(packageRoot, 'assets', 'SKILL.md'), 'utf8');
+}
+
+export async function stylesText(options = {}) {
+  const assets = await availableAssets(options);
+  const baseStyles = await configuredBaseStyles(options.homeDir);
+  const citationDefault = await configuredCitationStyle(options.homeDir);
+  const visibleStyles = assets.styles.filter((entry) => !entry.name.startsWith('_'));
+  return [
+    formatAssetSection('Document styles', visibleStyles, baseStyles),
+    '',
+    formatAssetSection('Citation styles', assets.citations, [citationDefault]),
+    '',
+    configHelpText()
+  ].join('\n');
+}
+
+function configHelpText() {
+  return `Additional styles (NAME.css) and citation styles (NAME.csl) can be placed in ~/.mdpreview/.
+Defaults can be overridden in ~/.mdpreview/config.yaml, e.g.
+  styles: [msword]
+  citations: european-journal-of-international-law`;
+}
+
+function formatAssetSection(title, entries, defaults) {
+  const header = `${title} (default=${defaults.join(', ') || 'none'}):`;
+  if (!entries.length) return `${header}\n  (none)`;
+  const nameWidth = Math.max(...entries.map((entry) => displayName(entry).length));
+  const lines = entries.map((entry) => {
+    const name = displayName(entry).padEnd(nameWidth);
+    const description = entry.description ? `  ${entry.description}` : '';
+    return `  ${name}${description}`;
+  });
+  return `${header}\n${lines.join('\n')}`;
+}
+
+function displayName(entry) {
+  const isUser = entry.sources.includes('user') && !entry.sources.includes('bundled');
+  return isUser ? `${entry.name} [user]` : entry.name;
+}