@xtrable-ltd/nanoesis 0.1.10 → 0.1.12

package/dist/{chunk-UZQ7UP2B.js → chunk-XO3CT6GL.js}

@@ -471,20 +471,58 @@ function freeze(field) {
 }
 
 // ../engine/src/template/stamp.ts
-function detectStamp(oldSource, newSource, components = /* @__PURE__ */ new Map()) {
-  const oldFields = new Set(deriveFields(oldSource, components).map((f) => f.name));
-  const newFields = new Set(deriveFields(newSource, components).map((f) => f.name));
-  const removed = [];
+function isDestructiveTypeChange(from, to) {
+  if (from === to) return false;
+  const fromKind = valueKindOf(from);
+  const toKind = valueKindOf(to);
+  if (toKind === "html") return false;
+  if (fromKind === "html") return true;
+  if (from === "date" && to === "time" || from === "time" && to === "date") return true;
+  const isFreeText = (t) => t === "shorttext" || t === "text" || t === "code" || t === "email" || t === "phone";
+  if (isFreeText(from) && (to === "date" || to === "time")) return true;
+  if (fromKind === toKind) return false;
+  if (toKind === "text") return false;
+  return true;
+}
+function computeSchemaDelta(oldFields, newFields) {
+  const oldByName = new Map(oldFields.map((f) => [f.name, f]));
+  const newByName = new Map(newFields.map((f) => [f.name, f]));
   const added = [];
-  for (const name of oldFields) {
-    if (!newFields.has(name)) removed.push(name);
+  const removed = [];
+  const typeChanged = [];
+  for (const [name, oldField] of oldByName) {
+    const newField = newByName.get(name);
+    if (newField === void 0) {
+      removed.push({ name, type: oldField.type });
+    } else if (newField.type !== oldField.type) {
+      typeChanged.push({
+        name,
+        from: oldField.type,
+        to: newField.type,
+        destructive: isDestructiveTypeChange(oldField.type, newField.type)
+      });
+    }
   }
-  for (const name of newFields) {
-    if (!oldFields.has(name)) added.push(name);
+  for (const [name, newField] of newByName) {
+    if (!oldByName.has(name)) added.push({ name, type: newField.type });
   }
-  removed.sort();
-  added.sort();
-  return { destructive: removed.length > 0, removedTokens: removed, addedTokens: added };
+  return {
+    added: added.sort((a, b) => a.name.localeCompare(b.name)),
+    removed: removed.sort((a, b) => a.name.localeCompare(b.name)),
+    typeChanged: typeChanged.sort((a, b) => a.name.localeCompare(b.name))
+  };
+}
+function detectStamp(oldSource, newSource, components = /* @__PURE__ */ new Map()) {
+  const oldFields = deriveFields(oldSource, components);
+  const newFields = deriveFields(newSource, components);
+  const delta = computeSchemaDelta(oldFields, newFields);
+  const destructive = delta.removed.length > 0 || delta.typeChanged.some((change) => change.destructive);
+  return {
+    destructive,
+    removedTokens: delta.removed.map((r) => r.name),
+    addedTokens: delta.added.map((a) => a.name),
+    typeChanged: delta.typeChanged
+  };
 }
 
 // ../engine/src/template/versions.ts
@@ -692,11 +730,15 @@ var IndexedStore = class {
       const stampCandidate = stampTargetOf(target);
       const previousBytes = stampCandidate !== void 0 ? await this.store.get(target) : void 0;
       let stampDecision;
+      let schemaDelta;
       if (stampCandidate !== void 0 && previousBytes !== void 0) {
         const oldSource = new TextDecoder().decode(previousBytes);
         const newSource = new TextDecoder().decode(bytes);
-        const decision = detectStamp(oldSource, newSource);
-        if (decision.destructive) {
+        const oldFields = deriveFields(oldSource);
+        const newFields = deriveFields(newSource);
+        schemaDelta = computeSchemaDelta(oldFields, newFields);
+        const destructive = schemaDelta.removed.length > 0 || schemaDelta.typeChanged.some((change) => change.destructive);
+        if (destructive) {
           const index2 = await this.loaded();
           const siblings = index2.keys.filter((k) => k.startsWith(`${stampCandidate.dir}/`) && k.endsWith(".html")).map((k) => k.slice(stampCandidate.dir.length + 1, -".html".length));
           const version = nextVersionNumber(siblings);
@@ -736,7 +778,8 @@ var IndexedStore = class {
       this.index = nextIndex;
       return {
         ...stamped !== void 0 && { stamped },
-        ...stampIncomplete === true && { stampIncomplete: true }
+        ...stampIncomplete === true && { stampIncomplete: true },
+        ...schemaDelta !== void 0 && { schemaDelta }
       };
     });
   }
@@ -2378,7 +2421,8 @@ function buildAuthoringReference(context = {}) {
       annotationsSection(),
       loopsSection(context),
       componentsSection(context),
-      shellSection()
+      shellSection(),
+      guardrailsSection()
     ]
   };
 }
@@ -2523,6 +2567,41 @@ function componentsSection(context) {
     entries
   };
 }
+function guardrailsSection() {
+  return {
+    title: "Authoring guardrails for LLMs",
+    intro: "Common pitfalls when authoring through MCP, where you can't see the editor form's shape change. Most stem from the same root: data-* annotations bind to the element they sit on, not to the token inside it.",
+    entries: [
+      {
+        name: "data-* annotations are element-bound",
+        summary: "data-type, data-required, data-field, data-minlength, and data-maxlength apply to the *element* that carries them \u2014 moving a token outside its annotated container silently strips those properties from the schema.",
+        detail: 'Example: `<div data-type="richtext">{body}</div>` makes body a rich-text field. If you change it to `<div data-type="richtext"></div>{body}`, body drops back to plain shorttext. The compiler still substitutes the token at fragment root, but existing HTML content for body now renders escaped.',
+        example: '<!-- WRONG (drops the annotation) -->\n<div data-type="richtext"></div>{body}\n\n<!-- RIGHT -->\n<div data-type="richtext">{body}</div>'
+      },
+      {
+        name: "After write_file on a template, check `schemaDelta`",
+        summary: "Every write to templates/*.html or components/*.html returns a `schemaDelta` describing added/removed/typeChanged fields. If `typeChanged` contains `destructive: true` entries or `removed` is non-empty, an auto-stamp has been written and authored content may need migration \u2014 surface to the user before further edits.",
+        detail: "`schemaDelta` shape: `{added: [{name, type}], removed: [{name, type}], typeChanged: [{name, from, to, destructive}]}`. Empty arrays everywhere means the edit changed only whitespace, comments, or non-token markup \u2014 safe."
+      },
+      {
+        name: "After rename_path on a template, search content for the old name",
+        summary: 'Renaming `templates/article.html` to `templates/post.html` leaves every content item with `template: "article"` bound to a now-missing template. The validation gate will report these on publish, but the cheaper check is `list_pending_migrations` followed by editing the items\' `template` fields.'
+      },
+      {
+        name: "After delete_path on a template, expect publish-blocking errors",
+        summary: "Deleting a template that any item binds to will fail validation with `template-missing` per item. Use `list_pending_migrations` first to see who would be affected, and consider whether to rename items to a different template before deleting."
+      },
+      {
+        name: "Read describe_template before editing a content item",
+        summary: "A content item's `fields` object MUST match the bound template's schema (field names and value shapes). `describe_template` returns the field list with types so you build the right shape on the first try; mismatched keys become orphan fields the gate warns about."
+      },
+      {
+        name: "richtext values are HTML, shorttext/text are plain text",
+        summary: "For a `richtext` field, write the value as HTML (`<p>...</p>` etc). For `shorttext` or `text`, write plain text \u2014 any HTML you include is escaped at render time. If the gate emits a `content.type-drift` warning, a field's type changed destructively (commonly richtext \u2192 shorttext) and the old HTML content now renders as escaped text."
+      }
+    ]
+  };
+}
 function shellSection() {
   return {
     title: "The document shell",
@@ -2637,6 +2716,65 @@ async function validateSite(source) {
     expectedFieldsCache.set(templateName, fields);
     return fields;
   };
+  const driftFieldsCache = /* @__PURE__ */ new Map();
+  const driftFieldsFor = async (templateName) => {
+    if (driftFieldsCache.has(templateName)) return driftFieldsCache.get(templateName) ?? null;
+    const highest = await highestSnapshotName(templateName);
+    if (highest === null) {
+      driftFieldsCache.set(templateName, null);
+      return null;
+    }
+    let snapshotHtml;
+    try {
+      snapshotHtml = await loadTemplate(source, highest);
+    } catch {
+      driftFieldsCache.set(templateName, null);
+      return null;
+    }
+    const currentHtml = sourceCache.get(templateName);
+    if (currentHtml === void 0) {
+      driftFieldsCache.set(templateName, null);
+      return null;
+    }
+    const delta = computeSchemaDelta(
+      deriveFields(snapshotHtml, components),
+      deriveFields(currentHtml, components)
+    );
+    const destructive = new Set(
+      delta.typeChanged.filter((change) => change.destructive).map((change) => change.name)
+    );
+    driftFieldsCache.set(templateName, destructive);
+    return destructive;
+  };
+  const snapshotNameCache = /* @__PURE__ */ new Map();
+  const highestSnapshotName = async (baseName) => {
+    if (snapshotNameCache.has(baseName)) return snapshotNameCache.get(baseName) ?? null;
+    const slash = baseName.lastIndexOf("/");
+    const dir = slash === -1 ? "templates" : `templates/${baseName.slice(0, slash)}`;
+    const stem = slash === -1 ? baseName : baseName.slice(slash + 1);
+    let entries;
+    try {
+      entries = await source.list(dir);
+    } catch {
+      snapshotNameCache.set(baseName, null);
+      return null;
+    }
+    let highest = 0;
+    let highestStem = null;
+    const prefix = `${stem}@v`;
+    for (const entry of entries) {
+      if (entry.kind !== "file" || !entry.name.endsWith(".html")) continue;
+      const entryStem = entry.name.slice(0, -".html".length);
+      if (!entryStem.startsWith(prefix)) continue;
+      const version = versionNumber(entryStem);
+      if (version !== null && version > highest) {
+        highest = version;
+        highestStem = slash === -1 ? entryStem : `${baseName.slice(0, slash)}/${entryStem}`;
+      }
+    }
+    snapshotNameCache.set(baseName, highestStem);
+    return highestStem;
+  };
   const urlOwners = /* @__PURE__ */ new Map();
   for (const { node, templateName } of published) {
     const owners = urlOwners.get(urlForItem(node.path)) ?? [];
@@ -2674,6 +2812,18 @@ async function validateSite(source) {
           node.path
         );
       }
+      const driftFields = await driftFieldsFor(templateName);
+      if (driftFields !== null && driftFields.size > 0) {
+        const affected = itemFieldNames.filter((name) => driftFields.has(name));
+        if (affected.length > 0) {
+          add(
+            "warning",
+            "content.type-drift",
+            `"${node.path}" has field${affected.length === 1 ? "" : "s"} whose type changed destructively in template "${templateName}": ${affected.map((f) => `"${f}"`).join(", ")}. The value will render under the new type (commonly HTML escaped as text). Open the Migrations workspace to migrate.`,
+            node.path
+          );
+        }
+      }
     }
     const scope = buildScope2(node.item);
     for (const field of analysis.requiredFields) {
@@ -3110,6 +3260,8 @@ export {
   findTokens,
   wholeValueToken,
   deriveFields,
+  isDestructiveTypeChange,
+  computeSchemaDelta,
   detectStamp,
   isVersionedTemplateName,
   baseTemplateName,