@xtrable-ltd/nanoesis 0.1.8 → 0.1.10

package/dist/editor-api.d.ts

@@ -1,4 +1,4 @@
-import { WorkingStore, IdentityProvider, PublishResult, ReconcileResult, AuthEndpoints, UserAdminEndpoints, AuthorOption, DiagnosticRegistry, UserSummary, AuthorDirectory, DiagnosticCheck, Repair } from '@nanoesis/engine';
+import { WorkingStore, IdentityProvider, PublishResult, ReconcileResult, AuthEndpoints, UserAdminEndpoints, AuthorOption, DiagnosticRegistry, UserSummary, AuthorDirectory, Repair, DiagnosticCheck } from '@nanoesis/engine';
 
 /**
  * Editor white-labelling storage (DESIGN §11, Phase B). This is the *editor app's*
@@ -285,5 +285,42 @@ declare const recreateHomeTemplateRepair: Repair;
  * user picks what to publish; we only point out that nothing is.
  */
 declare const noPublishedContentDiagnostic: DiagnosticCheck;
+/**
+ * Walk every published content item; for any pinned to a snapshot, check whether the
+ * snapshot file exists and parses (PROPOSAL §16.1, §16.2). Emits one finding per
+ * affected item — the missing-snapshot case (publish-blocking error) and the
+ * corrupt-snapshot case (publish-blocking error, distinct headline so the user knows
+ * "the file is there but the bytes are bad" vs "the file is gone"). Both repair via
+ * `templates.rebind-item-to-current`.
+ */
+declare const templateSnapshotIntegrityDiagnostic: DiagnosticCheck;
+/**
+ * Rebind an item's `template` field from `<name>@v<N>` to `<name>` (current). Used for
+ * the missing/corrupt snapshot repair: the item's pin is lost (the snapshot was the
+ * intent), but the item itself stays, and shows up in the pending-migrations list so
+ * its fields can be reconciled with current. Idempotent: a write of the same JSON is
+ * a no-op semantically.
+ */
+declare const rebindItemToCurrentRepair: Repair;
+/**
+ * Snapshot exists but its current sibling is missing (PROPOSAL §16.4). Someone deleted
+ * `templates/article.html` and left `templates/article@v1.html` behind. The Health page
+ * surfaces this with the `copy-snapshot-to-current` repair — promotes the snapshot to
+ * be the current.
+ */
+declare const templateSuffixConflictDiagnostic: DiagnosticCheck;
+/**
+ * Copy a snapshot's bytes to the current path (PROPOSAL §16.4 repair). The snapshot
+ * itself remains in place; the user can retire it manually later. Idempotent: if the
+ * current already exists, the repair is a no-op (so a stale UI re-firing the repair
+ * never silently overwrites real work).
+ */
+declare const copySnapshotToCurrentRepair: Repair;
+/**
+ * Count items whose current-template binding has orphan fields (PROPOSAL §10). Read-only
+ * summary — points the user at the Migrations workspace (Phase 2). No auto-repair, since
+ * resolution is per-item (drop / rename / keep) and needs human choice.
+ */
+declare const pendingMigrationsDiagnostic: DiagnosticCheck;
 
-export { type ApiDeps, type ApiRequest, type ApiResponse, type BrandingLogo, type BrandingLogoMeta, type BrandingState, type BrandingStore, FileBrandingStore, InMemoryBrandingStore, MCP_RESOURCES, MCP_TOOLS, type McpCallOptions, type McpResourceDef, type McpToolDef, type McpToolResult, SCAFFOLD_FILES, authorDirectory, authorOptions, buildDefaultDiagnostics, callMcpTool, handleApi, homeTemplateMissingDiagnostic, noPublishedContentDiagnostic, readMcpResource, recreateHomeTemplateRepair };
+export { type ApiDeps, type ApiRequest, type ApiResponse, type BrandingLogo, type BrandingLogoMeta, type BrandingState, type BrandingStore, FileBrandingStore, InMemoryBrandingStore, MCP_RESOURCES, MCP_TOOLS, type McpCallOptions, type McpResourceDef, type McpToolDef, type McpToolResult, SCAFFOLD_FILES, authorDirectory, authorOptions, buildDefaultDiagnostics, callMcpTool, copySnapshotToCurrentRepair, handleApi, homeTemplateMissingDiagnostic, noPublishedContentDiagnostic, pendingMigrationsDiagnostic, readMcpResource, rebindItemToCurrentRepair, recreateHomeTemplateRepair, templateSnapshotIntegrityDiagnostic, templateSuffixConflictDiagnostic };

package/dist/editor-api.js

@@ -1,16 +1,21 @@
 import {
+  analyzeTemplate,
+  applyMigration,
+  baseTemplateName,
   buildAuthoringReference,
   canEdit,
   contentTypeFor,
   createDiagnosticRegistry,
   deriveFields,
   hasRole,
+  isVersionedTemplateName,
   loadComponents,
   loadTemplate,
+  pendingMigrations,
   renderReferenceMarkdown,
   validateSite,
   workingStoreRoundTripDiagnostic
-} from "./chunk-J6VYOB47.js";
+} from "./chunk-UZQ7UP2B.js";
 
 // ../editor-api/src/scaffold.ts
 var HOME_HTML = `<!doctype html>
@@ -254,6 +259,128 @@ async function handleDiagnosticsRoute(deps, req, caller) {
     return json(400, { ok: false, error: error instanceof Error ? error.message : String(error) });
   }
 }
+async function handleMigrationsRoute(deps, req, caller) {
+  if (req.path === "/api/migrations") {
+    if (req.method !== "GET") return json(405, { ok: false, error: "method not allowed" });
+    const result = await pendingMigrations(deps.store);
+    return json(200, {
+      items: result.items,
+      byTemplate: Object.fromEntries(result.byTemplate)
+    });
+  }
+  if (req.path === "/api/migrations/preview") {
+    if (req.method !== "GET") return json(405, { ok: false, error: "method not allowed" });
+    const itemPath2 = req.query.get("path") ?? "";
+    if (itemPath2 === "") return json(400, { ok: false, error: "path query param required" });
+    return previewMigration(deps, itemPath2);
+  }
+  if (req.method !== "POST") return json(405, { ok: false, error: "method not allowed" });
+  void caller;
+  const body = await parseJsonBody(req);
+  if (!isObject(body) || typeof body["path"] !== "string" || !isObject(body["resolution"])) {
+    return json(400, { ok: false, error: "JSON body { path, resolution } required" });
+  }
+  const itemPath = body["path"];
+  const denied = denyWrite(caller, itemPath);
+  if (denied) return denied;
+  try {
+    await applyMigration(deps.store, itemPath, normalizeResolution(body["resolution"]));
+    const refreshed = await pendingMigrations(deps.store);
+    return json(200, {
+      ok: true,
+      items: refreshed.items,
+      byTemplate: Object.fromEntries(refreshed.byTemplate)
+    });
+  } catch (error) {
+    return json(400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+  }
+}
+async function previewMigration(deps, itemPath) {
+  let itemJson;
+  try {
+    itemJson = JSON.parse(await deps.store.readText(itemPath));
+  } catch {
+    return json(404, { ok: false, error: "item not found" });
+  }
+  const tplName = typeof itemJson["template"] === "string" ? itemJson["template"] : "";
+  if (tplName === "") return json(400, { ok: false, error: "item has no template binding" });
+  const baseTpl = tplName.replace(/@v\d+$/, "");
+  const components = await loadComponents(deps.store).catch(() => /* @__PURE__ */ new Map());
+  const currentHtml = await safeReadTemplate(deps.store, baseTpl);
+  const currentFields = currentHtml === null ? [] : deriveFields(currentHtml, components).map((f) => f.name);
+  let leftTpl = null;
+  let leftHtml = null;
+  if (tplName !== baseTpl) {
+    leftTpl = tplName;
+    leftHtml = await safeReadTemplate(deps.store, tplName);
+  } else {
+    const { bestFitSnapshot: pickBestFit } = await import("./index.js");
+    const itemFields2 = Object.keys(
+      typeof itemJson["fields"] === "object" && itemJson["fields"] !== null ? itemJson["fields"] : {}
+    );
+    const best = await pickBestFit(deps.store, baseTpl, itemFields2);
+    if (best !== null) {
+      leftTpl = best;
+      leftHtml = await safeReadTemplate(deps.store, best);
+    }
+  }
+  const measureTpl = tplName === baseTpl ? baseTpl : tplName;
+  const measureHtml = tplName === baseTpl ? currentHtml : leftHtml;
+  const measureFields = measureHtml === null ? [] : deriveFields(measureHtml, components).map((f) => f.name);
+  const itemFields = typeof itemJson["fields"] === "object" && itemJson["fields"] !== null ? itemJson["fields"] : {};
+  const orphans = Object.keys(itemFields).filter((name) => !measureFields.includes(name)).map((name) => ({ name, value: itemFields[name] }));
+  void measureTpl;
+  return json(200, {
+    left: leftHtml === null ? null : { template: leftTpl, html: leftHtml },
+    right: { template: baseTpl, html: currentHtml ?? "" },
+    orphans,
+    missing: [],
+    currentTemplateFields: currentFields
+  });
+}
+async function safeReadTemplate(store, name) {
+  try {
+    return await store.readText(`templates/${name}.html`);
+  } catch {
+    return null;
+  }
+}
+function normalizeResolution(raw) {
+  const drop = Array.isArray(raw["drop"]) ? raw["drop"].filter((v) => typeof v === "string") : [];
+  const keep = Array.isArray(raw["keep"]) ? raw["keep"].filter((v) => typeof v === "string") : [];
+  const rename2 = {};
+  if (isObject(raw["rename"])) {
+    for (const [from, to] of Object.entries(raw["rename"])) {
+      if (typeof to === "string") rename2[from] = to;
+    }
+  }
+  const fill = {};
+  if (isObject(raw["fill"])) {
+    for (const [name, value] of Object.entries(raw["fill"])) {
+      if (typeof value === "string") fill[name] = value;
+    }
+  }
+  return { drop, rename: rename2, keep, fill };
+}
+async function handleStampRoute(deps, req, caller) {
+  if (req.method !== "POST") return json(405, { ok: false, error: "method not allowed" });
+  if (!hasRole(caller, "developer")) {
+    return json(403, { ok: false, error: "developer role required" });
+  }
+  const body = await parseJsonBody(req);
+  if (!isObject(body) || typeof body["name"] !== "string" || body["kind"] !== "template" && body["kind"] !== "component") {
+    return json(400, {
+      ok: false,
+      error: 'JSON body { name, kind: "template" | "component" } required'
+    });
+  }
+  try {
+    const record = await deps.store.stamp(body["name"], body["kind"]);
+    return json(200, record);
+  } catch (error) {
+    return json(400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+  }
+}
 async function handleBrandingRoute(deps, req) {
   if (req.path !== "/api/branding" && req.path !== "/api/branding/logo") return void 0;
   const store = deps.branding;
@@ -322,6 +449,12 @@ async function dispatchApi(deps, req) {
   if (req.path === "/api/admin/diagnostics" || req.path === "/api/admin/diagnostics/repair") {
     return handleDiagnosticsRoute(deps, req, principal);
   }
+  if (req.path === "/api/migrations" || req.path === "/api/migrations/preview" || req.path === "/api/migrations/apply") {
+    return handleMigrationsRoute(deps, req, principal);
+  }
+  if (req.path === "/api/templates/stamp") {
+    return handleStampRoute(deps, req, principal);
+  }
   const get = (key) => req.query.get(key) ?? "";
   switch (req.path) {
     case "/api/list": {
@@ -362,8 +495,12 @@ async function dispatchApi(deps, req) {
       const denied = denyWrite(principal, get("path"));
       if (denied) return denied;
       try {
-        await deps.store.write(get("path"), await req.body());
-        return json(200, { ok: true });
+        const result = await deps.store.write(get("path"), await req.body());
+        return json(200, {
+          ok: true,
+          ...result.stamped !== void 0 && { stamped: result.stamped },
+          ...result.stampIncomplete === true && { stampIncomplete: true }
+        });
       } catch (error) {
         return json(500, { ok: false, error: String(error) });
       }
@@ -610,8 +747,59 @@ var TOOL_SPECS = [
     description: "Compile and publish the whole site. Runs the validation gate first; if anything would break, it reports the problems and writes nothing.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
     toRequest: (_args, token) => request("POST", "/api/publish", {}, void 0, token)
+  },
+  {
+    name: "list_pending_migrations",
+    description: "List content items whose JSON fields don't match their bound template's schema (orphan fields or missing required fields). Use this after a destructive template edit (you'll see a `stamped` record on write_file) to see what needs migrating, or any time to check site-wide drift.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    toRequest: (_args, token) => request("GET", "/api/migrations", {}, void 0, token)
+  },
+  {
+    name: "preview_migration",
+    description: 'For one content item, return the current template HTML, the best-fit snapshot HTML (the "before"), the list of orphan fields with their values, and the names of fields the current template defines. Use this to plan how to migrate (drop, rename, or keep each orphan).',
+    inputSchema: {
+      type: "object",
+      properties: { path: pathArg },
+      required: ["path"],
+      additionalProperties: false
+    },
+    toRequest: (args, token) => request("GET", "/api/migrations/preview", { path: str(args, "path") }, void 0, token)
+  },
+  {
+    name: "apply_migration",
+    description: "Resolve a content item's schema drift in one go. `resolution` is a JSON object: `drop` (array of orphan field names to delete), `rename` (object mapping orphan field name \u2192 current template field name to copy the value into), `keep` (array of orphan field names to leave untouched), and `fill` (object mapping current template field name \u2192 value, for missing required fields). Returns the refreshed pending list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: pathArg,
+        resolution: {
+          type: "string",
+          description: 'A JSON object encoded as a string: { "drop": string[], "rename": { from: to }, "keep": string[], "fill": { name: value } }.'
+        }
+      },
+      required: ["path", "resolution"],
+      additionalProperties: false
+    },
+    toRequest: (args, token) => request(
+      "POST",
+      "/api/migrations/apply",
+      {},
+      JSON.stringify({
+        path: str(args, "path"),
+        resolution: parseResolutionArg(str(args, "resolution"))
+      }),
+      token
+    )
   }
 ];
+function parseResolutionArg(raw) {
+  if (raw === "") return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
 var MCP_TOOLS = TOOL_SPECS.map(
   ({ name, description, inputSchema }) => ({ name, description, inputSchema })
 );
@@ -646,7 +834,12 @@ function buildDefaultDiagnostics() {
   registry.add(workingStoreRoundTripDiagnostic);
   registry.add(homeTemplateMissingDiagnostic);
   registry.add(noPublishedContentDiagnostic);
+  registry.add(templateSnapshotIntegrityDiagnostic);
+  registry.add(templateSuffixConflictDiagnostic);
+  registry.add(pendingMigrationsDiagnostic);
   registry.addRepair(recreateHomeTemplateRepair);
+  registry.addRepair(rebindItemToCurrentRepair);
+  registry.addRepair(copySnapshotToCurrentRepair);
   return registry;
 }
 var HOME_PATH = "templates/home.html";
@@ -690,6 +883,197 @@ var noPublishedContentDiagnostic = {
     ];
   }
 };
+var templateSnapshotIntegrityDiagnostic = {
+  id: "templates.snapshot-integrity",
+  async run({ store }) {
+    const findings = [];
+    const components = await loadComponents(store).catch(() => /* @__PURE__ */ new Map());
+    const items = await collectContentItems(store);
+    const snapshotCache = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      if (!isVersionedTemplateName(item.template)) continue;
+      const kind = "template";
+      const path = `${kind === "template" ? "templates" : "components"}/${item.template}.html`;
+      let state = snapshotCache.get(path);
+      if (state === void 0) {
+        state = await classifySnapshot(store, path, components);
+        snapshotCache.set(path, state);
+      }
+      if (state === "ok") continue;
+      const isMissing = state === "missing";
+      findings.push({
+        id: `templates.${isMissing ? "missing" : "corrupt"}-snapshot:${item.path}`,
+        source: "templates",
+        severity: "error",
+        title: isMissing ? `Pinned snapshot missing: ${path}` : `Pinned snapshot will not parse: ${path}`,
+        detail: isMissing ? `${item.path} pins to ${item.template}, but ${path} does not exist. Restore the snapshot from git/backup, or rebind this item to the current template (its fields will need migration after).` : `${item.path} pins to ${item.template}, but ${path} cannot be parsed as a template. Restore valid bytes from git/backup, or rebind this item to the current template.`,
+        repair: {
+          id: "templates.rebind-item-to-current",
+          label: "Rebind item to current template",
+          args: { itemPath: item.path }
+        }
+      });
+    }
+    return findings;
+  }
+};
+var rebindItemToCurrentRepair = {
+  id: "templates.rebind-item-to-current",
+  async run({ store }, args) {
+    const itemPath = args["itemPath"];
+    if (typeof itemPath !== "string" || itemPath === "") {
+      throw new Error("rebind-item-to-current: missing itemPath arg");
+    }
+    const text = await store.readText(itemPath);
+    const data = JSON.parse(text);
+    if (typeof data !== "object" || data === null) {
+      throw new Error(`rebind-item-to-current: ${itemPath} is not a JSON object`);
+    }
+    const obj = data;
+    if (typeof obj.template !== "string" || !isVersionedTemplateName(obj.template)) {
+      return;
+    }
+    obj.template = baseTemplateName(obj.template);
+    const next = `${JSON.stringify(obj, null, 2)}
+`;
+    await store.write(itemPath, new TextEncoder().encode(next));
+  }
+};
+var templateSuffixConflictDiagnostic = {
+  id: "templates.suffix-conflict",
+  async run({ store }) {
+    const findings = [];
+    for (const dir of ["templates", "components"]) {
+      let entries;
+      try {
+        entries = await store.list(dir);
+      } catch {
+        continue;
+      }
+      const seenBases = /* @__PURE__ */ new Set();
+      const snapshots = [];
+      for (const entry of entries) {
+        if (entry.kind !== "file" || !entry.name.endsWith(".html")) continue;
+        const stem = entry.name.slice(0, -".html".length);
+        if (isVersionedTemplateName(stem)) {
+          snapshots.push({ base: baseTemplateName(stem), snapshotPath: `${dir}/${entry.name}` });
+        } else {
+          seenBases.add(stem);
+        }
+      }
+      for (const snap of snapshots) {
+        if (seenBases.has(snap.base)) continue;
+        const currentPath = `${dir}/${snap.base}.html`;
+        findings.push({
+          id: `templates.suffix-conflict:${snap.snapshotPath}`,
+          source: "templates",
+          severity: "warning",
+          title: `Snapshot has no current sibling: ${snap.snapshotPath}`,
+          detail: `${snap.snapshotPath} exists but ${currentPath} does not. Promote the snapshot to current with "Copy snapshot to current", or rename the snapshot off the @v<N> suffix if it was named this way by mistake.`,
+          repair: {
+            id: "templates.copy-snapshot-to-current",
+            label: "Copy snapshot to current",
+            args: { snapshotPath: snap.snapshotPath, currentPath }
+          }
+        });
+      }
+    }
+    return findings;
+  }
+};
+var copySnapshotToCurrentRepair = {
+  id: "templates.copy-snapshot-to-current",
+  async run({ store }, args) {
+    const snapshotPath = args["snapshotPath"];
+    const currentPath = args["currentPath"];
+    if (typeof snapshotPath !== "string" || typeof currentPath !== "string") {
+      throw new Error("copy-snapshot-to-current: missing snapshotPath or currentPath args");
+    }
+    if (await store.exists(currentPath)) return;
+    const bytes = await store.readBytes(snapshotPath);
+    await store.write(currentPath, bytes);
+  }
+};
+var pendingMigrationsDiagnostic = {
+  id: "content.pending-migrations",
+  async run({ store }) {
+    const components = await loadComponents(store).catch(() => /* @__PURE__ */ new Map());
+    const items = await collectContentItems(store);
+    const templateFieldCache = /* @__PURE__ */ new Map();
+    let pendingCount = 0;
+    for (const item of items) {
+      if (isVersionedTemplateName(item.template)) continue;
+      let expected = templateFieldCache.get(item.template);
+      if (expected === void 0) {
+        const path = `templates/${item.template}.html`;
+        try {
+          const html = await store.readText(path);
+          expected = new Set(deriveFields(html, components).map((f) => f.name));
+        } catch {
+          expected = /* @__PURE__ */ new Set();
+        }
+        templateFieldCache.set(item.template, expected);
+      }
+      const orphans = Object.keys(item.fields).filter((k) => !expected.has(k));
+      if (orphans.length > 0) pendingCount += 1;
+    }
+    if (pendingCount === 0) return [];
+    return [
+      {
+        id: "content.pending-migrations",
+        source: "content",
+        severity: "warning",
+        title: `${pendingCount} item${pendingCount === 1 ? "" : "s"} pending migration`,
+        detail: `${pendingCount} content item${pendingCount === 1 ? "" : "s"} ${pendingCount === 1 ? "has" : "have"} fields not rendered by ${pendingCount === 1 ? "its" : "their"} current template. The Migrations workspace (shipping in Phase 2 of versioning) will resolve these; for now, edit the item JSON to drop or rename the orphan fields. The site continues to publish \u2014 drift is a soft warning, not a publish blocker.`
+      }
+    ];
+  }
+};
+async function collectContentItems(store, dir = "content") {
+  const out = [];
+  let entries;
+  try {
+    entries = await store.list(dir);
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
+    if (entry.kind === "dir") {
+      out.push(...await collectContentItems(store, path));
+      continue;
+    }
+    if (!entry.name.endsWith(".json") || entry.name.startsWith("_")) continue;
+    let data;
+    try {
+      data = JSON.parse(await store.readText(path));
+    } catch {
+      continue;
+    }
+    if (typeof data !== "object" || data === null) continue;
+    const obj = data;
+    const template = obj["template"];
+    if (typeof template !== "string") continue;
+    const fields = obj["fields"];
+    out.push({
+      path,
+      template,
+      fields: typeof fields === "object" && fields !== null ? fields : {}
+    });
+  }
+  return out;
+}
+async function classifySnapshot(store, path, components) {
+  if (!await store.exists(path)) return "missing";
+  try {
+    const html = await store.readText(path);
+    if (html.trim() === "") return "corrupt";
+    analyzeTemplate(html, components);
+    return "ok";
+  } catch {
+    return "corrupt";
+  }
+}
 async function anyPublishedContentItem(store, dir = "content") {
   let entries;
   try {
@@ -822,9 +1206,14 @@ export {
   authorOptions,
   buildDefaultDiagnostics,
   callMcpTool,
+  copySnapshotToCurrentRepair,
   handleApi,
   homeTemplateMissingDiagnostic,
   noPublishedContentDiagnostic,
+  pendingMigrationsDiagnostic,
   readMcpResource,
-  recreateHomeTemplateRepair
+  rebindItemToCurrentRepair,
+  recreateHomeTemplateRepair,
+  templateSnapshotIntegrityDiagnostic,
+  templateSuffixConflictDiagnostic
 };