@yojahny/wp-design-library 0.1.0

package/tests/checks/minors.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; pid=""
+trap 'rm -rf "$tmp"; [ -n "$pid" ] && kill $pid 2>/dev/null || true' EXIT
+
+# Item 1: --inbox, two files that slugify identically in one run -> the second refuses,
+# naming the first file.
+d1="$tmp/item1"; mkdir -p "$d1/inbox" "$d1/entries"
+cp tests/fixtures/three-frame.webp "$d1/inbox/A.webp"
+cp tests/fixtures/three-frame.webp "$d1/inbox/a.webp"
+out=$(LIBRARY_DATA="$d1" node bin/library.mjs add --inbox --source public-site --license x 2>&1 || true)
+echo "$out" | grep -qF '{"file":"a.webp","slug":"a","status":"refused","reason":"slug a collides with A.webp in this run"}' \
+  || { echo "FAIL: item1 same-run slug collision"; echo "$out"; exit 1; }
+
+# Item 2: source.kind outside the vocabulary is refused at draft time (resolveTerm),
+# both for `add` directly and for `--inbox`.
+d2="$tmp/item2"; mkdir -p "$d2/entries"
+out=$(LIBRARY_DATA="$d2" node bin/library.mjs add tests/fixtures/three-frame.webp --slug bad-kind --title t --source bogus --license x 2>&1 || true)
+echo "$out" | grep -q 'unknown source term' || { echo "FAIL: item2 add refuses unknown source.kind"; echo "$out"; exit 1; }
+[ ! -e "$d2/entries/bad-kind" ] || { echo "FAIL: item2 draft written despite unknown source.kind"; exit 1; }
+
+d2b="$tmp/item2b"; mkdir -p "$d2b/inbox" "$d2b/entries"
+cp tests/fixtures/three-frame.webp "$d2b/inbox/x.webp"
+out=$(LIBRARY_DATA="$d2b" node bin/library.mjs add --inbox --source bogus --license x 2>&1 || true)
+echo "$out" | grep -q '"reason":"source.kind: unknown source term' || { echo "FAIL: item2 inbox refuses unknown source.kind at draft time"; echo "$out"; exit 1; }
+[ ! -e "$d2b/entries/x" ] || { echo "FAIL: item2 inbox draft written despite unknown source.kind"; exit 1; }
+
+# Item 3: over http, a dangling symlink under inbox is refused, for both add and similar.
+d3="$tmp/item3"; mkdir -p "$d3/inbox" "$d3/entries"
+ln -s "$d3/inbox/does-not-exist.webp" "$d3/inbox/dangling.webp"
+LIBRARY_DATA="$d3" PORT=4190 LIBRARY_TOKEN=t0k node bin/library.mjs serve --http >"$d3/log" 2>&1 & pid=$!
+for i in $(seq 1 30); do curl -sf localhost:4190/healthz >/dev/null 2>&1 && break; sleep 0.2; done
+init='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}'
+curl -s -X POST localhost:4190/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$init" >/dev/null
+call_add="{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"add\",\"arguments\":{\"input\":\"$d3/inbox/dangling.webp\",\"slug\":\"x\",\"title\":\"x\",\"source\":{\"kind\":\"open\",\"license\":\"MIT\"}}}}"
+curl -s -X POST localhost:4190/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$call_add" \
+  | grep -q '"refused":"input does not exist"' || { echo "FAIL: http add did not refuse a dangling symlink under inbox"; exit 1; }
+call_sim="{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"similar\",\"arguments\":{\"image\":\"$d3/inbox/dangling.webp\"}}}"
+curl -s -X POST localhost:4190/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$call_sim" \
+  | grep -q '"refused":"input does not exist"' || { echo "FAIL: http similar did not refuse a dangling symlink under inbox"; exit 1; }
+kill $pid 2>/dev/null || true; pid=""
+
+# Item 4: slugify('___.webp') derives an empty slug -> refused, naming --slug.
+d4="$tmp/item4"; mkdir -p "$d4/inbox" "$d4/entries"
+cp tests/fixtures/three-frame.webp "$d4/inbox/___.webp"
+out=$(LIBRARY_DATA="$d4" node bin/library.mjs add --inbox --source public-site --license x 2>&1 || true)
+echo "$out" | grep -qF '"reason":"cannot derive a slug from the file name; pass --slug"' \
+  || { echo "FAIL: item4 empty slug refused"; echo "$out"; exit 1; }
+
+# Item 5: export --saved-only skips drafts (entries failing validateEntry) and reports
+# how many on stderr; the tar still goes to stdout.
+d5="$tmp/item5"; mkdir -p "$d5/entries"
+cp -r tests/fixtures/entry-ok "$d5/entries/entry-ok"
+LIBRARY_DATA="$d5" node bin/library.mjs add tests/fixtures/three-frame.webp --slug draft-one --title t --source own --license x >/dev/null
+LIBRARY_DATA="$d5" node bin/library.mjs export --saved-only >"$d5/out.tar" 2>"$d5/err"
+tar -tf "$d5/out.tar" | grep -q 'entries/entry-ok/entry.md' || { echo "FAIL: item5 saved entry missing from tar"; exit 1; }
+tar -tf "$d5/out.tar" | grep -q 'entries/draft-one' && { echo "FAIL: item5 draft included in tar"; exit 1; }
+grep -q 'skipped 1 drafts' "$d5/err" || { echo "FAIL: item5 skipped count on stderr"; cat "$d5/err"; exit 1; }
+# all drafts -> a named refusal, never tar's own "empty archive" wording
+rm -rf "$d5/entries/entry-ok"
+LIBRARY_DATA="$d5" node bin/library.mjs export --saved-only >/dev/null 2>"$d5/err2" && { echo "FAIL: item5 all-drafts export exited 0"; exit 1; }
+grep -q 'export: no saved entries to export' "$d5/err2" || { echo "FAIL: item5 all-drafts refusal not named"; cat "$d5/err2"; exit 1; }
+
+# Item 6: over http, `add` with a URL refuses before Chrome ever launches — a plain
+# http:// scheme, a literal private IP, and a hostname that resolves to loopback.
+d6="$tmp/item6"; mkdir -p "$d6/entries"
+LIBRARY_DATA="$d6" PORT=4190 LIBRARY_TOKEN=t0k node bin/library.mjs serve --http >"$d6/log" 2>&1 & pid=$!
+for i in $(seq 1 30); do curl -sf localhost:4190/healthz >/dev/null 2>&1 && break; sleep 0.2; done
+curl -s -X POST localhost:4190/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$init" >/dev/null
+call_scheme="{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"add\",\"arguments\":{\"input\":\"http://127.0.0.1:1/\",\"slug\":\"ssrf-scheme\",\"title\":\"t\",\"source\":{\"kind\":\"public-site\",\"license\":\"x\"}}}}"
+curl -s -X POST localhost:4190/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$call_scheme" \
+  | grep -qF 'only https://' || { echo "FAIL: item6 http:// scheme not refused"; exit 1; }
+call_ip="{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{\"name\":\"add\",\"arguments\":{\"input\":\"https://127.0.0.1:1/\",\"slug\":\"ssrf-ip\",\"title\":\"t\",\"source\":{\"kind\":\"public-site\",\"license\":\"x\"}}}}"
+curl -s -X POST localhost:4190/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$call_ip" \
+  | grep -qF 'resolves to a private address' || { echo "FAIL: item6 literal private IP not refused"; exit 1; }
+call_host="{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"tools/call\",\"params\":{\"name\":\"add\",\"arguments\":{\"input\":\"https://localhost:1/\",\"slug\":\"ssrf-host\",\"title\":\"t\",\"source\":{\"kind\":\"public-site\",\"license\":\"x\"}}}}"
+curl -s -X POST localhost:4190/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$call_host" \
+  | grep -qF 'resolves to a private address' || { echo "FAIL: item6 localhost (resolves to loopback) not refused by the guard"; exit 1; }
+kill $pid 2>/dev/null || true; pid=""
+[ ! -e "$d6/entries/ssrf-scheme" ] && [ ! -e "$d6/entries/ssrf-ip" ] && [ ! -e "$d6/entries/ssrf-host" ] \
+  || { echo "FAIL: item6 a draft was written despite an SSRF refusal"; exit 1; }
+
+echo PASS

package/tests/checks/prompt-add-entry.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# The server ships the add-entry prompt: prompts/list names it, prompts/get renders the
+# order of operations and the tagging rubric with the vocabulary read from vocab.yaml.
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"
+{
+  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'
+  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"prompts/list"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"add-entry","arguments":{"path":"/x/site.webp","source":"public-site"}}}'
+  sleep 1
+} | LIBRARY_DATA="$tmp" timeout 10 node bin/library.mjs serve >"$tmp/out" 2>"$tmp/err" || true
+grep -q '"name":"add-entry"' "$tmp/out" || { echo "FAIL: prompts/list lacks add-entry"; cat "$tmp/err"; exit 1; }
+get=$(grep '"id":3' "$tmp/out")
+need() { echo "$get" | grep -qF "$1" || { echo "FAIL: prompt text lacks: $1"; exit 1; }; }
+need 'The session is the tagger'
+need 'show the draft and wait for a yes'
+need 'never remove a field to make it pass'
+need 'Eyeballed from N sampled frames, not measured'
+need 'added by a PR to `vocab.yaml`, never by an ingest'
+need 'can only read files already in the server'
+need '/x/site.webp'
+need 'public-site'
+# vocabulary is rendered from vocab.yaml, so every role term appears
+for t in $(node --input-type=module -e 'import { loadVocab } from "./src/vocab.mjs"; console.log([...loadVocab().facets.role].join(" "))'); do need "$t"; done
+echo PASS

package/tests/checks/resources.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# The server ships two resources (vocab.yaml, an entry's entry.md) and the
+# brief-from-library prompt: resources/list, resources/templates/list and
+# resources/read cover both; prompts/list and prompts/get cover the prompt.
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+{
+  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'
+  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"resources/list"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":3,"method":"resources/templates/list"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"library://vocab"}}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":5,"method":"resources/read","params":{"uri":"library://entry/entry-ok"}}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":6,"method":"resources/read","params":{"uri":"library://entry/nope"}}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":9,"method":"resources/read","params":{"uri":"library://entry/bad.slug"}}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":7,"method":"prompts/list"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":8,"method":"prompts/get","params":{"name":"brief-from-library","arguments":{"brief":"a hero and a pricing table, dark and premium"}}}'
+  sleep 1
+} | LIBRARY_DATA="$tmp" timeout 10 node bin/library.mjs serve >"$tmp/out" 2>"$tmp/err" || true
+
+grep '"id":2' "$tmp/out" | grep -q 'library://vocab' || { echo "FAIL: resources/list lacks library://vocab"; cat "$tmp/err"; exit 1; }
+grep '"id":3' "$tmp/out" | grep -q 'library://entry/{slug}' || { echo "FAIL: resources/templates/list lacks library://entry/{slug}"; exit 1; }
+grep '"id":4' "$tmp/out" | grep -q 'role:' || { echo "FAIL: vocab resource read lacks role:"; exit 1; }
+grep '"id":5' "$tmp/out" | grep -q 'slug: entry-ok' || { echo "FAIL: entry resource read lacks slug: entry-ok"; exit 1; }
+nope=$(grep '"id":6' "$tmp/out")
+echo "$nope" | grep -q '"error"' || { echo "FAIL: unknown slug did not error"; exit 1; }
+echo "$nope" | grep -q 'no entry nope' || { echo "FAIL: unknown slug error lacks 'no entry nope'"; exit 1; }
+bad=$(grep '"id":9' "$tmp/out")
+echo "$bad" | grep -q '"error"' || { echo "FAIL: bad slug did not error"; exit 1; }
+echo "$bad" | grep -qF 'no entry bad.slug' || { echo "FAIL: bad slug error lacks 'no entry bad.slug'"; exit 1; }
+grep '"id":7' "$tmp/out" | grep -q '"name":"brief-from-library"' || { echo "FAIL: prompts/list lacks brief-from-library"; exit 1; }
+get=$(grep '"id":8' "$tmp/out")
+echo "$get" | grep -qF 'limit: 3' || { echo "FAIL: prompt text lacks: limit: 3"; exit 1; }
+echo "$get" | grep -qF '## References' || { echo "FAIL: prompt text lacks: ## References"; exit 1; }
+echo "$get" | grep -qF 'ranks.fts' || { echo "FAIL: prompt text lacks the weak-vector-match rule (ranks.fts)"; exit 1; }
+echo "$get" | grep -qF 'having no reference rather than filling it' || { echo "FAIL: prompt text lacks the weak-match-only role guidance"; exit 1; }
+echo "$get" | grep -qi 'hero' || { echo "FAIL: prompt text lacks the word hero"; exit 1; }
+# vocabulary is rendered from vocab.yaml, so every feel term appears
+for t in $(node --input-type=module -e 'import { loadVocab } from "./src/vocab.mjs"; console.log([...loadVocab().facets.feel].join(" "))'); do
+  echo "$get" | grep -qF "$t" || { echo "FAIL: prompt text lacks feel term: $t"; exit 1; }
+done
+echo PASS

package/tests/checks/rrf.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+export LIBRARY_EMBED=stub
+mkdir -p "$tmp/entries"
+
+# Four entries sharing role/feel/motion so tags never leak "parallax"/"bed" (both are
+# also valid vocab terms elsewhere) into the FTS/vector text: only title+body
+# distinguish them from the query "parallax bed". Keyword relevance (verified by
+# querying bm25() directly): y is best (both terms in title and twice in body),
+# z is medium (both terms once, in body only), w is weak (both terms once, in a
+# title padded long with unrelated words so document-length normalisation costs it),
+# x has no keyword match at all (never appears in the FTS arm's results).
+#
+# The stub embedder has no real semantics, so instead of hoping title/body text
+# happens to produce a useful vector spread, the vectors are overwritten directly in
+# vec_text after indexing so the two arms are made to actively disagree: x (worst
+# keywords) gets the *closest* vector, y (best keywords) gets the *farthest*
+# (negated) vector, z and w sit in between in keyword order. Only z is good on both
+# arms, so only RRF's fusion — not either arm alone — puts it first.
+mk() {
+  slug=$1; title=$2; body=$3
+  d="$tmp/entries/$slug"; mkdir -p "$d"
+  cp tests/fixtures/entry-ok/strip.png "$d/strip.png"
+  cat > "$d/entry.md" <<EOF
+---
+slug: $slug
+title: $title
+tier: inspiration
+source:
+  kind: open
+  url: https://example.com
+  license: MIT
+captured:
+  method: frames
+  at: 2026-09-14
+  tool: wp-design-library@0.1.0
+media:
+  frames: 3
+  duration_ms: 120
+roles: [footer]
+feel: [cold]
+palette:
+  canvas: "#0b0f14"
+  ink: "#f4f6f8"
+  accent: "#6ea8ff"
+type:
+  display: geometric sans, light
+  body: same family
+motion:
+  devices: [pin]
+  notes: static footer element
+ported_from: null
+---
+
+$body
+EOF
+}
+mk y "parallax bed hero" "the parallax bed rises here and the parallax bed falls there again"
+mk z "quiet mountains view" "parallax bed"
+mk w "parallax bed among many other unrelated words padding this title out considerably more" "clouds valleys rivers forests deserts glaciers coastlines"
+mk x "quiet coastal footer element" "clouds valleys rivers forests deserts glaciers coastlines mountains"
+
+LIBRARY_DATA="$tmp" node bin/library.mjs index >"$tmp/out" 2>&1
+grep -q "arms: fts,vec" "$tmp/out" || { echo "FAIL: corpus did not index with the vec arm"; cat "$tmp/out"; exit 1; }
+
+LIBRARY_DATA="$tmp" node --input-type=module -e '
+import { openIndex, search } from "./src/index/query.mjs";
+import { getEmbedder } from "./src/index/embed.mjs";
+import { paths } from "./src/paths.mjs";
+const must = (c, m) => { if (!c) { console.error("FAIL: " + m); process.exit(1); } };
+
+const e = await getEmbedder({ models: "/x", mode: "stub" });
+const q = await e.text("parallax bed");
+
+function renorm(arr) {
+  let s = 0; for (const v of arr) s += v * v;
+  const n = Math.sqrt(s) || 1;
+  for (let i = 0; i < arr.length; i++) arr[i] /= n;
+  return arr;
+}
+const vecX = Float32Array.from(q);                                                  // rank 1: exact match
+const vecZ = renorm(Float32Array.from(q).map((v, i) => (i === 0 ? v + 0.01 : v)));   // rank 2: small nudge
+const vecW = renorm(Float32Array.from(q).map((v, i) => (i === 0 ? v + 0.05 : v)));   // rank 3: bigger nudge
+const vecY = Float32Array.from(q).map((v) => -v);                                   // rank 4: opposite direction
+
+const dbw = openIndex(paths().index, { readonly: false });
+const upd = dbw.prepare("UPDATE vec_text SET embedding = ? WHERE slug = ?");
+upd.run(Buffer.from(vecX.buffer), "x");
+upd.run(Buffer.from(vecZ.buffer), "z");
+upd.run(Buffer.from(vecW.buffer), "w");
+upd.run(Buffer.from(vecY.buffer), "y");
+dbw.close();
+
+const db2 = openIndex(paths().index);
+const r = await search(db2, { query: "parallax bed", embedder: e });
+must(r.arms.length === 2 && r.arms.includes("fts") && r.arms.includes("vec"), "arms is fts+vec");
+must(r.hits[0].slug === "z", "z ranks first (mid on both beats top on one), got " + JSON.stringify(r.hits.map(h => h.slug)));
+const top2 = r.hits.map(h => h.slug).slice(0, 2);
+must(top2.includes("y"), "y appears in the top 2, got " + JSON.stringify(top2));
+const xHit = r.hits.find(h => h.slug === "x");
+must(!!xHit, "x is present in the results");
+must(r.hits[0].slug !== "x", "x is not first");
+must(xHit.ranks.fts === null, "x has no fts rank, got " + JSON.stringify(xHit.ranks));
+must(xHit.ranks.vec === 1, "x is vec rank 1, got " + JSON.stringify(xHit.ranks));
+
+const embOff = await getEmbedder({ models: "/x", mode: "off" });
+must(embOff === null, "LIBRARY_EMBED=off resolves to no embedder");
+const r2 = await search(db2, { query: "parallax bed", embedder: embOff });
+must(r2.arms.length === 1 && r2.arms[0] === "fts", "off falls back to fts only");
+must(Array.isArray(r2.skipped) && r2.skipped.length === 1 && r2.skipped[0].arm === "vec" && !!r2.skipped[0].reason, "skipped names the vec arm and a reason");
+
+const badEmbedder = { arm: "vec", dims: e.dims, text: async () => { throw new Error("boom"); }, image: e.image };
+const r3 = await search(db2, { query: "parallax bed", embedder: badEmbedder });
+must(r3.arms.length === 1 && r3.arms[0] === "fts", "a failing embedder degrades to fts only, got " + JSON.stringify(r3.arms));
+must(Array.isArray(r3.skipped) && r3.skipped.length === 1 && r3.skipped[0].arm === "vec" && r3.skipped[0].reason.includes("boom"), "skipped reason mentions boom, got " + JSON.stringify(r3.skipped));
+must(Array.isArray(r3.hits) && r3.hits.length > 0, "hits are still returned despite the embedder failure");
+'
+echo PASS

package/tests/checks/seed-sync.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# On every start, entries present in the seed (the image's entries/) but missing from
+# LIBRARY_DATA are copied in; entries already in the volume are never overwritten.
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); pid=""; trap 'rm -rf "$tmp"; [ -n "$pid" ] && kill $pid 2>/dev/null || true' EXIT
+mkdir -p "$tmp/seed" "$tmp/data/entries"
+cp -r tests/fixtures/entry-ok "$tmp/seed/entry-ok"
+cp -r tests/fixtures/entry-ok "$tmp/seed/entry-two"; sed -i 's/slug: entry-ok/slug: entry-two/' "$tmp/seed/entry-two/entry.md"
+# volume already holds entry-ok with a local edit that must survive
+cp -r tests/fixtures/entry-ok "$tmp/data/entries/entry-ok"; sed -i 's/Fixture hero with parallax bed/Volume edit kept/' "$tmp/data/entries/entry-ok/entry.md"
+LIBRARY_DATA="$tmp/data" LIBRARY_SEED="$tmp/seed" PORT=4196 LIBRARY_TOKEN=t0k node bin/library.mjs serve --http >"$tmp/log" 2>&1 & pid=$!
+for i in $(seq 1 30); do curl -sf localhost:4196/healthz >/dev/null 2>&1 && break; sleep 0.2; done
+curl -sf localhost:4196/healthz | grep -q '"entries":2' || { echo "FAIL: seed entry not synced into a non-empty volume"; cat "$tmp/log"; exit 1; }
+grep -q "Volume edit kept" "$tmp/data/entries/entry-ok/entry.md" || { echo "FAIL: volume entry was overwritten"; exit 1; }
+grep -q "seed: copied 1 new" "$tmp/log" || { echo "FAIL: sync not reported"; cat "$tmp/log"; exit 1; }
+kill $pid; wait $pid 2>/dev/null || true; pid=""
+# second start copies nothing
+LIBRARY_DATA="$tmp/data" LIBRARY_SEED="$tmp/seed" PORT=4196 LIBRARY_TOKEN=t0k node bin/library.mjs serve --http >"$tmp/log2" 2>&1 & pid=$!
+for i in $(seq 1 30); do curl -sf localhost:4196/healthz >/dev/null 2>&1 && break; sleep 0.2; done
+grep -q "seed: copied 0 new" "$tmp/log2" || { echo "FAIL: second start should copy nothing"; cat "$tmp/log2"; exit 1; }
+echo PASS

package/tests/checks/similar.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; export LIBRARY_EMBED=stub; pid=""
+trap 'rm -rf "$tmp"; [ -n "$pid" ] && kill $pid 2>/dev/null || true' EXIT
+
+# a and b: byte-identical strip.png (both are plain copies of the fixture).
+# c: a strip of a different size, so its stub vector differs.
+mkdir -p "$tmp/entries"
+cp -r tests/fixtures/entry-ok "$tmp/entries/a"; sed -i 's/slug: entry-ok/slug: a/' "$tmp/entries/a/entry.md"
+cp -r tests/fixtures/entry-ok "$tmp/entries/b"; sed -i 's/slug: entry-ok/slug: b/' "$tmp/entries/b/entry.md"
+cp -r tests/fixtures/entry-ok "$tmp/entries/c"; sed -i 's/slug: entry-ok/slug: c/' "$tmp/entries/c/entry.md"
+printf x >> "$tmp/entries/c/strip.png"
+
+# stub, over stdio: slug lookup and image lookup
+{
+  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'
+  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"similar","arguments":{"slug":"a"}}}'
+  printf '%s\n' "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"similar\",\"arguments\":{\"image\":\"$tmp/entries/a/strip.png\"}}}"
+  printf '%s\n' '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"similar","arguments":{}}}'
+  sleep 1
+} | LIBRARY_DATA="$tmp" timeout 10 node bin/library.mjs serve >"$tmp/out" 2>"$tmp/err" || true
+
+node --input-type=module -e '
+import fs from "node:fs";
+const lines = fs.readFileSync(process.argv[2], "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+const must = (c, m) => { if (!c) { console.error("FAIL: " + m); process.exit(1); } };
+const byId = (id) => lines.find((l) => l.id === id)?.result?.structuredContent;
+
+const bySlug = byId(2);
+must(bySlug.arms.length === 1 && bySlug.arms[0] === "vec", "similar-by-slug arms is vec");
+must(bySlug.hits[0].slug === "b" && bySlug.hits[0].distance === 0, "similar-by-slug returns b first at distance 0; got " + JSON.stringify(bySlug.hits));
+
+const byImage = byId(3);
+const slugs = byImage.hits.map((h) => h.slug);
+must(slugs.includes("a") && slugs.includes("b"), "similar-by-image returns a and b; got " + JSON.stringify(slugs));
+
+const noArg = byId(4);
+must(!!noArg.refused, "similar with neither slug nor image is refused");
+' _ "$tmp/out"
+
+# LIBRARY_EMBED=off: similar refuses, naming the arm
+{
+  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'
+  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"similar","arguments":{"slug":"a"}}}'
+  sleep 1
+} | LIBRARY_DATA="$tmp" LIBRARY_EMBED=off timeout 10 node bin/library.mjs serve >"$tmp/out-off" 2>"$tmp/err-off" || true
+grep '"id":2' "$tmp/out-off" | grep -q 'refused.*arm' || { echo "FAIL: LIBRARY_EMBED=off did not refuse similar, naming the arm"; cat "$tmp/out-off"; exit 1; }
+
+# over http: image is confined to <data>/inbox
+LIBRARY_DATA="$tmp" PORT=4191 LIBRARY_TOKEN=t0k node bin/library.mjs serve --http >"$tmp/log" 2>&1 & pid=$!
+for i in $(seq 1 30); do curl -sf localhost:4191/healthz >/dev/null 2>&1 && break; sleep 0.2; done
+curl -sf localhost:4191/healthz | grep -q '"arms":\["fts","vec"\]' || { echo "FAIL: healthz arms with vec"; cat "$tmp/log"; exit 1; }
+init='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}'
+curl -s -X POST localhost:4191/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$init" >/dev/null
+call='{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"similar","arguments":{"image":"/etc/hostname"}}}'
+curl -s -X POST localhost:4191/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$call" \
+  | grep -q 'refused.*inbox' || { echo "FAIL: http similar did not refuse an image outside the inbox"; exit 1; }
+kill $pid 2>/dev/null || true; pid=""
+echo PASS

package/tests/checks/ui-build.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; pid=""; trap 'rm -rf "$tmp"; [ -n "$pid" ] && kill $pid 2>/dev/null || true' EXIT
+mkdir -p "$tmp/entries"
+cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+cp -r tests/fixtures/entry-ok "$tmp/entries/entry-draft"
+# draft frontmatter slug carries a path-traversal + attribute-breakout payload; the
+# directory name (entry-draft) stays safe. title is blanked so the card/entry-page title
+# falls back to fm.slug (text, shown only through esc()) and exercises the quote-escaping
+# fix. captured.at is newer than entry-ok's so the sort fix (not insertion order) puts it first.
+sed -i 's/title: Fixture hero with parallax bed/title: ""/; s/roles: \[hero, closing\]/roles: []/; s#slug: entry-ok#slug: ../escape" onmouseover="x#; s/  at: 2026-09-14/  at: 2026-09-20/' "$tmp/entries/entry-draft/entry.md"
+
+# `library ui` builds a static gallery straight from entries/, no index required first
+LIBRARY_DATA="$tmp" node bin/library.mjs ui >"$tmp/out" 2>&1
+ui="$tmp/ui"
+[ -f "$ui/index.html" ] || { echo "FAIL: index.html missing"; cat "$tmp/out"; exit 1; }
+[ -f "$ui/manifest.json" ] || { echo "FAIL: manifest.json missing"; cat "$tmp/out"; exit 1; }
+[ "$(grep -c '"slug":' "$ui/manifest.json")" = "2" ] || { echo "FAIL: manifest does not have two rows"; cat "$ui/manifest.json"; exit 1; }
+[ "$(grep -c '"draft": true' "$ui/manifest.json")" = "1" ] || { echo "FAIL: manifest does not mark exactly one draft"; cat "$ui/manifest.json"; exit 1; }
+grep -q 'Fixture hero with parallax bed' "$ui/entry/entry-ok.html" || { echo "FAIL: entry page missing title"; exit 1; }
+grep -q '<h2>What it does</h2>' "$ui/entry/entry-ok.html" || { echo "FAIL: markdown heading not converted"; exit 1; }
+[ -f "$ui/strips/entry-ok.png" ] || { echo "FAIL: strip not copied"; exit 1; }
+for t in hero proof feature process offer testimonial faq closing capability explainer page-head footer; do
+  grep -q "value=\"$t\"" "$ui/index.html" || { echo "FAIL: role term $t missing from index.html filters"; exit 1; }
+done
+
+# fm.slug must never reach a path: nothing escaped outDir or the entry/ dir via ../
+# (the payload is `../escape" onmouseover="x`, so any file carrying "escape" anywhere under $tmp is the leak)
+[ -z "$(find "$tmp" -name '*escape*' -print -quit)" ] || { echo "FAIL: fm.slug reached a filesystem path"; find "$tmp" -name '*escape*'; exit 1; }
+# fm.slug must never reach an unescaped attribute: a raw " right before onmouseover=
+# means the quote broke out; a safely-escaped &quot; is fine and expected here
+grep -Fq '" onmouseover="' "$ui/index.html" && { echo "FAIL: fm.slug quote broke out of an attribute"; exit 1; }
+grep -q '"slug": "entry-draft"' "$ui/manifest.json" || { echo "FAIL: manifest does not list the draft under its directory name"; cat "$ui/manifest.json"; exit 1; }
+
+# captured.at round-trips js-yaml as a Date; sort must land on the ISO string, newest first
+node -e '
+const rows = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+if (rows[0].slug !== "entry-draft") { console.error(JSON.stringify(rows.map((r) => [r.slug, r.captured]))); process.exit(1); }
+' "$ui/manifest.json" || { echo "FAIL: newer captured.at entry is not first in manifest.json"; exit 1; }
+
+# a real file one level above the ui root (LIBRARY_DATA itself), so a successful
+# traversal would actually read something back instead of 404ing on its own
+echo '{"leak":true}' > "$tmp/package.json"
+
+# `serve --http` builds the same gallery on start and serves it at /, safely
+LIBRARY_DATA="$tmp" PORT=4193 LIBRARY_TOKEN=t0k timeout 10 node bin/library.mjs serve --http >"$tmp/log" 2>&1 & pid=$!
+for i in $(seq 1 30); do curl -sf localhost:4193/healthz >/dev/null 2>&1 && break; sleep 0.2; done
+code=$(curl -s -o /dev/null -w '%{http_code}' localhost:4193/)
+[ "$code" = "200" ] || { echo "FAIL: GET / -> $code"; cat "$tmp/log"; exit 1; }
+curl -s localhost:4193/ | grep -q 'id="grid"' || { echo "FAIL: GET / missing the grid"; exit 1; }
+code=$(curl -s -o /dev/null -w '%{http_code}' localhost:4193/entry/entry-ok.html)
+[ "$code" = "200" ] || { echo "FAIL: GET /entry/entry-ok.html -> $code"; exit 1; }
+code=$(curl -s -o /dev/null -w '%{http_code}' --path-as-is localhost:4193/../package.json)
+[ "$code" = "404" ] || { echo "FAIL: GET /../package.json -> $code (traversal not blocked)"; exit 1; }
+code=$(curl -s -o /dev/null -w '%{http_code}' --path-as-is localhost:4193/%2e%2e/package.json)
+[ "$code" = "404" ] || { echo "FAIL: GET /%2e%2e/package.json -> $code (traversal not blocked)"; exit 1; }
+curl -sf localhost:4193/healthz | grep -q '"ok":true' || { echo "FAIL: healthz not json"; exit 1; }
+echo PASS

package/tests/checks/vocab.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmpdir=$(mktemp -d); trap 'rm -rf "$tmpdir"' EXIT
+tmp="$tmpdir/bad-vocab-aliases.yaml"
+VOCAB_TMP="$tmp" node --input-type=module -e '
+import { loadVocab, resolveTerm } from "./src/vocab.mjs";
+import { writeFileSync } from "fs";
+const v = loadVocab();
+const must = (c, m) => { if (!c) { console.error("FAIL: " + m); process.exit(1); } };
+must(v.facets.role.has("hero"), "role/hero present");
+must(resolveTerm(v, "role", "plans") === "offer", "alias plans -> offer");
+must(resolveTerm(v, "role", "offer") === "offer", "canonical passes through");
+must(resolveTerm(v, "feel", "neon") === null, "unknown term is null");
+must(resolveTerm(v, "role", "dark") === null, "term from another facet is null");
+must(Object.keys(v.facets).length === 5, "exactly five facets");
+const tmpFile = process.env.VOCAB_TMP;
+writeFileSync(tmpFile, "role: [hero]\nfeel: [dark]\nmotion: [reveal]\nsource: [own]\ntier: [inspiration]\naliases: pricing\n");
+try {
+  loadVocab(tmpFile);
+  console.error("FAIL: bad aliases did not throw");
+  process.exit(1);
+} catch (err) {
+  if (!err.message.includes("aliases")) {
+    console.error("FAIL: error message missing aliases: " + err.message);
+    process.exit(1);
+  }
+}
+'
+echo PASS

package/tests/fixtures/entry-ok/entry.md

@@ -0,0 +1,41 @@
+---
+slug: entry-ok
+title: Fixture hero with parallax bed
+tier: inspiration
+source:
+  kind: open
+  url: https://example.com
+  license: MIT
+captured:
+  method: frames
+  at: 2026-09-14
+  tool: wp-design-library@0.1.0
+media:
+  frames: 3
+  duration_ms: 120
+roles: [hero, closing]
+feel: [dark, depth]
+palette:
+  canvas: "#0b0f14"
+  ink: "#f4f6f8"
+  accent: "#6ea8ff"
+type:
+  display: geometric sans, light
+  body: same family
+motion:
+  devices: [parallax, reveal]
+  notes: bed moves slower than the frame
+ported_from: null
+---
+
+## What it does
+
+A dark hero whose background bed scrolls slower than the foreground frame.
+
+## Section roster
+
+hero, cta
+
+## Why it works
+
+Depth from one cheap device.

package/tests/fixtures/page/index.html

@@ -0,0 +1,47 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>measure fixture</title>
+<style>
+  * { box-sizing: border-box; }
+  html, body { margin: 0; }
+  body {
+    background: #0b1218;
+    color: #f2f5f8;
+    font-family: Arial;
+  }
+  h1 { font-family: Georgia; margin: 0 0 16px; }
+  p { font-family: Arial; margin: 0 0 16px; }
+  a, button { color: #7fb6ff; }
+  button { background: transparent; border: 1px solid currentColor; font: inherit; padding: 8px 16px; }
+  section { height: 1000px; padding: 48px; }
+
+  @keyframes reveal {
+    from { opacity: 0; transform: translateY(24px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+  .reveal-target {
+    animation: reveal linear both;
+    animation-timeline: view();
+    animation-range: entry 0% entry 40%;
+  }
+</style>
+</head>
+<body>
+  <section class="hero">
+    <h1>Hero heading</h1>
+    <p>Static hero copy that sets the scene.</p>
+    <a href="#learn">Learn more</a>
+  </section>
+  <section class="feature">
+    <h1>Feature heading</h1>
+    <p class="reveal-target">This paragraph reveals as it enters the viewport.</p>
+  </section>
+  <section class="closing">
+    <h1>Closing heading</h1>
+    <p>Closing copy.</p>
+    <button type="button">Get started</button>
+  </section>
+</body>
+</html>

package/tests/run.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -u
+cd "$(dirname "$0")/.."
+pass=0; fail=0
+for f in tests/checks/*.sh; do
+  if out=$(bash "$f" 2>&1); then pass=$((pass+1)); echo "PASS $f"
+  else fail=$((fail+1)); echo "FAIL $f"; echo "$out" | tail -20; fi
+done
+echo "PASS=$pass FAIL=$fail"
+[ "$fail" -eq 0 ]

package/vocab.yaml

@@ -0,0 +1,16 @@
+# Five facets, one level deep. A term is added by PR, never by an ingest.
+role: [hero, proof, feature, process, offer, testimonial, faq, closing, capability, explainer, page-head, footer]
+feel: [dark, light, premium, playful, editorial, brutalist, saas, depth, minimal, warm, cold]
+# The eleven data-motion device names from claude-wp-builder's motion.js,
+# then observed-only terms: things seen in reference not a device.
+motion: [reveal, pin, pan, wipe, kinetic, parallax, count, drift, tilt, magnet, spotlight, stagger, marquee, stack, tabs]
+source: [own, open, paid, public-site]
+tier: [inspiration, ported]
+aliases:
+  offer: [pricing, plans, tiers, offer-table]
+  proof: [logos, social-proof]
+  testimonial: [testimonials]
+  closing: [cta, call-to-action]
+  feature: [features]
+  dark: [dark-mode]
+  parallax: [depth-scroll]