@yojahny/wp-design-library 0.1.0 → 0.2.0

package/Dockerfile

@@ -14,6 +14,10 @@ RUN if [ "$WITH_CHROME" = "1" ] && [ "$(dpkg --print-architecture)" = "amd64" ];
 WORKDIR /app
 COPY package*.json ./
 RUN npm ci --omit=dev
+# The vector arm and URL measurement are optional peers (npm ci skips an optional
+# peer by design); the hosted image wants both, so install them explicitly at the
+# pins package.json declares.
+RUN npm install --no-save --no-audit --no-fund @huggingface/transformers@4.2.0 playwright-core@1.63.0
 COPY . .
 # Vector-search models are not baked into the image: they land on the /data volume
 # under models/ and are fetched at container start when LIBRARY_FETCH_MODELS=1.

package/README.md

@@ -24,9 +24,28 @@ only for `own` or `open` sources; the licence gate refuses anything else.
 ```bash
 git clone git@github.com:yojahny55/wp-design-library.git
 cd wp-design-library && npm install
-npm test          # 24 checks, all should PASS (measure.sh SKIPs without a system Chrome)
+npm test          # 25 checks, all should PASS (measure.sh SKIPs without a system Chrome)
 ```
 
+## Install: core vs full
+
+A plain `npm install` (or the plugin's `npx @yojahny/wp-design-library serve`) gives you
+keyword search, ingest from recordings, the gallery, and every MCP tool — everything except
+the vector arm of `search`/`similar` and live-URL measurement (`add https://…`, `refresh`).
+Those two features sit behind `@huggingface/transformers` and `playwright-core`, listed as
+optional `peerDependencies` rather than regular dependencies precisely so the `npx` path (what
+the plugin actually runs) stays a core-only install. Measured on a fresh npm cache, a cold
+install is 57 MB and takes 6 s, against 736 MB and 48 s when both are regular dependencies;
+513 MB of the difference is `onnxruntime-node`, which transformers pulls in.
+Add them yourself when you want both arms:
+
+```bash
+npm install @huggingface/transformers@4.2.0 playwright-core@1.63.0
+```
+
+Without them, `search` degrades to the `fts` arm alone (`skipped` names the missing package),
+and `add`/`refresh` refuse a URL input with a named reason instead of crashing.
+
 ## Adding an entry
 
 Adding is two steps by design: the tool does the mechanical part, a Claude
@@ -348,6 +367,36 @@ The container runs as `node` (uid 1000), not root: `docker/entrypoint.sh` starts
 root only to `chown` an existing (possibly root-owned) `/data` volume, then drops to
 `node` via `setpriv` before exec'ing the server.
 
+## Releasing
+
+1. Bump `version` in `package.json`.
+2. Tag the release: `git tag v0.2.0` (the workflow triggers on any `v*` tag).
+3. Push the tag: `git push origin v0.2.0`.
+4. `.github/workflows/publish.yml` runs on that push: checks out, installs with
+   `npm ci`, runs `npm test`, then `npm publish`. Trusted publishing means no npm
+   token lives in this repo — the registry trusts the GitHub Actions run itself via
+   OIDC (`id-token: write`).
+
+One-time setup on npmjs.com, before the first tagged release:
+
+1. Open the package's settings page on npmjs.com.
+2. Under **Trusted Publisher**, add a publisher.
+3. Choose **GitHub Actions** as the provider.
+4. Organisation: `yojahny55`.
+5. Repository: `wp-design-library`.
+6. Workflow filename: `publish.yml` (the filename only, not the path under
+   `.github/workflows/`).
+7. Environment: leave empty (the workflow does not define one).
+
+Trusted publisher configurations created now default to **staged** publishing rather
+than a direct `npm publish`. Either flip the allowed-actions toggle on the trusted
+publisher to permit direct publishing (matches the workflow above as written), or
+change the workflow's last step to `npm stage publish` and approve each release by
+hand in the npm UI. Provenance is not generated for this release, because this repo
+is private — provenance requires a public repository. After the first successful
+publish, publishing access can be tightened to require 2FA and disallow tokens
+without breaking this workflow, since it never uses a token.
+
 ## Known ceilings
 
 - **Chrome runs without its own sandbox inside the container.** Docker's default

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@yojahny/wp-design-library",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Design reference corpus and MCP server for claude-wp-builder",
+  "repository": { "type": "git", "url": "git+https://github.com/yojahny55/wp-design-library.git" },
+  "homepage": "https://github.com/yojahny55/wp-design-library#readme",
+  "bugs": { "url": "https://github.com/yojahny55/wp-design-library/issues" },
   "type": "module",
   "bin": { "library": "bin/library.mjs" },
   "engines": { "node": ">=22" },
@@ -12,15 +15,35 @@
     "serve": "node bin/library.mjs serve"
   },
   "dependencies": {
-    "@huggingface/transformers": "4.2.0",
     "@modelcontextprotocol/sdk": "^1.20.0",
     "better-sqlite3": "^12.2.0",
     "js-yaml": "^4.1.0",
-    "playwright-core": "1.63.0",
     "sharp": "^0.34.3",
     "sqlite-vec": "0.1.9",
     "zod": "^3.25.0"
   },
+  "peerDependencies": {
+    "@huggingface/transformers": "4.2.0",
+    "playwright-core": "1.63.0"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": { "optional": true },
+    "playwright-core": { "optional": true }
+  },
   "license": "MIT",
-  "private": false
+  "private": false,
+  "files": [
+    ".dockerignore",
+    ".env.example",
+    "Dockerfile",
+    "LICENSE",
+    "README.md",
+    "bin/",
+    "docker-compose.yml",
+    "docker/",
+    "entries/",
+    "src/",
+    "tests/",
+    "vocab.yaml"
+  ]
 }

package/src/cli/check.mjs

@@ -7,7 +7,8 @@ import { fetchModels, modelDirs } from '../index/embed.mjs';
 export async function run(args = []) {
   const p = paths();
   if (args.includes('--fetch-models')) {
-    await fetchModels(p.models);
+    const r = await fetchModels(p.models);
+    if (r?.refused) { process.stdout.write(JSON.stringify(r) + '\n'); return 1; }
     const d = modelDirs(p.models);
     process.stdout.write(`model: ${d.text}\nmodel: ${d.image}\n`);
     return 0;

package/src/index/embed.mjs

@@ -19,6 +19,12 @@ export function modelDirs(models) {
   return { text: path.join(models, TEXT_MODEL), image: path.join(models, IMAGE_MODEL) };
 }
 
+// Resolvable without importing/executing the module, so it works as a cheap, sync
+// "is it installed" probe for the optional peer.
+function packageAvailable(specifier) {
+  try { import.meta.resolve(specifier); return true; } catch { return false; }
+}
+
 export async function getEmbedder({ models, mode = process.env.LIBRARY_EMBED } = {}) {
   if (mode === 'off') return null;
   if (mode === 'stub') {
@@ -34,7 +40,9 @@ export async function getEmbedder({ models, mode = process.env.LIBRARY_EMBED } =
   }
   const d = modelDirs(models);
   if (!fs.existsSync(d.text) || !fs.existsSync(d.image)) return null; // caller reads absentReason()
-  const tf = await import('@huggingface/transformers');
+  let tf;
+  try { tf = await import('@huggingface/transformers'); }
+  catch { return null; } // package not installed; caller reads absentReason()
   tf.env.cacheDir = models; tf.env.allowRemoteModels = process.env.LIBRARY_FETCH_MODELS === '1';
   const textPipe = await tf.pipeline('feature-extraction', TEXT_MODEL);
   const proc = await tf.AutoProcessor.from_pretrained(IMAGE_MODEL);
@@ -55,13 +63,19 @@ export function absentReason(models, mode = process.env.LIBRARY_EMBED) {
   // An explicit opt-out is the reason on its own; do not let a stale/present
   // model dir on disk relabel it, and do not touch the filesystem to find out.
   if (mode === 'off') return 'LIBRARY_EMBED=off';
+  // The package is a smaller, more fundamental blocker than an unfetched model
+  // directory, and it's checked first so a host missing the peer gets told that,
+  // not a misleading "models absent" (a fresh host has neither).
+  if (!packageAvailable('@huggingface/transformers')) return '@huggingface/transformers is not installed';
   const d = modelDirs(models);
   const missing = Object.entries(d).filter(([, p]) => !fs.existsSync(p)).map(([k]) => k);
   return missing.length ? `models absent: ${missing.join(', ')} under ${models}` : null;
 }
 
 export async function fetchModels(models) {
-  const tf = await import('@huggingface/transformers');
+  let tf;
+  try { tf = await import('@huggingface/transformers'); }
+  catch { return { refused: '@huggingface/transformers is not installed' }; }
   tf.env.cacheDir = models; tf.env.allowRemoteModels = true;
   await tf.pipeline('feature-extraction', TEXT_MODEL);
   await tf.AutoProcessor.from_pretrained(IMAGE_MODEL);

package/src/index/query.mjs

@@ -20,7 +20,7 @@ function filterSql(filters = {}, col = 'slug') {
 
 const RRF_K = 60;
 
-export async function search(db, { query = '', filters = {}, limit = 10, embedder = null }) {
+export async function search(db, { query = '', filters = {}, limit = 10, embedder = null, embedderReason = null }) {
   const { where, params } = filterSql(filters, 'e.slug');
   if (!query.trim()) {
     const { where, params } = filterSql(filters);
@@ -39,7 +39,7 @@ export async function search(db, { query = '', filters = {}, limit = 10, embedde
     return { arms: ['fts'], skipped: [{ arm: 'vec', reason }], hits: rows };
   };
   if (!(db.vec && embedder)) {
-    return ftsOnly(db.vec ? 'no embedder' : 'sqlite-vec not loaded');
+    return ftsOnly(db.vec ? (embedderReason ?? 'no embedder') : 'sqlite-vec not loaded');
   }
   let vec;
   try {
@@ -65,9 +65,9 @@ export async function search(db, { query = '', filters = {}, limit = 10, embedde
   };
 }
 
-export async function similar(db, { slug, image, limit = 10, embedder = null }) {
+export async function similar(db, { slug, image, limit = 10, embedder = null, embedderReason = null }) {
   if (!(db.vec && embedder)) {
-    return { refused: `similar needs the image arm: ${db.vec ? 'no embedder' : 'sqlite-vec not loaded'}` };
+    return { refused: `similar needs the image arm: ${db.vec ? (embedderReason ?? 'no embedder') : 'sqlite-vec not loaded'}` };
   }
   let vec;
   if (slug) {

package/src/ingest/measure.mjs

@@ -1,6 +1,5 @@
 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 };
@@ -87,6 +86,12 @@ function collect() {
 // 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 } = {}) {
+  let chromium;
+  try {
+    ({ chromium } = await import('playwright-core'));
+  } catch {
+    return { ok: false, error: 'playwright-core is not installed; install it for URL measurement' };
+  }
   if (!chrome || !fs.existsSync(chrome)) {
     return { ok: false, error: 'chrome not available: CHROME_PATH not set or not found' };
   }

package/src/mcp/server.mjs

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { paths } from '../paths.mjs';
 import { loadVocab } from '../vocab.mjs';
-import { getEmbedder } from '../index/embed.mjs';
+import { getEmbedder, absentReason } from '../index/embed.mjs';
 import { registerPrompts } from './prompts.mjs';
 import { registerResources } from './resources.mjs';
 import { makeTools, registerTools } from './tools.mjs';
@@ -13,6 +13,8 @@ export async function buildServer(opts = {}) {
   const ctx = { paths: p, vocab: loadVocab(p.vocab), transport, models: p.models };
   // http passes its own cached embedder in (one per process, not one per request); stdio resolves its own.
   ctx.embedder = 'embedder' in opts ? opts.embedder : await getEmbedder({ models: ctx.models });
+  // Names why, when it's null: off / package not installed / models absent are distinct.
+  ctx.embedderReason = ctx.embedder ? null : absentReason(ctx.models);
   const server = new McpServer({ name: 'wp-design-library', version: p.version });
   registerTools(server, makeTools(ctx));
   registerPrompts(server, ctx);

package/src/mcp/tools.mjs

@@ -70,7 +70,7 @@ export function makeTools(ctx) {
       }),
       handler: withDb(async (db, a) => {
         const { filters, unknown } = resolveFilters(ctx.vocab, a.filters ?? {});
-        const result = await search(db, { ...a, filters, embedder: ctx.embedder });
+        const result = await search(db, { ...a, filters, embedder: ctx.embedder, embedderReason: ctx.embedderReason });
         return unknown.length ? { ...result, unknown } : result;
       }),
     },
@@ -97,7 +97,7 @@ export function makeTools(ctx) {
           const refusal = confineToInbox(ctx, a.image);
           if (refusal) return { refused: refusal };
         }
-        return similar(db, { ...a, embedder: ctx.embedder });
+        return similar(db, { ...a, embedder: ctx.embedder, embedderReason: ctx.embedderReason });
       }),
     },
     {

package/tests/checks/frames-dense.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -eu
 cd "$(dirname "$0")/../.."
+command -v ffmpeg >/dev/null || { echo "SKIP: ffmpeg not installed"; exit 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"

package/tests/checks/index-degrade.sh

@@ -6,7 +6,7 @@ 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; }
+echo "$out" | grep -qE "embeddings: skipped \((models absent|@huggingface/transformers is not installed)" || { 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; }

package/tests/checks/measure.sh

@@ -3,6 +3,8 @@ 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; }
+node --input-type=module -e 'await import("playwright-core")' 2>/dev/null \
+  || { echo "SKIP: playwright-core not installed"; exit 0; }
 export CHROME_PATH
 tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 mkdir -p "$tmp/entries"
@@ -51,7 +53,9 @@ if (strip.height < single.height * 2) { console.error('FAIL: strip height ' + st
 # 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)
+# UTC, because measure.mjs writes `new Date().toISOString()`. Using local `date`
+# here fails every evening west of Greenwich, on a correct entry.
+today=$(date -u +%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)

package/tests/checks/optional-deps.sh

@@ -0,0 +1,55 @@
+#!/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"
+
+# A sandbox that genuinely lacks the two optional peers: copy the code, then symlink
+# every real node_modules entry except @huggingface/transformers and playwright-core.
+# Scoped packages are symlinked individually under @scope/, not the scope directory
+# itself — symlinking the scope dir would drag the excluded package back in.
+sandbox="$tmp/sandbox"
+mkdir -p "$sandbox/node_modules"
+cp -r bin src package.json vocab.yaml "$sandbox/"
+for entry in node_modules/*; do
+  name=$(basename "$entry")
+  case "$name" in
+    @*|playwright-core) continue ;;
+  esac
+  ln -s "$PWD/$entry" "$sandbox/node_modules/$name"
+done
+for scope in node_modules/@*; do
+  sname=$(basename "$scope")
+  mkdir -p "$sandbox/node_modules/$sname"
+  for pkg in "$scope"/*; do
+    pname=$(basename "$pkg")
+    [ "$sname/$pname" = "@huggingface/transformers" ] && continue
+    ln -s "$PWD/$pkg" "$sandbox/node_modules/$sname/$pname"
+  done
+done
+[ ! -e "$sandbox/node_modules/playwright-core" ] || { echo "FAIL: sandbox still has playwright-core"; exit 1; }
+[ ! -e "$sandbox/node_modules/@huggingface/transformers" ] || { echo "FAIL: sandbox still has @huggingface/transformers"; exit 1; }
+
+# search over stdio: fts only, skip names the transformers package
+{
+  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":"search","arguments":{"query":"parallax"}}}'
+  sleep 1
+} | LIBRARY_DATA="$tmp" LIBRARY_SEED="$tmp/noseed" timeout 10 node "$sandbox/bin/library.mjs" serve >"$tmp/out" 2>"$tmp/err" || true
+grep -q '"arms":\["fts"\]' "$tmp/out" || { echo "FAIL: arms not fts-only; got:"; cat "$tmp/out"; exit 1; }
+grep -q '"skipped":\[{"arm":"vec","reason":"@huggingface/transformers is not installed"}\]' "$tmp/out" \
+  || { echo "FAIL: skipped reason did not name the transformers package; got:"; cat "$tmp/out"; exit 1; }
+
+# add <https url>: refused, naming playwright-core
+out=$(LIBRARY_DATA="$tmp" node "$sandbox/bin/library.mjs" add https://example.com --slug px-url --title "Px Url" --source own --license x) || true
+echo "$out" | grep -q '"refused"' || { echo "FAIL: https add did not refuse; got: $out"; exit 1; }
+echo "$out" | grep -q "playwright-core is not installed" || { echo "FAIL: refusal did not name playwright-core; got: $out"; exit 1; }
+
+# add <local recording>: still works — the regression a static playwright-core import
+# in measure.mjs would cause, since add.mjs imports measure.mjs unconditionally
+out=$(LIBRARY_DATA="$tmp" node "$sandbox/bin/library.mjs" add "$PWD/tests/fixtures/three-frame.webp" --slug px-local --title "Px Local" --source own --license x)
+echo "$out" | grep -q '"blanks"' || { echo "FAIL: local-file add did not draft; got: $out"; exit 1; }
+[ -f "$tmp/entries/px-local/strip.png" ] || { echo "FAIL: strip.png missing for local-file add"; exit 1; }
+
+echo PASS

package/tests/run.sh

@@ -1,10 +1,16 @@
 #!/usr/bin/env bash
 set -u
 cd "$(dirname "$0")/.."
-pass=0; fail=0
+pass=0; fail=0; skip=0
+# A check that cannot run its subject exits 0 after printing SKIP. Counting those as
+# PASS would let a runner missing every tool report a clean suite, which is how three
+# absent-dependency failures reached the publish workflow unnoticed.
 for f in tests/checks/*.sh; do
-  if out=$(bash "$f" 2>&1); then pass=$((pass+1)); echo "PASS $f"
+  if out=$(bash "$f" 2>&1); then
+    if printf '%s' "$out" | grep -q '^SKIP'; then
+      skip=$((skip+1)); echo "SKIP $f  ($(printf '%s' "$out" | grep -m1 '^SKIP' | cut -c7-))"
+    else pass=$((pass+1)); echo "PASS $f"; fi
   else fail=$((fail+1)); echo "FAIL $f"; echo "$out" | tail -20; fi
 done
-echo "PASS=$pass FAIL=$fail"
+echo "PASS=$pass SKIP=$skip FAIL=$fail"
 [ "$fail" -eq 0 ]