@yojahny/wp-design-library 0.1.0

package/src/vocab.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import yaml from 'js-yaml';
+import { paths } from './paths.mjs';
+
+export const FACETS = ['role', 'feel', 'motion', 'source', 'tier'];
+
+export function loadVocab(file = paths().vocab) {
+  const raw = yaml.load(fs.readFileSync(file, 'utf8')) ?? {};
+  const facets = {};
+  for (const f of FACETS) {
+    if (!Array.isArray(raw[f])) throw new Error(`vocab.yaml: facet "${f}" must be a list`);
+    facets[f] = new Set(raw[f]);
+  }
+  const aliases = new Map();
+  if (raw.aliases !== undefined) {
+    if (typeof raw.aliases !== 'object' || Array.isArray(raw.aliases) || raw.aliases === null) {
+      throw new Error('vocab.yaml: aliases must map canonical term -> list');
+    }
+    for (const [canon, list] of Object.entries(raw.aliases)) {
+      if (!Array.isArray(list)) {
+        throw new Error(`vocab.yaml: aliases.${canon} must be list`);
+      }
+      for (const a of list) aliases.set(a, canon);
+    }
+  }
+  return { facets, aliases };
+}
+
+export function resolveTerm(vocab, facet, term) {
+  const set = vocab.facets[facet];
+  if (!set) return null;
+  const canon = vocab.aliases.get(term) ?? term;
+  return set.has(canon) ? canon : null;
+}

package/tests/README.md

@@ -0,0 +1,21 @@
+# Check ports
+
+A check that starts `serve --http` picks its own `PORT`, unique across the suite, so
+checks can run concurrently without colliding on a listening socket.
+
+| Check | Port |
+|---|---|
+| fetch-on-start.sh | 4189 |
+| minors.sh | 4190 |
+| similar.sh | 4191 |
+| ui-build.sh | 4193 |
+| hygiene.sh | 4195 |
+| seed-sync.sh | 4196 |
+| docker.sh | 4198 |
+| http.sh | 4199 |
+
+A check that never calls `serve --http` (everything else under `tests/checks/`) needs
+no port; it exercises `add`/`export`/`index`/`check`/`save` directly or drives `serve`
+(no `--http`) over stdio.
+
+A new serve-based check takes the next free port below 4191.

package/tests/checks/cli-check.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+LIBRARY_DATA="$tmp" node bin/library.mjs check | grep -q "1/1 entries ok" || { echo "FAIL: clean corpus"; exit 1; }
+sed -i 's/kind: open/kind: paid/; s/tier: inspiration/tier: ported/' "$tmp/entries/entry-ok/entry.md"
+if LIBRARY_DATA="$tmp" node bin/library.mjs check >"$tmp/out" 2>&1; then echo "FAIL: gate not enforced by check"; exit 1; fi
+grep -q "entry-ok: licence gate" "$tmp/out" || { echo "FAIL: error line shape"; cat "$tmp/out"; exit 1; }
+mkdir -p "$tmp/entries/broken"; echo "no frontmatter here" > "$tmp/entries/broken/entry.md"
+if LIBRARY_DATA="$tmp" node bin/library.mjs check >"$tmp/out" 2>&1; then echo "FAIL: parse error not detected"; exit 1; fi
+grep -q "^broken: " "$tmp/out" || { echo "FAIL: parse error line shape"; cat "$tmp/out"; exit 1; }
+echo PASS

package/tests/checks/docker.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+command -v docker >/dev/null || { echo "SKIP: docker not installed"; exit 0; }
+docker build -q -t wp-design-library:check . >/dev/null
+cid=""; trap '[ -n "$cid" ] && docker stop "$cid" >/dev/null 2>&1 || true' EXIT
+cid=$(docker run -d --rm -e LIBRARY_TOKEN=t0k -p 4198:4180 wp-design-library:check)
+for i in $(seq 1 60); do curl -sf localhost:4198/healthz >/dev/null 2>&1 && break; sleep 1; done
+curl -sf localhost:4198/healthz | grep -q '"ok":true' || { echo "FAIL: container healthz"; docker logs "$cid"; exit 1; }
+echo PASS

package/tests/checks/entry.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+node --input-type=module -e '
+import { parseEntry, validateEntry } from "./src/entry.mjs";
+import { loadVocab } from "./src/vocab.mjs";
+const must = (c, m) => { if (!c) { console.error("FAIL: " + m); process.exit(1); } };
+const v = loadVocab();
+const e = parseEntry("tests/fixtures/entry-ok");
+must(e.slug === "entry-ok", "slug from frontmatter");
+must(e.body.includes("## Section roster"), "body parsed");
+let r = validateEntry(e, v);
+must(r.ok, "fixture validates: " + r.errors.join("; "));
+e.fm.roles = ["hero", "neon"];
+r = validateEntry(e, v);
+must(!r.ok && r.errors.some(x => x.includes("role") && x.includes("neon")), "unknown tag names facet and term");
+e.fm.roles = ["plans"];
+r = validateEntry(e, v);
+must(r.ok && e.fm.roles[0] === "offer", "alias resolved to canonical in place");
+e.fm.title = "";
+r = validateEntry(e, v);
+must(!r.ok && r.errors.some(x => x.includes("title")), "blank required field named");
+'
+
+# Test CRLF line endings support
+tmpdir=$(mktemp -d)
+trap "rm -rf $tmpdir" EXIT
+mkdir -p "$tmpdir/entry-ok"
+cp tests/fixtures/entry-ok/entry.md "$tmpdir/entry-ok/entry.md"
+sed -i "s/$/\r/" "$tmpdir/entry-ok/entry.md"
+cp tests/fixtures/entry-ok/strip.png "$tmpdir/entry-ok/strip.png"
+node --input-type=module -e "
+import { parseEntry, validateEntry } from './src/entry.mjs';
+import { loadVocab } from './src/vocab.mjs';
+const must = (c, m) => { if (!c) { console.error('FAIL: ' + m); process.exit(1); } };
+const v = loadVocab();
+const e = parseEntry('$tmpdir/entry-ok');
+must(e.slug === 'entry-ok', 'CRLF: slug parsed');
+must(validateEntry(e, v).ok, 'CRLF: validates');
+"
+
+# slug must equal the directory name
+mkdir -p "$tmpdir/other-name"
+cp tests/fixtures/entry-ok/entry.md tests/fixtures/entry-ok/strip.png "$tmpdir/other-name/"
+node --input-type=module -e "
+import { parseEntry, validateEntry } from './src/entry.mjs';
+import { loadVocab } from './src/vocab.mjs';
+const must = (c, m) => { if (!c) { console.error('FAIL: ' + m); process.exit(1); } };
+const v = loadVocab();
+const e = parseEntry('$tmpdir/other-name');
+const r = validateEntry(e, v);
+must(!r.ok && r.errors.some(x => x.includes('slug: must equal')), 'slug mismatch refused');
+"
+
+echo PASS

package/tests/checks/export.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+node_bin=$(command -v node)
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+LIBRARY_DATA="$tmp" node bin/library.mjs export > "$tmp/out.tar" 2>"$tmp/err"
+tar -tf "$tmp/out.tar" | grep -q 'entries/entry-ok/entry.md' || { echo "FAIL: tar content"; exit 1; }
+grep -q "export: 1 entries" "$tmp/err" || { echo "FAIL: count on stderr"; exit 1; }
+
+emptybin="$tmp/emptybin"; mkdir -p "$emptybin"
+code=0
+PATH="$emptybin" LIBRARY_DATA="$tmp" "$node_bin" bin/library.mjs export > "$tmp/out2.tar" 2>"$tmp/err2" || code=$?
+[ "$code" -ne 0 ] || { echo "FAIL: missing tar should exit non-zero"; exit 1; }
+grep -q "tar is required" "$tmp/err2" || { echo "FAIL: missing tar message"; cat "$tmp/err2"; exit 1; }
+echo PASS

package/tests/checks/fetch-on-start.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# LIBRARY_FETCH_MODELS=1 makes `serve --http` attempt a model fetch between the seed
+# sync and the index build; the attempt is logged and never blocks the server from
+# coming up, even when it fails. No network download is asserted here: LIBRARY_MODELS
+# sits under a regular file, so fetchModels fails fast on its first cache write
+# (ENOTDIR, for any uid including root) instead of pulling real model weights.
+# (HF_HUB_OFFLINE=1 is also set for intent, but @huggingface/transformers does not
+# honour it — see task-7-report.md.)
+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/data"; : > "$tmp/notadir"
+export LIBRARY_SEED="$tmp/noseed" LIBRARY_DATA="$tmp/data" LIBRARY_MODELS="$tmp/notadir/models" LIBRARY_EMBED=stub LIBRARY_TOKEN=t0k HF_HUB_OFFLINE=1
+
+LIBRARY_FETCH_MODELS=1 PORT=4189 node bin/library.mjs serve --http >"$tmp/log" 2>&1 & pid=$!
+for i in $(seq 1 60); do curl -sf localhost:4189/healthz >/dev/null 2>&1 && break; sleep 0.2; done
+curl -sf localhost:4189/healthz | grep -q '"ok":true' || { echo "FAIL: healthz not up after a model fetch attempt"; cat "$tmp/log"; exit 1; }
+grep -q "models: fetch start" "$tmp/log" || { echo "FAIL: fetch-start line missing with LIBRARY_FETCH_MODELS=1"; cat "$tmp/log"; exit 1; }
+kill $pid; wait $pid 2>/dev/null || true; pid=""
+
+LIBRARY_FETCH_MODELS=0 PORT=4189 node bin/library.mjs serve --http >"$tmp/log2" 2>&1 & pid=$!
+for i in $(seq 1 60); do curl -sf localhost:4189/healthz >/dev/null 2>&1 && break; sleep 0.2; done
+curl -sf localhost:4189/healthz | grep -q '"ok":true' || { echo "FAIL: healthz not up with LIBRARY_FETCH_MODELS=0"; cat "$tmp/log2"; exit 1; }
+grep -q "models: fetch" "$tmp/log2" && { echo "FAIL: fetch line present with LIBRARY_FETCH_MODELS=0"; cat "$tmp/log2"; exit 1; }
+kill $pid; wait $pid 2>/dev/null || true; pid=""
+echo PASS

package/tests/checks/frames-dense.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/f" "$tmp/data/entries"
+node --input-type=module -e 'import sharp from "sharp"; for (let i = 0; i < 60; i++) await sharp({create:{width:40,height:20,channels:3,background:{r:i*4,g:0,b:0}}}).png().toFile(process.argv[1] + "/" + i + ".png")' "$tmp/f"
+ffmpeg -y -loglevel error -framerate 10 -i "$tmp/f/%d.png" -loop 0 -lossless 1 "$tmp/sixty.webp"   # 60 frames, 100 ms each = 6 s
+node --input-type=module -e '
+import { sampleFrames } from "./src/ingest/frames.mjs";
+const must = (c, m) => { if (!c) { console.error("FAIL: " + m); process.exit(1); } };
+let r = await sampleFrames(process.argv[1], process.argv[2]);
+must(r.frames === 60, "frame count " + r.frames);
+must(r.sampled.length === 12, "6 s → 12 frames by duration, got " + r.sampled.length);
+r = await sampleFrames(process.argv[1], process.argv[2], { frames: 36 });
+must(r.sampled.length === 36, "explicit 36");
+must(r.sampled[0] === 0 && r.sampled[35] === 59, "spread first..last");
+r = await sampleFrames(process.argv[1], process.argv[3], { frames: 1 });
+must(r.sampled.length === 2, "frames:1 must not divide by zero, got " + r.sampled.length);
+' "$tmp/sixty.webp" "$tmp/strip.png" "$tmp/strip1.png"
+node --input-type=module -e "import sharp from 'sharp'; const m = await sharp('$tmp/strip.png').metadata(); if (m.width !== 40*6) { console.error('FAIL: 36 tiles use 6 columns, width ' + m.width); process.exit(1); }"
+# --frames 1 is invalid at the CLI too (schema requires 6..36) and must refuse before ingesting
+if out=$(LIBRARY_DATA="$tmp/data" node bin/library.mjs add tests/fixtures/three-frame.webp --slug x --title x --source own --license x --frames 1 2>&1); then
+  echo "FAIL: --frames 1 should refuse and exit non-zero"; echo "$out"; exit 1
+fi
+echo "$out" | grep -q '"refused"' || { echo "FAIL: --frames 1 refusal missing refused field"; echo "$out"; exit 1; }
+echo PASS

package/tests/checks/http.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; trap 'rm -rf "$tmp"; kill $pid 2>/dev/null || true' EXIT  # LIBRARY_SEED isolates the check from the repo corpus
+mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+LIBRARY_DATA="$tmp" node bin/library.mjs index >/dev/null 2>&1
+# refuses without token
+if LIBRARY_DATA="$tmp" PORT=4199 timeout 5 node bin/library.mjs serve --http >"$tmp/o" 2>&1; then echo "FAIL: started without token"; exit 1; fi
+grep -q "LIBRARY_TOKEN" "$tmp/o" || { echo "FAIL: refusal names LIBRARY_TOKEN"; exit 1; }
+LIBRARY_DATA="$tmp" PORT=4199 LIBRARY_TOKEN=t0k node bin/library.mjs serve --http >"$tmp/log" 2>&1 & pid=$!
+for i in $(seq 1 30); do curl -sf localhost:4199/healthz >/dev/null 2>&1 && break; sleep 0.2; done
+curl -sf localhost:4199/healthz | grep -q '"entries":1' || { echo "FAIL: healthz"; cat "$tmp/log"; exit 1; }
+code=$(curl -s -o /dev/null -w '%{http_code}' -X POST localhost:4199/mcp -H 'content-type: application/json' -d '{}')
+[ "$code" = "401" ] || { echo "FAIL: expected 401 without bearer, got $code"; exit 1; }
+body='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'
+curl -s -X POST localhost:4199/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$body" \
+  | grep -q 'wp-design-library' || { echo "FAIL: initialize over http"; exit 1; }
+# http add is confined to <data>/inbox
+body_add='{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add","arguments":{"input":"/etc/hostname","slug":"x","title":"x","source":{"kind":"open","license":"MIT"}}}}'
+curl -s -X POST localhost:4199/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$body_add" \
+  | grep -q '"refused"' || { echo "FAIL: http add did not refuse a file outside the inbox"; exit 1; }
+echo PASS

package/tests/checks/hygiene.sh

@@ -0,0 +1,29 @@
+#!/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" "$tmp/inbox" "$tmp/outside"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+# version comes from package.json
+v=$(node -p "require('./package.json').version")
+grep -rEq "(version|tool)[^\n]*['\"][0-9]+\.[0-9]+\.[0-9]+['\"]" src/ && { echo "FAIL: hard-coded version literal in src/"; exit 1; }
+LIBRARY_DATA="$tmp" PORT=4195 LIBRARY_TOKEN=t0k node bin/library.mjs serve --http >"$tmp/log" 2>&1 & pid=$!
+for i in $(seq 1 30); do curl -sf localhost:4195/healthz >/dev/null 2>&1 && break; sleep 0.2; done
+curl -sf localhost:4195/healthz | grep -q "\"version\":\"$v\"" || { echo "FAIL: healthz version"; exit 1; }
+# a token of a different length is refused without a 500
+code=$(curl -s -o /dev/null -w '%{http_code}' -X POST localhost:4195/mcp -H 'authorization: Bearer t0' -H 'content-type: application/json' -d '{}')
+[ "$code" = "401" ] || { echo "FAIL: short token → $code"; exit 1; }
+# symlink inside inbox pointing outside is refused over http
+cp tests/fixtures/three-frame.webp "$tmp/outside/real.webp"; ln -s "$tmp/outside/real.webp" "$tmp/inbox/link.webp"
+init='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}'
+curl -s -X POST localhost:4195/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\":\"add\",\"arguments\":{\"input\":\"$tmp/inbox/link.webp\",\"slug\":\"lnk\",\"title\":\"x\",\"source\":{\"kind\":\"open\",\"license\":\"MIT\"}}}}"
+curl -s -X POST localhost:4195/mcp -H 'authorization: Bearer t0k' -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$call" | grep -q '"refused"' || { echo "FAIL: symlink escape not refused"; exit 1; }
+# atomic rebuild: no partial index visible; the temp file is gone afterwards
+LIBRARY_DATA="$tmp" node bin/library.mjs index >/dev/null 2>&1
+[ ! -e "$tmp/.library/index.sqlite.tmp" ] || { echo "FAIL: temp index left behind"; exit 1; }
+grep -q "renameSync" src/index/build.mjs || { echo "FAIL: build is not rename-based"; exit 1; }
+# a failed rebuild (renameSync onto a directory) closes the tmp handle, removes the tmp file, and exits non-zero
+rm -rf "$tmp/.library/index.sqlite"; mkdir -p "$tmp/.library/index.sqlite"
+LIBRARY_DATA="$tmp" node bin/library.mjs index >/dev/null 2>&1 && { echo "FAIL: index build over a directory target exited 0"; exit 1; }
+[ ! -e "$tmp/.library/index.sqlite.tmp" ] || { echo "FAIL: temp index left behind after a failed rebuild"; exit 1; }
+echo PASS

package/tests/checks/inbox.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/inbox" "$tmp/entries"
+cp tests/fixtures/three-frame.webp "$tmp/inbox/Acme Dark Hero.webp"
+cp tests/fixtures/three-frame.webp "$tmp/inbox/with-sidecar.webp"
+echo '{"kind":"open","license":"MIT","url":"https://x.example","title":"Sidecar title"}' > "$tmp/inbox/with-sidecar.webp.json"
+cp tests/fixtures/three-frame.webp "$tmp/inbox/no-meta.webp"
+out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add --inbox --source public-site --license "description only" 2>&1)
+echo "$out" | grep -q '"slug":"acme-dark-hero","status":"drafted"' || { echo "FAIL: slug from filename"; echo "$out"; exit 1; }
+grep -q "title: Sidecar title" "$tmp/entries/with-sidecar/entry.md" || { echo "FAIL: sidecar title"; exit 1; }
+grep -q "kind: open" "$tmp/entries/with-sidecar/entry.md" || { echo "FAIL: sidecar kind"; exit 1; }
+grep -q "kind: public-site" "$tmp/entries/no-meta/entry.md" || { echo "FAIL: flags as fallback"; exit 1; }
+out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add --inbox --source public-site --license x 2>&1)
+echo "$out" | grep -c '"status":"skipped"' | grep -q '^3$' || { echo "FAIL: second run skips all three"; echo "$out"; exit 1; }
+out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add --inbox 2>&1 || true)   # no flags, no sidecar → refused, not crash
+cp tests/fixtures/three-frame.webp "$tmp/inbox/fourth.webp"
+out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add --inbox 2>&1 || true)
+echo "$out" | grep -q '"slug":"fourth","status":"refused"' || { echo "FAIL: missing metadata is a per-file refusal"; echo "$out"; exit 1; }
+
+cp tests/fixtures/three-frame.webp "$tmp/inbox/bad-side.webp"
+echo 'null' > "$tmp/inbox/bad-side.webp.json"
+out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add --inbox --source public-site --license x 2>&1 || true)
+echo "$out" | grep -q '"slug":"bad-side","status":"refused"' || { echo "FAIL: non-object sidecar is a per-file refusal"; echo "$out"; exit 1; }
+echo "$out" | grep -c '^{' | grep -q '^5$' || { echo "FAIL: loop died instead of reporting every file"; echo "$out"; exit 1; }
+echo PASS

package/tests/checks/index-degrade.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+# models absent → fts only, skip reported, exit 0
+out=$(LIBRARY_DATA="$tmp" LIBRARY_EMBED= node bin/library.mjs index 2>&1)
+echo "$out" | grep -qE "arms: fts([^,]|$)" || { echo "FAIL: arms without models; got: $out"; exit 1; }
+echo "$out" | grep -q "embeddings: skipped (models absent" || { echo "FAIL: skip line; got: $out"; exit 1; }
+# stub → both arms, vectors stored with the right dims
+out=$(LIBRARY_DATA="$tmp" LIBRARY_EMBED=stub node bin/library.mjs index 2>&1)
+echo "$out" | grep -q "arms: fts,vec" || { echo "FAIL: arms with stub; got: $out"; exit 1; }
+LIBRARY_DATA="$tmp" node --input-type=module -e '
+import { openIndex } from "./src/index/query.mjs"; import { paths } from "./src/paths.mjs";
+const db = openIndex(paths().index);
+const must = (c, m) => { if (!c) { console.error("FAIL: " + m); process.exit(1); } };
+must(db.vec === true, "sqlite-vec loaded");
+must(db.prepare("select count(*) c from vec_text").get().c === 1, "one text vector");
+must(db.prepare("select count(*) c from vec_image").get().c === 1, "one image vector");
+must(db.prepare("select vec_length(embedding) n from vec_text").get().n === 384, "text dims 384");
+must(db.prepare("select vec_length(embedding) n from vec_image").get().n === 768, "image dims 768");
+'
+# stub is deterministic
+LIBRARY_DATA="$tmp" node --input-type=module -e '
+import { getEmbedder } from "./src/index/embed.mjs";
+const e = await getEmbedder({ models: "/nonexistent", mode: "stub" });
+const a = await e.text("dark hero"), b = await e.text("dark hero"), c = await e.text("light hero");
+const must = (x, m) => { if (!x) { console.error("FAIL: " + m); process.exit(1); } };
+must(a.length === 384 && a.every((v, i) => v === b[i]), "stub deterministic");
+must(!a.every((v, i) => v === c[i]), "stub distinguishes texts");
+'
+echo PASS

package/tests/checks/index.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"
+cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+cp -r tests/fixtures/entry-ok "$tmp/entries/entry-two"
+sed -i 's/slug: entry-ok/slug: entry-two/; s/Fixture hero with parallax bed/Pricing table with three plans/; s/roles: \[hero, closing\]/roles: [offer]/; s/at: 2026-09-14/at: 2026-01-15/' "$tmp/entries/entry-two/entry.md"
+cp -r tests/fixtures/entry-ok "$tmp/entries/entry-bad"
+sed -i 's/slug: entry-ok/slug: entry-bad/; s/kind: open/kind: paid/; s/tier: inspiration/tier: ported/' "$tmp/entries/entry-bad/entry.md"
+LIBRARY_DATA="$tmp" node bin/library.mjs index >"$tmp/out" 2>&1
+grep -q "indexed 2" "$tmp/out" || { echo "FAIL: count"; cat "$tmp/out"; exit 1; }
+grep -q "refused entry-bad" "$tmp/out" || { echo "FAIL: refusal not reported"; cat "$tmp/out"; exit 1; }
+LIBRARY_DATA="$tmp" node --input-type=module -e '
+import { openIndex, search, getEntry } from "./src/index/query.mjs";
+import { paths } from "./src/paths.mjs";
+const must = (c, m) => { if (!c) { console.error("FAIL: " + m); process.exit(1); } };
+const db = openIndex(paths().index);
+let r = await search(db, { query: "parallax" });
+must(r.arms.length === 1 && r.arms[0] === "fts", "arms reports fts only");
+must(r.hits[0].slug === "entry-ok", "keyword hit ranks first");
+r = await search(db, { query: "plans" });
+must(r.hits.some(h => h.slug === "entry-two"), "title matched");
+r = await search(db, { query: "", filters: { role: ["offer"] } });
+must(r.hits.length === 1 && r.hits[0].slug === "entry-two", "facet filter alone");
+r = await search(db, { query: "", filters: { role: ["hero"], feel: ["depth"] } });
+must(r.hits.length === 1 && r.hits[0].slug === "entry-ok", "AND across facets");
+r = await search(db, { query: "" });
+must(r.hits[0].slug === "entry-ok", "newest first");
+r = await search(db, { query: "parallax", filters: { role: ["offer"] } });
+must(r.hits.length === 1 && r.hits[0].slug === "entry-two", "query and facet filter combined");
+const e = getEntry(db, "entry-two");
+must(e && e.fm.roles[0] === "offer" && e.body.includes("Section roster"), "getEntry returns fm and body");
+must(getEntry(db, "nope") === null, "missing slug is null");
+'
+echo PASS

package/tests/checks/ingest-mp4.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+command -v ffmpeg >/dev/null || { echo "SKIP: ffmpeg not installed"; exit 0; }
+NODE=$(command -v node)
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/f" "$tmp/entries"
+for i in $(seq 0 39); do node --input-type=module -e "import sharp from 'sharp'; await sharp({create:{width:64,height:32,channels:3,background:{r:0,g:$((i*6)),b:0}}}).png().toFile('$tmp/f/$i.png')"; done
+ffmpeg -y -loglevel error -framerate 10 -i "$tmp/f/%d.png" -pix_fmt yuv420p "$tmp/clip.mp4"    # 4 s
+out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add "$tmp/clip.mp4" --slug clip --title Clip --source own --license "own work")
+echo "$out" | grep -q '"frames":8' || { echo "FAIL: 4 s at 2 fps → 8 frames; got: $out"; exit 1; }
+[ -f "$tmp/entries/clip/strip.png" ] || { echo "FAIL: strip"; exit 1; }
+# absent ffmpeg is a refusal naming the binary
+out=$(PATH="$tmp/nobin" LIBRARY_DATA="$tmp" "$NODE" bin/library.mjs add "$tmp/clip.mp4" --slug clip2 --title Clip --source own --license x 2>&1 || true)
+echo "$out" | grep -q 'ffmpeg is required' || { echo "FAIL: refusal names ffmpeg; got: $out"; exit 1; }
+[ ! -e "$tmp/entries/clip2" ] || { echo "FAIL: refused add (absent ffmpeg) created entries/clip2"; exit 1; }
+# a broken/unreadable video is a named refusal too, and never leaks its temp frame dir
+sysTmp=$(node -p "require('os').tmpdir()")
+before=$(find "$sysTmp" -maxdepth 1 -name 'wpdl-*' 2>/dev/null | sort)
+: > "$tmp/broken.mp4"
+if out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add "$tmp/broken.mp4" --slug broken --title Broken --source own --license x 2>&1); then
+  echo "FAIL: broken mp4 should refuse and exit non-zero"; echo "$out"; exit 1
+fi
+echo "$out" | grep -q '"refused":"ffmpeg could not read broken.mp4' || { echo "FAIL: broken mp4 refusal wording; got: $out"; exit 1; }
+after=$(find "$sysTmp" -maxdepth 1 -name 'wpdl-*' 2>/dev/null | sort)
+[ "$before" = "$after" ] || { echo "FAIL: temp wpdl- dir leaked; before=[$before] after=[$after]"; exit 1; }
+[ ! -e "$tmp/entries/broken" ] || { echo "FAIL: refused add (broken.mp4) created entries/broken"; exit 1; }
+# webm without a container duration (browser MediaRecorder style) is read from the video stream
+VPX_ENC=""
+if ffmpeg -encoders 2>/dev/null | grep -q ' libvpx '; then
+  VPX_ENC=libvpx
+elif ffmpeg -encoders 2>/dev/null | grep -q ' libvpx-vp9 '; then
+  VPX_ENC=libvpx-vp9
+fi
+if [ -z "$VPX_ENC" ]; then
+  echo "SKIP: webm-without-duration case (no libvpx/libvpx-vp9 encoder in this ffmpeg build)"
+  echo "  encoders seen: $(ffmpeg -encoders 2>/dev/null | grep -i vp || true)"
+else
+  ffmpeg -y -loglevel error -framerate 10 -i "$tmp/f/%d.png" -c:v "$VPX_ENC" -f webm pipe:1 > "$tmp/piped.webm"
+  dur=$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 -i "$tmp/piped.webm")
+  [ "$dur" = "N/A" ] || { echo "FAIL: fixture webm unexpectedly has a container duration ($dur); no longer exercises the fallback"; exit 1; }
+  out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add "$tmp/piped.webm" --slug webmclip --title WebmClip --source own --license "own work")
+  echo "$out" | grep -q '"frames":8' || { echo "FAIL: duration-less webm should still yield 8 frames (4s @ duration rule); got: $out"; exit 1; }
+  ms=$(grep -o 'duration_ms: [0-9]*' "$tmp/entries/webmclip/entry.md" | grep -o '[0-9]*')
+  [ -n "$ms" ] && [ "$ms" -ge 3950 ] && [ "$ms" -le 4050 ] || { echo "FAIL: media.duration_ms not ~4000; got: $ms"; exit 1; }
+fi
+echo PASS

package/tests/checks/ingest.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"
+out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add tests/fixtures/three-frame.webp --slug fx --title "Fixture" --source open --license MIT)
+echo "$out" | grep -q '"frames":3' || { echo "FAIL: frame count"; echo "$out"; exit 1; }
+echo "$out" | grep -q '"blanks":\["roles","feel","motion.devices","motion.notes","type.display","type.body","body","palette.canvas","palette.ink","palette.accent"\]' || { echo "FAIL: blanks list"; echo "$out"; exit 1; }
+[ -f "$tmp/entries/fx/strip.png" ] || { echo "FAIL: strip.png"; exit 1; }
+grep -q '^roles: \[\]' "$tmp/entries/fx/entry.md" || { echo "FAIL: draft has empty roles"; exit 1; }
+# add refuses to overwrite an existing draft without force, and exits 1
+if LIBRARY_DATA="$tmp" node bin/library.mjs add tests/fixtures/three-frame.webp --slug fx --title "Fixture" --source open --license MIT >/dev/null 2>&1; then
+  echo "FAIL: refused add should exit 1"; exit 1
+fi
+out2=$(LIBRARY_DATA="$tmp" node bin/library.mjs add tests/fixtures/three-frame.webp --slug fx --title "Fixture" --source open --license MIT) || true
+echo "$out2" | grep -q '"refused"' || { echo "FAIL: re-add without force did not refuse"; echo "$out2"; exit 1; }
+# --force overwrites; this resets the draft, so it must happen before the fill step
+out3=$(LIBRARY_DATA="$tmp" node bin/library.mjs add tests/fixtures/three-frame.webp --slug fx --title "Fixture" --source open --license MIT --force)
+echo "$out3" | grep -q '"frames":3' || { echo "FAIL: force re-add did not succeed"; echo "$out3"; exit 1; }
+# save refuses the unfilled draft
+if LIBRARY_DATA="$tmp" node bin/library.mjs save fx >"$tmp/s" 2>&1; then echo "FAIL: saved a draft with blanks"; exit 1; fi
+grep -q "roles: required, blank" "$tmp/s" || { echo "FAIL: refusal names the blank"; cat "$tmp/s"; exit 1; }
+grep -q '"refused"' "$tmp/s" || { echo "FAIL: refusal missing refused field"; cat "$tmp/s"; exit 1; }
+# fill it and save
+python3 - "$tmp/entries/fx/entry.md" <<'EOF'
+import io,sys
+p=sys.argv[1]; s=io.open(p,encoding="utf-8").read()
+s=s.replace("roles: []","roles: [hero]").replace("feel: []","feel: [dark]")
+s=s.replace("  devices: []","  devices: [parallax]").replace("  notes: ''","  notes: bed lags the frame")
+s=s.replace("  display: ''","  display: sans").replace("  body: ''","  body: sans")
+s=s.replace("  canvas: ''","  canvas: '#0b0f14'").replace("  ink: ''","  ink: '#f4f6f8'").replace("  accent: ''","  accent: '#6ea8ff'")
+s+="\n## What it does\n\nx\n\n## Section roster\n\nhero\n\n## Why it works\n\ny\n"
+io.open(p,"w",encoding="utf-8").write(s)
+EOF
+LIBRARY_DATA="$tmp" node bin/library.mjs save fx | grep -q '"ok":true' || { echo "FAIL: save"; exit 1; }
+LIBRARY_DATA="$tmp" node --input-type=module -e '
+import { openIndex, getEntry } from "./src/index/query.mjs"; import { paths } from "./src/paths.mjs";
+const db = openIndex(paths().index); if (!getEntry(db, "fx")) { console.error("FAIL: not reindexed"); process.exit(1); }'
+echo PASS

package/tests/checks/licence-gate.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+node --input-type=module -e '
+import { parseEntry, validateEntry } from "./src/entry.mjs";
+import { loadVocab } from "./src/vocab.mjs";
+const must = (c, m) => { if (!c) { console.error("FAIL: " + m); process.exit(1); } };
+const v = loadVocab();
+for (const kind of ["paid", "public-site"]) {
+  const e = parseEntry("tests/fixtures/entry-ok");
+  e.fm.tier = "ported"; e.fm.source.kind = kind; e.fm.ported_from = "entry-ok";
+  const r = validateEntry(e, v);
+  must(!r.ok && r.errors.some(x => x.includes("licence") && x.includes(kind)), "ported+" + kind + " refused");
+}
+for (const kind of ["own", "open"]) {
+  const e = parseEntry("tests/fixtures/entry-ok");
+  e.fm.tier = "ported"; e.fm.source.kind = kind; e.fm.ported_from = "entry-ok";
+  must(validateEntry(e, v).ok, "ported+" + kind + " allowed");
+}
+const e = parseEntry("tests/fixtures/entry-ok");
+e.fm.tier = "ported"; e.fm.source.kind = "own";
+must(!validateEntry(e, v).ok, "ported without ported_from refused");
+'
+echo PASS

package/tests/checks/mcp-stdout.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; trap 'rm -rf "$tmp"' EXIT  # LIBRARY_SEED isolates the check from the repo corpus
+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":"tools/list"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search","arguments":{"query":"parallax"}}}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search","arguments":{"query":"","filters":{"role":["cta"]}}}}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"search","arguments":{"query":"","filters":{"role":["neon"]}}}}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"save_entry","arguments":{"slug":"../entry-ok"}}}'
+  sleep 1
+} | LIBRARY_DATA="$tmp" timeout 10 node bin/library.mjs serve >"$tmp/out" 2>"$tmp/err" || true
+# every stdout line must be JSON-RPC
+while IFS= read -r line; do
+  [ -z "$line" ] && continue
+  printf '%s' "$line" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const j=JSON.parse(s);if(j.jsonrpc!=="2.0")process.exit(1)})' \
+    || { echo "FAIL: non-JSON-RPC on stdout: $line"; exit 1; }
+done <"$tmp/out"
+grep -q '"name":"search"' "$tmp/out" || { echo "FAIL: search not listed"; exit 1; }
+grep -q '"name":"get_entry"' "$tmp/out" || { echo "FAIL: get_entry not listed"; exit 1; }
+grep -q '"name":"add"' "$tmp/out" || { echo "FAIL: add not listed"; exit 1; }
+grep -q '"name":"save_entry"' "$tmp/out" || { echo "FAIL: save_entry not listed"; exit 1; }
+grep -q 'entry-ok' "$tmp/out" || { echo "FAIL: search hit"; exit 1; }
+grep -q '"arms":\["fts"\]' "$tmp/out" || { echo "FAIL: arms reported"; exit 1; }
+grep '"id":4' "$tmp/out" | grep -q 'entry-ok' || { echo "FAIL: role alias cta did not hit entry-ok"; exit 1; }
+grep '"id":5' "$tmp/out" | grep -q '"unknown":\[{"facet":"role","term":"neon"}\]' || { echo "FAIL: unknown filter term not reported"; exit 1; }
+grep '"id":6' "$tmp/out" | grep -q '"isError":true' || { echo "FAIL: save_entry did not reject a path-traversal slug"; exit 1; }
+echo PASS

package/tests/checks/measure.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+[ -n "${CHROME_PATH:-}" ] || CHROME_PATH=$(command -v google-chrome || command -v chromium || true)
+[ -n "$CHROME_PATH" ] || { echo "SKIP: no chrome/chromium found"; exit 0; }
+export CHROME_PATH
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"
+
+out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add "file://$PWD/tests/fixtures/page/index.html" --slug fx --title Fx --source own --license x --record)
+echo "$out" | grep -q '"blanks"' || { echo "FAIL: add did not draft"; echo "$out"; exit 1; }
+# a measured add fills palette/type mechanically, so they must not come back in the
+# blanks list a Claude session is told it still needs to fill; judgement fields still must.
+echo "$out" | grep -q '"roles"' || { echo "FAIL: blanks missing roles"; echo "$out"; exit 1; }
+if echo "$out" | grep -q '"palette.canvas"'; then
+  echo "FAIL: blanks still lists palette.canvas after a measured add"; echo "$out"; exit 1
+fi
+
+mjson="$tmp/entries/fx/measure.json"
+[ -f "$mjson" ] || { echo "FAIL: measure.json missing"; echo "$out"; exit 1; }
+python3 - "$mjson" <<'EOF'
+import json, os, sys
+m = json.load(open(sys.argv[1]))
+def fail(msg): print("FAIL: " + msg); sys.exit(1)
+if m["tokens"]["canvas"] != "#0b1218": fail("canvas got " + str(m["tokens"]["canvas"]))
+if m["tokens"]["ink"] != "#f2f5f8": fail("ink got " + str(m["tokens"]["ink"]))
+if m["tokens"]["accent"] != "#7fb6ff": fail("accent got " + str(m["tokens"]["accent"]))
+if "Georgia" not in m["tokens"]["fontDisplay"]: fail("fontDisplay got " + str(m["tokens"]["fontDisplay"]))
+ok = any(a.get("timeline") == "view" and "entry" in (a.get("range") or "")
+         for s in m["sections"] for a in s.get("animations", []))
+if not ok: fail("no section has a view-timeline animation with an entry range")
+shot = os.path.join(os.path.dirname(sys.argv[1]), m["screenshots"]["1440"])
+if not os.path.isfile(shot): fail("screenshots[1440] file missing: " + shot)
+EOF
+
+[ -f "$tmp/entries/fx/strip.png" ] || { echo "FAIL: strip.png missing"; exit 1; }
+grep -q "  method: both" "$tmp/entries/fx/entry.md" || { echo "FAIL: draft captured.method not both"; cat "$tmp/entries/fx/entry.md"; exit 1; }
+grep -q "canvas: '#0b1218'" "$tmp/entries/fx/entry.md" || { echo "FAIL: draft palette.canvas not filled"; cat "$tmp/entries/fx/entry.md"; exit 1; }
+
+# --record composites 12 stops: compositeStrip uses 3 columns under 12 tiles, so the
+# strip must be 1440*3 wide and at least two single-screenshot heights tall — a strip
+# that is just the lone 1440 screenshot (the non-record fallback) would fail both.
+node --input-type=module -e "
+import sharp from 'sharp';
+const strip = await sharp('$tmp/entries/fx/strip.png').metadata();
+const single = await sharp('$tmp/entries/fx/screen-1440.png').metadata();
+if (strip.width !== 1440 * 3) { console.error('FAIL: 12-tile strip width ' + strip.width + ', expected ' + (1440 * 3)); process.exit(1); }
+if (strip.height < single.height * 2) { console.error('FAIL: strip height ' + strip.height + ' not at least twice the single screenshot height ' + single.height); process.exit(1); }
+"
+
+# refresh re-measures and rewrites captured.at
+out=$(LIBRARY_DATA="$tmp" node bin/library.mjs refresh fx)
+echo "$out" | grep -q '"ok":true' || { echo "FAIL: refresh did not succeed"; echo "$out"; exit 1; }
+today=$(date +%Y-%m-%d)
+grep -Eq "^  at: '?$today'?\$" "$tmp/entries/fx/entry.md" || { echo "FAIL: captured.at not rewritten to today"; cat "$tmp/entries/fx/entry.md"; exit 1; }
+
+# add without --record: strip is just the 1440 screenshot, method is measured (not both)
+out=$(LIBRARY_DATA="$tmp" node bin/library.mjs add "file://$PWD/tests/fixtures/page/index.html" --slug fx-plain --title FxPlain --source own --license x)
+echo "$out" | grep -q '"blanks"' || { echo "FAIL: add without --record did not draft"; echo "$out"; exit 1; }
+grep -q "  method: measured" "$tmp/entries/fx-plain/entry.md" || { echo "FAIL: draft captured.method not measured"; cat "$tmp/entries/fx-plain/entry.md"; exit 1; }
+node --input-type=module -e "
+import sharp from 'sharp';
+const strip = await sharp('$tmp/entries/fx-plain/strip.png').metadata();
+if (strip.width !== 1440) { console.error('FAIL: non-record strip width ' + strip.width + ', expected 1440'); process.exit(1); }
+"
+
+# chrome unavailable: add refuses, exits 1, nothing left under entries/
+if out=$(CHROME_PATH=/nonexistent LIBRARY_DATA="$tmp" node bin/library.mjs add "file://$PWD/tests/fixtures/page/index.html" --slug fx2 --title Fx2 --source own --license x 2>&1); then
+  echo "FAIL: add with an unavailable chrome should refuse and exit non-zero"; echo "$out"; exit 1
+fi
+echo "$out" | grep -q '"refused"' || { echo "FAIL: refusal missing refused field"; echo "$out"; exit 1; }
+echo "$out" | grep -qi chrome || { echo "FAIL: refusal does not mention chrome"; echo "$out"; exit 1; }
+[ -d "$tmp/entries/fx2" ] && { echo "FAIL: refused add left a directory under entries/"; exit 1; }
+
+echo PASS