webcake-storefront-mcp 2.1.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,12 +5,28 @@
5
5
  // - keys mined from 329 published pages (element-keys.generated.json),
6
6
  // - the curated tables in attributes.ts (meanings, enums like "h1|h2|…|p"),
7
7
  // - the factory skeleton (also the source of each key's value TYPE),
8
- // - the generic grid config + shared specials every node may carry.
8
+ // - the generic grid config + shared specials every node may carry,
9
+ // - the published-page renderer (renderer-keys.generated.json, scripts/mine-renderer.mjs):
10
+ // which keys each type's HTML/CSS builder READS, their fallback default, compared values,
11
+ // - the editor panels (editor-keys.generated.json, scripts/mine-editor.mjs): the label the
12
+ // user sees, the control, the options a select offers.
9
13
  // The renderer ignores a specials/config key it doesn't know (a dead key), so an unknown key is
10
14
  // a WARNING with a did-you-mean. Style is different: the renderer emits every style key as CSS
11
15
  // (camelCase → kebab), so style keys are checked as CSS properties, not per type.
12
16
  import { OBSERVED, ELEMENT_ATTRS, SHARED_SPECIALS, SHARED_KEY_DICT, GENERIC_CONFIG } from "./attributes.js";
13
17
  import { buildElement, describeType, isKnownType, ELEMENT_TYPES } from "./catalog.js";
18
+ import { readFileSync } from "node:fs";
19
+ const loadJson = (name) => {
20
+ try {
21
+ return JSON.parse(readFileSync(new URL(name, import.meta.url), "utf8"));
22
+ }
23
+ catch {
24
+ return {};
25
+ }
26
+ };
27
+ const RENDERER = loadJson("./renderer-keys.generated.json");
28
+ const MENTIONED = new Set(RENDERER.mentioned || []);
29
+ const EDITOR = loadJson("./editor-keys.generated.json");
14
30
  /** `[CODE] #id (type) at: message → fix` — stable code first so an agent can act per code. */
15
31
  export function formatFinding(f) {
16
32
  const who = f.id ? ` #${f.id}${f.type ? ` (${f.type})` : ""}` : f.type ? ` (${f.type})` : "";
@@ -49,6 +65,10 @@ for (const a of Object.values(ELEMENT_ATTRS)) {
49
65
  Object.keys(a.specials || {}).forEach((k) => ANY_SPECIALS.add(k));
50
66
  Object.keys(a.config || {}).forEach((k) => ANY_CONFIG.add(k));
51
67
  }
68
+ for (const src of [RENDERER.shared, ...Object.values(RENDERER.types || {}), ...Object.values(EDITOR.types || {})]) {
69
+ Object.keys(src?.specials || {}).forEach((k) => ANY_SPECIALS.add(k));
70
+ Object.keys(src?.config || {}).forEach((k) => ANY_CONFIG.add(k));
71
+ }
52
72
  const KEY_TYPES = new Set(["string", "number", "boolean", "array", "object"]);
53
73
  export function elementSchema(type) {
54
74
  if (!isKnownType(type))
@@ -59,26 +79,53 @@ export function elementSchema(type) {
59
79
  const skeleton = buildElement(type, {});
60
80
  const obs = OBSERVED[type] || { specials: [], config: [], style: [], bindings: [], events: false };
61
81
  const cur = ELEMENT_ATTRS[type] || {};
82
+ const rend = RENDERER.types?.[type];
83
+ const edit = EDITOR.types?.[type];
62
84
  const bucket = (where, keys, defaults, curated, shared) => {
63
85
  const out = {};
64
- for (const k of [...keys].sort()) {
86
+ const r = rend?.[where] || {};
87
+ const rs = RENDERER.shared?.[where] || {};
88
+ const e = edit?.[where] || {};
89
+ for (const k of [...new Set([...keys, ...Object.keys(r), ...Object.keys(e)])].sort()) {
65
90
  const desc = curated?.[k] ?? shared[k] ?? SHARED_KEY_DICT[k];
66
91
  const spec = {};
92
+ const rk = r[k] ?? rs[k];
93
+ const ek = e[k];
67
94
  const types = new Set((obs.types?.[`${where}.${k}`] || []).filter((t) => KEY_TYPES.has(t)));
68
- const t = typeOf(defaults?.[k]);
95
+ const t = typeOf(defaults?.[k]) ?? typeOf(rk?.default);
69
96
  if (t)
70
97
  types.add(t);
71
98
  if (types.size)
72
99
  spec.types = [...types].sort();
73
100
  const seen = obs.values?.[`${where}.${k}`];
74
101
  const curatedEnum = enumOf(curated?.[k]);
102
+ // Numeric editor options next to word values (renderer/real pages) come from another panel.
103
+ const words = [...(rk?.values || []), ...(seen || [])].some((v) => !/^\d+$/.test(v));
104
+ const opts = (ek?.options || []).filter((o) => !(words && /^\d+$/.test(o)));
105
+ const offered = [...new Set([...opts, ...(rk?.values || [])])];
75
106
  // Enforced only when both the editor's list and real pages agree it is closed.
76
107
  if (curatedEnum && seen)
77
108
  spec.enum = [...new Set([...curatedEnum, ...seen])];
109
+ else if (opts.length && seen?.length && seen.every((v) => opts.includes(v)))
110
+ spec.enum = [...new Set([...opts, ...(rk?.values || [])])];
78
111
  else if (seen)
79
112
  spec.seen = seen;
113
+ if (!spec.enum && offered.length)
114
+ spec.values = offered;
80
115
  if (desc)
81
116
  spec.desc = desc;
117
+ if (ek?.label)
118
+ spec.label = ek.label;
119
+ if (rk?.default !== undefined)
120
+ spec.default = rk.default;
121
+ // Grid/position config and shared specials are read by generic plumbing — no per-type flag.
122
+ // false only when nothing on the render side (Elixir or client JS) mentions the key at all.
123
+ if (rend && !(where === "config" ? GENERIC_CONFIG.has(k) : k in SHARED_SPECIALS)) {
124
+ if (rk)
125
+ spec.rendered = true;
126
+ else if (!MENTIONED.has(k))
127
+ spec.rendered = false;
128
+ }
82
129
  out[k] = spec;
83
130
  }
84
131
  return out;
@@ -196,11 +243,13 @@ export function checkElementKeys(node) {
196
243
  if (!obj || typeof obj !== "object" || Array.isArray(obj))
197
244
  return;
198
245
  for (const [k, v] of Object.entries(obj)) {
199
- if (NOISE.has(k))
200
- continue;
246
+ if (NOISE.has(k) || k.startsWith("__"))
247
+ continue; // __row/__cell: layout markers finalizeForRender consumes
201
248
  const at = `${where}.${k}`;
202
249
  if (k in specs) {
203
250
  checkValue(specs[k], v, { ...base, at }, out);
251
+ if (specs[k].rendered === false && v !== undefined && v !== null && v !== "")
252
+ out.push({ ...base, at, code: "NO_EFFECT", severity: "warning", message: `no render code reads ${where.split(".").pop()}.${k} — stored, changes nothing on the published page`, fix: `drop it; see keys in get_element("${node.type}")` });
204
253
  continue;
205
254
  }
206
255
  const anywhere = where === "specials" ? ANY_SPECIALS : ANY_CONFIG;
@@ -272,6 +321,76 @@ export function valueRules(type) {
272
321
  }
273
322
  return Object.keys(out).length ? out : undefined;
274
323
  }
324
+ /** One line per meaningful key of a type — what get_element shows an agent:
325
+ * `key: meaning · type · one of a|b · default x`. Keys the renderer reads come first; keys no
326
+ * render code mentions go to no_effect (stored, change nothing on the published page). */
327
+ export function keyReference(type) {
328
+ const schema = elementSchema(type);
329
+ if (!schema)
330
+ return undefined;
331
+ const fmt = (v) => (typeof v === "string" ? JSON.stringify(v) : String(v));
332
+ const out = { specials: [], config: [] };
333
+ const dead = [];
334
+ for (const where of ["specials", "config"]) {
335
+ const rows = Object.entries(schema[where]).filter(([k]) => !NOISE.has(k) && !(where === "config" ? GENERIC_CONFIG.has(k) : k in SHARED_SPECIALS));
336
+ rows.sort(([, a], [, b]) => Number(!!b.rendered) - Number(!!a.rendered));
337
+ for (const [k, s] of rows) {
338
+ if (s.rendered === false) {
339
+ dead.push(`${where}.${k}`);
340
+ continue;
341
+ }
342
+ const parts = [];
343
+ const meaning = s.desc ?? (s.label ? `"${s.label}"` : undefined);
344
+ if (meaning)
345
+ parts.push(meaning);
346
+ if (s.types && !(s.types.length === 1 && s.types[0] === "string" && (s.enum || s.values)))
347
+ parts.push(s.types.join("|"));
348
+ if (s.enum)
349
+ parts.push(`one of ${s.enum.join("|")}`);
350
+ else if (s.values || s.seen)
351
+ parts.push(`e.g. ${[...new Set([...(s.values || []), ...(s.seen || [])])].slice(0, 12).join("|")}`);
352
+ if (s.default !== undefined && s.default !== "")
353
+ parts.push(`default ${fmt(s.default)}`);
354
+ out[where].push(parts.length ? `${k}: ${parts.join(" · ")}` : k);
355
+ }
356
+ }
357
+ out.config = groupPlain(out.config);
358
+ if (dead.length)
359
+ out.no_effect = dead;
360
+ return out;
361
+ }
362
+ /** Style config of one part (addToCartColor, addToCartFontSize…) folded into one line per part:
363
+ * `addToCart{Color,FontSize,…}: style of the addToCart part` (defaults kept inline). */
364
+ const STYLE_SUFFIX = /(Background(?:Hover)?|Border(?:Color|Radius|Width|Style)?|BoxShadow|Color(?:Hover)?|Decoration|Font(?:Size|Style|Weight|Theme|Family)?|TextAlign|LetterSpacing|LineHeight|Padding[XY]?|Margin[XY]?|Radius|Width|Height|Size|Gap|Opacity|Shadow)$/;
365
+ function groupPlain(lines) {
366
+ const parse = (l) => {
367
+ const i = l.indexOf(":");
368
+ const k = i < 0 ? l : l.slice(0, i);
369
+ const m = STYLE_SUFFIX.exec(k);
370
+ const enumish = / · (one of|e\.g\.) /.test(l);
371
+ const dflt = / · default (.+)$/.exec(l)?.[1];
372
+ return { k, part: m && m.index > 1 && !enumish ? k.slice(0, m.index) : undefined, suffix: m?.[1], dflt };
373
+ };
374
+ const rows = lines.map((l) => ({ l, ...parse(l) }));
375
+ const count = new Map();
376
+ for (const r of rows)
377
+ if (r.part)
378
+ count.set(r.part, (count.get(r.part) || 0) + 1);
379
+ const done = new Set();
380
+ const out = [];
381
+ for (const r of rows) {
382
+ if (!r.part || count.get(r.part) < 3) {
383
+ out.push(r.l);
384
+ continue;
385
+ }
386
+ if (done.has(r.part))
387
+ continue;
388
+ done.add(r.part);
389
+ const members = rows.filter((x) => x.part === r.part).map((x) => `${x.suffix}${x.dflt ? `=${x.dflt}` : ""}`);
390
+ out.push(`${r.part}{${members.join(",")}}: style of the ${r.part} part`);
391
+ }
392
+ return out;
393
+ }
275
394
  /** Did-you-mean for an unknown element type. */
276
395
  export const suggestType = (type) => didYouMean(type, ELEMENT_TYPES);
277
396
  /** Collapse repeated warnings per code: keep the first `keep`, then one line with the rest. */