@yojahny/wp-design-library 0.6.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yojahny/wp-design-library",
-  "version": "0.6.0",
+  "version": "1.0.1",
   "description": "Design reference corpus and MCP server for claude-wp-builder",
   "repository": {
     "type": "git",

package/src/cli/serve.mjs

@@ -11,8 +11,20 @@ async function syncSeed(p) {
   if (p.seed !== p.entries && fs.existsSync(p.seed)) {
     const path = await import('node:path');
     fs.mkdirSync(p.entries, { recursive: true });
+    // Healing missing files is not enough when the file that changed is one the volume already
+    // has. 0.6.0 rewrote every entry.md — artifacts became {key, bytes, sha256} records — and
+    // because the volume's copies existed, none were replaced: all 31 entries failed validation
+    // and the gallery served nothing but drafts. Copy-if-absent can only ever fix an entry that
+    // is incomplete, never one that is stale, so a schema change breaks the corpus permanently.
+    // The stamp closes that: when the image's version differs from the one this volume was last
+    // seeded at, entry.md is re-copied for the slugs the seed ships.
+    const stamp = path.join(p.data, '.seed-version');
+    let seeded;
+    try { seeded = fs.readFileSync(stamp, 'utf8').trim(); } catch { seeded = null; }
+    const upgraded = seeded !== p.version;
     let copied = 0;
     let healed = 0;
+    let refreshed = 0;
     for (const d of fs.readdirSync(p.seed, { withFileTypes: true })) {
       if (!d.isDirectory() || !fs.existsSync(path.join(p.seed, d.name, 'entry.md'))) continue;
       const src = path.join(p.seed, d.name);
@@ -31,9 +43,22 @@ async function syncSeed(p) {
           return true;
         },
       });
+      // Only entry.md, and only on an upgrade. Everything else the seed ships is inert next to
+      // an artifact record, and a hosted ingest never lands on a slug the image also ships — so
+      // what this can overwrite is an operator's hand-edit of a seeded entry, which an image
+      // upgrade was always going to supersede. Serving a corpus that validates beats preserving
+      // an edit that only exists until the next deploy.
+      if (!upgraded) continue;
+      const from = path.join(src, 'entry.md');
+      const to = path.join(dest, 'entry.md');
+      if (fs.readFileSync(from, 'utf8') === fs.readFileSync(to, 'utf8')) continue;
+      fs.copyFileSync(from, to);
+      refreshed++;
     }
+    fs.writeFileSync(stamp, p.version);
     process.stderr.write(`seed: copied ${copied} new entries into ${p.entries}\n`);
     process.stderr.write(`seed: healed ${healed} missing files into existing entries\n`);
+    process.stderr.write(`seed: refreshed ${refreshed} stale entry.md (volume seeded at ${seeded ?? 'unknown'}, image is ${p.version})\n`);
   }
 }
 

package/src/mcp/http.mjs

@@ -23,8 +23,23 @@ async function handle(req, res, p, token, embedder) {
       if (db.vec && db.prepare('SELECT count(*) c FROM vec_text').get().c > 0) arms = ['fts', 'vec'];
       db.close();
     } catch {}
+    // A host with a full index and no reachable artifacts serves 31 grey boxes and reported
+    // ok:true, which is how a missing R2_PUBLIC_BASE_URL stayed invisible through two rounds of
+    // "it still is not showing images". Name it here, where anyone can see it without log access.
+    // It is not part of `ok`: the MCP API answers perfectly well on text alone, and failing the
+    // health check would take a working server down over missing pictures.
+    // "configured", never "ok": this reads the environment, it does not fetch an object, so it
+    // cannot claim the bucket is reachable. It catches the failure actually hit — the variable
+    // being absent — and says only what it checked.
+    let artifacts;
+    try {
+      const { readConfig } = await import('../r2.mjs');
+      artifacts = `configured: ${readConfig().base}`;
+    } catch (err) {
+      artifacts = `unconfigured: ${err.message}`;
+    }
     res.writeHead(200, { 'content-type': 'application/json' });
-    return res.end(JSON.stringify({ ok: true, entries, arms, version: p.version }));
+    return res.end(JSON.stringify({ ok: true, entries, arms, artifacts, version: p.version }));
   }
   if (url.pathname === '/mcp') {
     if (!authorized(req.headers.authorization, token)) { res.writeHead(401); return res.end('unauthorized'); }

package/src/ui/build.mjs

@@ -156,6 +156,7 @@ export async function buildUi({ indexPath, entriesDir, outDir, previewMediaDir,
   fs.mkdirSync(path.join(outDir, 'thumbnails'), { recursive: true });
 
   const rows = [];
+  const unresolved = [];
   for (const dir of listEntries(entriesDir)) {
     let entry;
     try { entry = parseEntry(dir); } catch (err) { process.stderr.write(`ui: skipping ${path.basename(dir)}: ${err.message}\n`); continue; }
@@ -169,11 +170,14 @@ export async function buildUi({ indexPath, entriesDir, outDir, previewMediaDir,
     const strip = (entry.fm.captured?.captures?.[0]?.artifacts ?? []).find((a) => a?.key?.endsWith('/strip.webp'));
     // One unreachable object must not take the gallery down with it: the entry renders without a
     // thumbnail, exactly as a draft does, and the build continues.
-    if (strip) { try { stripSrc = await artifactFile(p, strip); } catch { stripSrc = null; } }
+    // Degrading silently is what made a misconfigured host indistinguishable from a broken one:
+    // a gallery of 31 grey boxes, `ok: true` from healthz, and not one line saying why. Swallow
+    // the failure, still — but count it and keep the first reason.
+    if (strip) { try { stripSrc = await artifactFile(p, strip); } catch (err) { stripSrc = null; unresolved.push(err); } }
     // Same treatment for measure.json: a record to resolve, never a file next to entry.md.
     let measureSrc = null;
     const measured = (entry.fm.captured?.captures?.[0]?.artifacts ?? []).find((a) => a?.key?.endsWith('/measure.json'));
-    if (measured) { try { measureSrc = await artifactFile(p, measured); } catch { measureSrc = null; } }
+    if (measured) { try { measureSrc = await artifactFile(p, measured); } catch (err) { measureSrc = null; unresolved.push(err); } }
     const hasStrip = stripSrc !== null;
     if (hasStrip) {
       fs.copyFileSync(stripSrc, path.join(outDir, 'strips', `${slug}.webp`));
@@ -212,5 +216,11 @@ export async function buildUi({ indexPath, entriesDir, outDir, previewMediaDir,
   fs.writeFileSync(path.join(outDir, 'index.html'), render(tpl, { FILTERS: filters, GRID: rows.map(card).join('\n'), NOTICE: notice }));
   fs.copyFileSync(path.join(DIR, 'app.js'), path.join(outDir, 'app.js'));
 
-  return { entries: rows.length - drafts, drafts };
+  // One line, not one per artifact: 31 entries failing for the same missing variable is one
+  // fact, and printing it 62 times would bury it. The first reason is the one that matters —
+  // they are identical when the cause is configuration, which is the case worth naming.
+  if (unresolved.length) {
+    process.stderr.write(`ui: ${unresolved.length} artifact(s) could not be resolved, so those entries render without a thumbnail; first reason: ${unresolved[0].message}\n`);
+  }
+  return { entries: rows.length - drafts, drafts, unresolved: unresolved.length };
 }