@yojahny/wp-design-library 0.1.0

package/src/index/query.mjs

@@ -0,0 +1,103 @@
+import Database from 'better-sqlite3';
+import * as sqliteVec from 'sqlite-vec';
+
+export function openIndex(indexPath, { readonly = true } = {}) {
+  const db = new Database(indexPath, { readonly, fileMustExist: readonly });
+  try { sqliteVec.load(db); db.vec = true; } catch { db.vec = false; }
+  return db;
+}
+
+function filterSql(filters = {}, col = 'slug') {
+  const clauses = [], params = [];
+  for (const [facet, terms] of Object.entries(filters)) {
+    const list = Array.isArray(terms) ? terms : [terms];
+    if (!list.length) continue;
+    clauses.push(`${col} IN (SELECT slug FROM entry_tags WHERE facet=? AND term IN (${list.map(() => '?').join(',')}))`);
+    params.push(facet, ...list);
+  }
+  return { where: clauses.length ? ' AND ' + clauses.join(' AND ') : '', params };
+}
+
+const RRF_K = 60;
+
+export async function search(db, { query = '', filters = {}, limit = 10, embedder = null }) {
+  const { where, params } = filterSql(filters, 'e.slug');
+  if (!query.trim()) {
+    const { where, params } = filterSql(filters);
+    const rows = db.prepare(`SELECT slug, title, tier, 0 AS score FROM entries WHERE 1=1 ${where} ORDER BY captured_at DESC LIMIT ?`)
+      .all(...params, limit);
+    return { arms: ['fts'], hits: rows };
+  }
+  const q = fts5Quote(query);
+  const ftsOnly = (reason) => {
+    const rows = db.prepare(
+      `SELECT e.slug, e.title, e.tier, bm25(entries_fts) AS score
+         FROM entries_fts JOIN entries e ON e.slug = entries_fts.slug
+        WHERE entries_fts MATCH ? ${where}
+        ORDER BY score LIMIT ?`
+    ).all(q, ...params, limit);
+    return { arms: ['fts'], skipped: [{ arm: 'vec', reason }], hits: rows };
+  };
+  if (!(db.vec && embedder)) {
+    return ftsOnly(db.vec ? 'no embedder' : 'sqlite-vec not loaded');
+  }
+  let vec;
+  try {
+    vec = await embedder.text(query);
+  } catch (err) {
+    return ftsOnly(`vec arm failed: ${err.message}`);
+  }
+  const rows = db.prepare(`
+    WITH f AS (SELECT slug, r FROM (
+                 SELECT slug, row_number() OVER (ORDER BY bm25(entries_fts)) AS r
+                 FROM entries_fts WHERE entries_fts MATCH ?
+               ) ORDER BY r LIMIT 50),
+         v AS (SELECT slug, row_number() OVER (ORDER BY distance) AS r
+               FROM vec_text WHERE embedding MATCH ? AND k = 50)
+    SELECT e.slug, e.title, e.tier, f.r AS fts_rank, v.r AS vec_rank,
+           COALESCE(1.0/(${RRF_K}+f.r),0) + COALESCE(1.0/(${RRF_K}+v.r),0) AS score
+      FROM entries e LEFT JOIN f ON f.slug = e.slug LEFT JOIN v ON v.slug = e.slug
+     WHERE (f.r IS NOT NULL OR v.r IS NOT NULL) ${where}
+     ORDER BY score DESC LIMIT ?`).all(q, Buffer.from(vec.buffer), ...params, limit);
+  return {
+    arms: ['fts', 'vec'],
+    hits: rows.map((r) => ({ slug: r.slug, title: r.title, tier: r.tier, score: r.score, ranks: { fts: r.fts_rank, vec: r.vec_rank } })),
+  };
+}
+
+export async function similar(db, { slug, image, limit = 10, embedder = null }) {
+  if (!(db.vec && embedder)) {
+    return { refused: `similar needs the image arm: ${db.vec ? 'no embedder' : 'sqlite-vec not loaded'}` };
+  }
+  let vec;
+  if (slug) {
+    const row = db.prepare(`SELECT embedding FROM vec_image WHERE slug = ?`).get(slug);
+    if (!row) return { refused: `similar needs the image arm: no vector for slug ${slug}` };
+    vec = row.embedding;
+  } else {
+    try {
+      vec = Buffer.from((await embedder.image(image)).buffer);
+    } catch (err) {
+      return { refused: `vec arm failed: ${err.message}` };
+    }
+  }
+  // k = 50: sqlite-vec 0.1.9 requires an explicit k alongside MATCH for a KNN query.
+  // slug ?? '' never matches a real slug, so an image query (no slug) excludes nothing.
+  const rows = db.prepare(`
+    WITH v AS (SELECT slug, distance FROM vec_image WHERE embedding MATCH ? AND k = 50)
+    SELECT e.slug, e.title, v.distance
+      FROM v JOIN entries e ON e.slug = v.slug
+     WHERE v.slug != ?
+     ORDER BY v.distance LIMIT ?`).all(vec, slug ?? '', limit);
+  return { arms: ['vec'], hits: rows };
+}
+
+function fts5Quote(q) {
+  return q.split(/\s+/).filter(Boolean).map((t) => `"${t.replace(/"/g, '""')}"`).join(' ');
+}
+
+export function getEntry(db, slug) {
+  const row = db.prepare(`SELECT * FROM entries WHERE slug = ?`).get(slug);
+  if (!row) return null;
+  return { slug: row.slug, title: row.title, tier: row.tier, dir: row.dir, body: row.body, fm: JSON.parse(row.frontmatter_json) };
+}

package/src/index/schema-vec.sql

@@ -0,0 +1,4 @@
+DROP TABLE IF EXISTS vec_text;
+DROP TABLE IF EXISTS vec_image;
+CREATE VIRTUAL TABLE vec_text  USING vec0(slug TEXT PRIMARY KEY, embedding float[384]);
+CREATE VIRTUAL TABLE vec_image USING vec0(slug TEXT PRIMARY KEY, embedding float[768]);

package/src/index/schema.sql

@@ -0,0 +1,10 @@
+DROP TABLE IF EXISTS entries;
+DROP TABLE IF EXISTS entry_tags;
+DROP TABLE IF EXISTS entries_fts;
+CREATE TABLE entries (
+  slug TEXT PRIMARY KEY, title TEXT NOT NULL, tier TEXT NOT NULL, source_kind TEXT NOT NULL,
+  captured_at TEXT NOT NULL, dir TEXT NOT NULL, body TEXT NOT NULL, frontmatter_json TEXT NOT NULL
+);
+CREATE TABLE entry_tags (slug TEXT NOT NULL, facet TEXT NOT NULL, term TEXT NOT NULL);
+CREATE INDEX entry_tags_ft ON entry_tags(facet, term);
+CREATE VIRTUAL TABLE entries_fts USING fts5(slug UNINDEXED, title, body, tags, tokenize='trigram');

package/src/ingest/draft.mjs

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { REQUIRED_BLANKS } from '../entry.mjs';
+
+function get(obj, dotted) {
+  return dotted.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+function isBlank(v) {
+  return v == null || v === '' || (Array.isArray(v) && v.length === 0);
+}
+
+export function writeDraft({ entriesDir, slug, title, source, media, captured, palette, type }) {
+  const dir = path.join(entriesDir, slug);
+  fs.mkdirSync(dir, { recursive: true });
+  const fm = {
+    slug, title, tier: 'inspiration',
+    source: { kind: source.kind, url: source.url ?? null, license: source.license },
+    captured, media,
+    roles: [], feel: [],
+    palette: palette ?? { canvas: '', ink: '', accent: '' },
+    type: type ?? { display: '', body: '' },
+    motion: { devices: [], notes: '' },
+    ported_from: null,
+  };
+  fs.writeFileSync(path.join(dir, 'entry.md'), `---\n${yaml.dump(fm, { lineWidth: 120 })}---\n`);
+  // Report only the blanks a caller actually still needs to fill — a mechanically
+  // filled field (measured palette/type from a URL add) is not "blank" just because
+  // the frame-sampling path always leaves it that way.
+  const blanks = REQUIRED_BLANKS.filter((k) => isBlank(get(fm, k)));
+  return { dir, blanks };
+}

package/src/ingest/frames.mjs

@@ -0,0 +1,93 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import sharp from 'sharp';
+
+const VIDEO = /\.(mp4|mov|webm|mkv)$/i;
+
+function which(bin) {
+  try { execFileSync('sh', ['-c', `command -v ${bin}`], { stdio: 'pipe' }); return true; } catch { return false; }
+}
+
+function readFailure(input, e) {
+  const reason = typeof e === 'string' ? e : (e.stderr?.toString().split('\n').find(Boolean) ?? e.message);
+  return new Error(`ffmpeg could not read ${path.basename(input)}: ${reason}`);
+}
+
+// Browser MediaRecorder webm has no format=duration (ffprobe prints N/A). Fall back to
+// counting the video stream's frames against its rate: dur = frames / (num/den).
+// Parsed by key, not position: ffprobe's default writer does not emit fields in the
+// order -show_entries lists them (avg_frame_rate prints before nb_read_frames here).
+function streamCountDuration(input) {
+  try {
+    const out = execFileSync('ffprobe', [
+      '-v', 'error', '-select_streams', 'v:0', '-count_frames',
+      '-show_entries', 'stream=nb_read_frames,avg_frame_rate', '-of', 'default=nw=1', '-i', input,
+    ], { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+    const nFrames = Number(out.match(/^nb_read_frames=(\S+)/m)?.[1]);
+    const [num, den] = (out.match(/^avg_frame_rate=(\S+)/m)?.[1] ?? '').split('/').map(Number);
+    if (!Number.isFinite(nFrames) || nFrames <= 0 || !Number.isFinite(num) || !Number.isFinite(den) || num <= 0 || den <= 0) return null;
+    return nFrames / (num / den);
+  } catch {
+    return null;
+  }
+}
+
+async function videoFrames(input, want) {
+  if (!which('ffmpeg') || !which('ffprobe')) throw new Error('ffmpeg is required for video input and was not found on PATH');
+  let dur;
+  try {
+    const probed = execFileSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', '-i', input], { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+    dur = Number(probed);
+  } catch (e) {
+    throw readFailure(input, e);
+  }
+  if (!Number.isFinite(dur) || dur <= 0) dur = streamCountDuration(input) ?? dur;
+  if (!Number.isFinite(dur) || dur <= 0) throw new Error(`ffmpeg could not read ${path.basename(input)}: no duration`);
+  const durationMs = Math.round(dur * 1000);
+  const n = want ?? Math.min(36, Math.max(6, Math.round(durationMs / 500)));
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wpdl-'));
+  try {
+    execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', input, '-vf', `fps=${n / dur}`, '-frames:v', String(n), path.join(dir, '%03d.png')], { stdio: ['ignore', 'pipe', 'pipe'] });
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.png')).sort().map((f) => path.join(dir, f));
+    if (files.length === 0) throw new Error('no frames decoded');
+    return { files, durationMs, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) };
+  } catch (e) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    throw readFailure(input, e.message === 'no frames decoded' ? e.message : e);
+  }
+}
+
+export async function compositeStrip(tiles, w, h, outPng) {
+  const cols = tiles.length > 12 ? 6 : Math.min(3, tiles.length), rows = Math.ceil(tiles.length / cols);
+  await sharp({ create: { width: w * cols, height: h * rows, channels: 3, background: '#000' } })
+    .composite(tiles.map((b, k) => ({ input: b, left: (k % cols) * w, top: Math.floor(k / cols) * h })))
+    .png().toFile(outPng);
+}
+
+export async function sampleFrames(input, outPng, { frames: want } = {}) {
+  if (VIDEO.test(input)) {
+    const { files, durationMs, cleanup } = await videoFrames(input, want);
+    try {
+      const tiles = await Promise.all(files.map((f) => sharp(f).png().toBuffer()));
+      const first = await sharp(files[0]).metadata();
+      await compositeStrip(tiles, first.width, first.height, outPng);
+      return { frames: files.length, durationMs, sampled: files.map((_, i) => i) };
+    } finally {
+      cleanup();
+    }
+  }
+  const meta = await sharp(input, { pages: -1 }).metadata();
+  const frames = meta.pages ?? 1;
+  const delays = meta.delay ?? [];
+  const durationMs = delays.reduce((a, b) => a + b, 0);
+  const byDuration = durationMs > 0 ? Math.round(durationMs / 500) : 12;
+  let n = Math.max(1, Math.min(frames, want ?? Math.min(36, Math.max(6, byDuration))));
+  if (frames >= 2) n = Math.max(2, n);
+  const sampled = n >= frames ? [...Array(frames).keys()] : [...Array(n).keys()].map((i) => Math.round((i * (frames - 1)) / (n - 1)));
+  const w = meta.width, h = meta.pageHeight ?? meta.height;
+  const tiles = await Promise.all(sampled.map((i) => sharp(input, { page: i }).png().toBuffer()));
+  await compositeStrip(tiles, w, h, outPng);
+  return { frames, durationMs, sampled };
+}

package/src/ingest/measure.mjs

@@ -0,0 +1,158 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { chromium } from 'playwright-core';
+
+const VIEWPORT_WIDE = { width: 1440, height: 900 };
+const VIEWPORT_NARROW = { width: 390, height: 844 };
+
+// Runs inside the page via page.evaluate — no Node globals, no sharp, nothing
+// from this module's closure crosses the Playwright boundary.
+function collect() {
+  function toHex(raw) {
+    const m = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:[,\s/]+([\d.]+))?\s*\)$/.exec(raw || '');
+    if (!m) return null;
+    const [, r, g, b, a] = m;
+    if (a !== undefined && Number(a) === 0) return null; // fully transparent: not a real token
+    const hex = (n) => Math.round(Number(n)).toString(16).padStart(2, '0');
+    return `#${hex(r)}${hex(g)}${hex(b)}`;
+  }
+
+  const bodyStyle = getComputedStyle(document.body);
+  let canvas = toHex(bodyStyle.backgroundColor);
+  if (!canvas) canvas = toHex(getComputedStyle(document.documentElement).backgroundColor) || '';
+  const ink = toHex(bodyStyle.color) || '';
+
+  const freq = new Map();
+  for (const el of document.querySelectorAll('a, button, [role="button"]')) {
+    const cs = getComputedStyle(el);
+    for (const raw of [cs.color, cs.backgroundColor]) {
+      const hex = toHex(raw);
+      if (hex && hex !== canvas && hex !== ink) freq.set(hex, (freq.get(hex) || 0) + 1);
+    }
+  }
+  let accent = '';
+  let best = 0;
+  for (const [hex, count] of freq) if (count > best) { best = count; accent = hex; }
+
+  const h1 = document.querySelector('h1');
+  const p = document.querySelector('p');
+  const fontDisplay = h1 ? getComputedStyle(h1).fontFamily : '';
+  const fontBody = p ? getComputedStyle(p).fontFamily : '';
+
+  const sections = [...document.querySelectorAll('section, header, main > *, footer')].map((el, index) => {
+    const rect = el.getBoundingClientRect();
+    const animations = el.getAnimations({ subtree: true }).map((anim) => {
+      const target = anim.effect?.target;
+      const cls = target?.className ? String(target.className).trim() : '';
+      const targetStr = target ? (cls ? `${target.tagName.toLowerCase()}.${cls}` : target.tagName.toLowerCase()) : '';
+      let timeline = 'none';
+      if (anim.timeline) {
+        if (typeof ViewTimeline !== 'undefined' && anim.timeline instanceof ViewTimeline) timeline = 'view';
+        else if (typeof ScrollTimeline !== 'undefined' && anim.timeline instanceof ScrollTimeline) timeline = 'scroll';
+        else timeline = 'document';
+      }
+      // rangeStart/rangeEnd are CSSKeywordish: the string 'normal' (no animation-range
+      // set), or a { rangeName, offset: CSSNumericValue } dictionary whose offset needs
+      // its own toString() — naive template-literal concatenation stringifies the
+      // object as "[object Object]".
+      const fmtBoundary = (v) => {
+        if (v == null) return null;
+        if (typeof v === 'string') return v;
+        return v.offset != null ? `${v.rangeName} ${v.offset}` : v.rangeName;
+      };
+      const rStart = fmtBoundary(anim.rangeStart), rEnd = fmtBoundary(anim.rangeEnd);
+      const range = rStart && rEnd && !(rStart === 'normal' && rEnd === 'normal') ? `${rStart} ${rEnd}` : null;
+      const rawDuration = anim.effect?.getTiming?.().duration;
+      const duration = typeof rawDuration === 'number' ? rawDuration : null;
+      return { target: targetStr, timeline, range, duration };
+    });
+    return {
+      index, tag: el.tagName.toLowerCase(), id: el.id || '',
+      class: el.className ? String(el.className).trim() : '',
+      top: Math.round(rect.top + window.scrollY), height: Math.round(rect.height),
+      animations,
+    };
+  });
+
+  return { tokens: { canvas, ink, accent, fontDisplay, fontBody }, sections };
+}
+
+// Measures a live page with the system Chrome: computed-style tokens, a per-section
+// animation inventory, and two screenshots (1440/390). With record:true it also
+// scrolls top to bottom in `stops` equal steps at 1440, screenshotting each —
+// add.mjs feeds those frames to the strip compositor. Never throws: chrome
+// missing/unlaunchable is caught up front, and everything from here (viewport,
+// navigation, screenshots, the scroll loop, the evaluate) is one outer try/catch,
+// so any failure — named ('page failed to load', 'measurement failed') or not —
+// comes back as { ok: false, error }, with whatever partial output (frames,
+// screenshots) had already been captured still attached.
+export async function measure(url, outDir, { chrome = process.env.CHROME_PATH, record = false, stops = 12 } = {}) {
+  if (!chrome || !fs.existsSync(chrome)) {
+    return { ok: false, error: 'chrome not available: CHROME_PATH not set or not found' };
+  }
+  let browser;
+  try {
+    // ponytail: chromiumSandbox off by default — Docker's default seccomp profile blocks
+    // the user namespaces Chrome's own sandbox needs, so it would fail to launch inside
+    // the container; the non-root `node` user is the isolation there instead. Opt in with
+    // CHROME_SANDBOX=1 only where user namespaces are actually allowed (e.g. bare metal).
+    browser = await chromium.launch({ executablePath: chrome, headless: true, timeout: 60000, chromiumSandbox: process.env.CHROME_SANDBOX === '1' });
+  } catch (err) {
+    return { ok: false, error: `chrome not available: ${err.message}` };
+  }
+  const screenshots = {};
+  let frames;
+  try {
+    const page = await browser.newPage();
+    await page.setViewportSize(VIEWPORT_WIDE);
+    try {
+      await page.goto(url, { waitUntil: 'load', timeout: 45000 });
+    } catch (err) {
+      return { ok: false, error: `page failed to load: ${err.message}` };
+    }
+
+    fs.mkdirSync(outDir, { recursive: true });
+    const shot1440 = path.join(outDir, 'screen-1440.png');
+    await page.screenshot({ path: shot1440, fullPage: false });
+    screenshots[1440] = shot1440;
+
+    if (record) {
+      frames = [];
+      const total = await page.evaluate(() => document.documentElement.scrollHeight);
+      const vh = VIEWPORT_WIDE.height;
+      for (let i = 0; i < stops; i++) {
+        const y = stops > 1 ? Math.round((i * Math.max(total - vh, 0)) / (stops - 1)) : 0;
+        await page.evaluate((y) => window.scrollTo(0, y), y);
+        await page.waitForTimeout(150);
+        const fp = path.join(outDir, `frame-${String(i).padStart(2, '0')}.png`);
+        await page.screenshot({ path: fp, fullPage: false });
+        frames.push(fp);
+      }
+      await page.evaluate(() => window.scrollTo(0, 0));
+    }
+
+    let data;
+    try {
+      data = await page.evaluate(collect);
+    } catch (err) {
+      return { ok: false, error: `measurement failed: ${err.message}`, frames, screenshots };
+    }
+
+    await page.setViewportSize(VIEWPORT_NARROW);
+    const shot390 = path.join(outDir, 'screen-390.png');
+    await page.screenshot({ path: shot390, fullPage: false });
+    screenshots[390] = shot390;
+
+    const measureJson = {
+      url, at: new Date().toISOString().slice(0, 10), viewport: [1440, 390],
+      tokens: data.tokens, sections: data.sections,
+      screenshots: { 1440: path.basename(shot1440), 390: path.basename(shot390) },
+    };
+    fs.writeFileSync(path.join(outDir, 'measure.json'), JSON.stringify(measureJson, null, 2));
+    return { ok: true, measure: measureJson, screenshots, frames };
+  } catch (err) {
+    return { ok: false, error: `measurement failed: ${err.message}`, frames, screenshots };
+  } finally {
+    await browser.close();
+  }
+}

package/src/ingest/save.mjs

@@ -0,0 +1,11 @@
+import { parseEntry, validateEntry } from '../entry.mjs';
+import { buildIndex } from '../index/build.mjs';
+
+export async function saveEntry({ dir, vocab, indexPath, entriesDir, models }) {
+  const e = parseEntry(dir);
+  const r = validateEntry(e, vocab);
+  if (!r.ok) return { ok: false, slug: e.slug, errors: r.errors, refused: r.errors.join('; ') };
+  // Phase 1: a full rebuild is cheap; single-entry upsert arrives with the vector arms.
+  await buildIndex({ entriesDir, indexPath, vocab, models });
+  return { ok: true, slug: e.slug, errors: [] };
+}

package/src/ingest/url-guard.mjs

@@ -0,0 +1,76 @@
+import dns from 'node:dns/promises';
+import net from 'node:net';
+
+// SSRF guard for `add <url>` and `refresh` over the hosted HTTP transport: a remote
+// caller names a URL, this process's Chrome fetches it, so the URL must not be able
+// to reach the container's own loopback/private network. Stdio has no such caller
+// (the operator already has that network access), so it only gets the scheme check.
+const V4_PRIVATE = [
+  ['127.0.0.0', 8], ['10.0.0.0', 8], ['172.16.0.0', 12], ['192.168.0.0', 16],
+  ['169.254.0.0', 16], ['0.0.0.0', 8], ['100.64.0.0', 10],
+];
+
+function ipv4ToInt(ip) {
+  return ip.split('.').reduce((acc, o) => (acc << 8) + Number(o), 0) >>> 0;
+}
+
+function isPrivateV4(ip) {
+  const n = ipv4ToInt(ip);
+  return V4_PRIVATE.some(([base, bits]) => {
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    return (n & mask) === (ipv4ToInt(base) & mask);
+  });
+}
+
+// ::ffff:a.b.c.d (dotted) or ::ffff:xxxx:xxxx (hex) — dns.lookup can hand back either form.
+function ipv4MappedToV4(address) {
+  const dotted = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+  if (dotted) return dotted[1];
+  const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(address);
+  if (!hex) return null;
+  const hi = parseInt(hex[1], 16), lo = parseInt(hex[2], 16);
+  return [(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff].join('.');
+}
+
+function isPrivateAddress(address, family) {
+  if (family === 4) return isPrivateV4(address);
+  const a = address.toLowerCase();
+  if (a === '::1') return true;
+  if (a.startsWith('fc') || a.startsWith('fd')) return true; // fc00::/7
+  if (/^fe[89ab]/.test(a)) return true; // fe80::/10
+  const mapped = ipv4MappedToV4(a);
+  return mapped ? isPrivateV4(mapped) : false;
+}
+
+// Returns null when the URL is allowed, or a refusal string naming why.
+export async function refuseUnsafeUrl(url, { transport } = {}) {
+  let u;
+  try { u = new URL(url); } catch { return `invalid URL: ${url}`; }
+  const scheme = u.protocol;
+  const overHttp = transport === 'http';
+
+  const schemeOk = scheme === 'https:' || scheme === 'http:' || (scheme === 'file:' && !overHttp);
+  if (!schemeOk) return overHttp ? 'only https:// URLs are accepted over http' : `unsupported URL scheme: ${scheme}`;
+  if (!overHttp) return null; // stdio/CLI: no caller to guard against, DNS never consulted
+
+  if (scheme !== 'https:') return 'only https:// URLs are accepted over http';
+
+  // WHATWG URL keeps the brackets on an IPv6 literal host ("[::1]"); net.isIP and
+  // dns.lookup both want the bare address.
+  const hostname = u.hostname.replace(/^\[|\]$/g, '');
+  const literalFamily = net.isIP(hostname);
+  let addresses;
+  if (literalFamily) {
+    addresses = [{ address: hostname, family: literalFamily }];
+  } else {
+    try {
+      addresses = await dns.lookup(hostname, { all: true });
+    } catch {
+      return `cannot resolve ${hostname}`;
+    }
+  }
+  if (addresses.some((a) => isPrivateAddress(a.address, a.family))) {
+    return `${hostname} resolves to a private address`;
+  }
+  return null;
+}

package/src/mcp/http.mjs

@@ -0,0 +1,72 @@
+import http from 'node:http';
+import path from 'node:path';
+import { timingSafeEqual } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { buildServer } from './server.mjs';
+import { paths } from '../paths.mjs';
+import { openIndex } from '../index/query.mjs';
+import { getEmbedder } from '../index/embed.mjs';
+import { serveFile } from '../ui/serve.mjs';
+
+function authorized(header, token) {
+  const want = Buffer.from(`Bearer ${token}`), got = Buffer.from(header ?? '');
+  return want.length === got.length && timingSafeEqual(want, got);
+}
+
+async function handle(req, res, p, token, embedder) {
+  const url = new URL(req.url, 'http://x');
+  if (url.pathname === '/healthz') {
+    let entries = 0, arms = ['fts'];
+    try {
+      const db = openIndex(p.index);
+      entries = db.prepare('SELECT count(*) c FROM entries').get().c;
+      if (db.vec && db.prepare('SELECT count(*) c FROM vec_text').get().c > 0) arms = ['fts', 'vec'];
+      db.close();
+    } catch {}
+    res.writeHead(200, { 'content-type': 'application/json' });
+    return res.end(JSON.stringify({ ok: true, entries, arms, version: p.version }));
+  }
+  if (url.pathname === '/mcp') {
+    if (!authorized(req.headers.authorization, token)) { res.writeHead(401); return res.end('unauthorized'); }
+    // ponytail: SDK 1.30's stateless transport (sessionIdGenerator: undefined)
+    // latches `_initialized` after the first `initialize` and 400s any later
+    // one on that same instance — fine for one client, wrong for a server
+    // meant to answer many. A fresh transport + server per request keeps
+    // every request statelessly independent; buildServer() stays the one
+    // tool table, just called once per request instead of once at startup.
+    // The embedder is cached once at serveHttp start and threaded through
+    // instead: the real arm loads models from disk, too slow to redo per request.
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    const server = await buildServer({ transport: 'http', embedder });
+    await server.connect(transport);
+    res.on('close', () => { transport.close(); server.close(); });
+    return transport.handleRequest(req, res);
+  }
+  // req.url, not url.pathname: WHATWG URL parsing already folds `%2e%2e`/`..` before
+  // serveFile's own prefix check would ever see them (see src/ui/serve.mjs).
+  return serveFile(path.join(p.data, 'ui'), req.url, res);
+}
+
+export async function serveHttp() {
+  const token = process.env.LIBRARY_TOKEN;
+  if (!token) { process.stderr.write('refusing to start HTTP transport: LIBRARY_TOKEN is not set\n'); return 2; }
+  const port = Number(process.env.PORT || 4180);
+  const p = paths();
+  const embedder = await getEmbedder({ models: p.models }); // once per process; handle() reuses it per request
+
+  // ponytail: a bare `async (req, res) =>` callback here would turn any
+  // thrown error (bad body, SDK error) into an unhandled rejection, which
+  // crashes the whole process under Node's default --unhandled-rejections.
+  // Catching per-request keeps one bad request from taking the server down.
+  const srv = http.createServer((req, res) => {
+    handle(req, res, p, token, embedder).catch((err) => {
+      process.stderr.write(`wp-design-library: request error: ${err.stack || err}\n`);
+      if (!res.headersSent) res.writeHead(500);
+      res.end();
+    });
+  });
+
+  await new Promise((resolve, reject) => { srv.once('error', reject); srv.listen(port, resolve); });
+  process.stderr.write(`wp-design-library: http on :${port}\n`);
+  return new Promise(() => {});
+}