@cmssy/core 9.1.0 → 9.2.0

package/dist/preflight.cjs

@@ -14,6 +14,159 @@ function resolvePublicUrl(config) {
   return `${base}/public/${config.org}/${config.workspaceSlug}/graphql`;
 }
 
+// src/config.ts
+var DEFAULT_CMSSY_EDITOR_ORIGINS = [
+  "https://cmssy.io",
+  "https://www.cmssy.io"
+];
+
+// src/edit-diagnostics.ts
+var REQUIRED_ENV = [
+  ["org", "CMSSY_ORG_SLUG"],
+  ["workspaceSlug", "CMSSY_WORKSPACE_SLUG"],
+  ["draftSecret", "CMSSY_DRAFT_SECRET"]
+];
+var SETTINGS_FIX = "copy the values from Settings \u2192 Headless in the cmssy dashboard, or run npx @cmssy/cli link";
+async function collectEditDiagnostics(input) {
+  const { config } = input;
+  const checks = [];
+  const missing = REQUIRED_ENV.filter(([key]) => {
+    const value = config[key];
+    return !(typeof value === "string" && value.trim());
+  }).map(([, env]) => env);
+  if (missing.length > 0) {
+    checks.push({
+      name: "configuration",
+      status: "fail",
+      message: `missing environment variables: ${missing.join(", ")}`,
+      fix: SETTINGS_FIX
+    });
+  } else {
+    checks.push({
+      name: "configuration",
+      status: "ok",
+      message: "CMSSY_ORG_SLUG, CMSSY_WORKSPACE_SLUG and CMSSY_DRAFT_SECRET are set"
+    });
+  }
+  const org = config.org?.trim();
+  const workspaceSlug = config.workspaceSlug?.trim();
+  const workspace = org && workspaceSlug ? `${org}/${workspaceSlug}` : null;
+  let previewUrl;
+  if (org && workspaceSlug) {
+    const preflight = {
+      apiUrl: config.apiUrl,
+      org,
+      workspaceSlug,
+      ...input.fetch ? { fetch: input.fetch } : {}
+    };
+    const reachable = await checkWorkspaceReachable(preflight);
+    previewUrl = reachable.previewUrl;
+    checks.push({
+      name: "workspace",
+      status: reachable.status,
+      message: reachable.message,
+      ...reachable.fix ? { fix: reachable.fix } : {}
+    });
+    const draftSecret = config.draftSecret?.trim();
+    if (draftSecret) {
+      checks.push(
+        await diagnoseSecret(
+          { ...preflight, draftSecret },
+          input.providedSecret
+        )
+      );
+    }
+  }
+  if (input.devOrigin) {
+    const preview = checkPreviewUrl(previewUrl ?? null, input.devOrigin);
+    checks.push({
+      name: "preview URL",
+      status: preview.status,
+      message: preview.message,
+      ...preview.fix ? { fix: preview.fix } : {}
+    });
+  }
+  checks.push({
+    name: "frame-ancestors",
+    status: "unknown",
+    message: "CSP blocking cannot be detected from inside the frame - if this page never appears in the editor at all, the likely causes are the preview URL pointing elsewhere or a Content-Security-Policy frame-ancestors that blocks the editor",
+    fix: `frame-ancestors must allow ${DEFAULT_CMSSY_EDITOR_ORIGINS.join(" ")} (cmssyCspHeaders / applyCmssyCsp set this for you)`
+  });
+  return { workspace, checks };
+}
+async function diagnoseSecret(preflight, providedSecret) {
+  const name = "draft secret";
+  if (!providedSecret?.trim()) {
+    return {
+      name,
+      status: "fail",
+      message: "the request carried no cmssySecret - a bare cmssyEdit=1 is never trusted",
+      fix: "open the page from the cmssy editor, which appends the cmssySecret itself"
+    };
+  }
+  const platform = await checkDraftSecret(preflight);
+  if (platform.status === "fail") {
+    return {
+      name,
+      status: "fail",
+      message: `the provided cmssySecret does not match CMSSY_DRAFT_SECRET, and ${platform.message}`,
+      ...platform.fix ? { fix: platform.fix } : {}
+    };
+  }
+  if (platform.status === "ok") {
+    return {
+      name,
+      status: "fail",
+      message: "CMSSY_DRAFT_SECRET matches this workspace, but the cmssySecret sent with the request does not match it",
+      fix: "reload the editor so it opens the preview with the current secret"
+    };
+  }
+  return {
+    name,
+    status: "unknown",
+    message: `could not verify against the platform (${platform.message}); the provided cmssySecret failed local verification against CMSSY_DRAFT_SECRET`,
+    fix: `make sure CMSSY_DRAFT_SECRET matches Settings \u2192 Headless, then reload the editor`
+  };
+}
+var STATUS_LABEL = {
+  ok: "OK",
+  fail: "FAIL",
+  unknown: "?"
+};
+var DIAGNOSTICS_CSS = `
+.cmssy-diagnostics{font:14px/1.6 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;max-width:44rem;margin:3rem auto;padding:0 1.5rem;color:#1f2328}
+.cmssy-diagnostics h1{font-size:1.15rem;margin:0 0 .5rem}
+.cmssy-diagnostics p{margin:.5rem 0}
+.cmssy-diagnostics ul{list-style:none;margin:1.5rem 0;padding:0}
+.cmssy-diagnostics li{margin:0 0 .75rem;padding:.75rem 1rem;border:1px solid #d0d7de;border-radius:6px}
+.cmssy-diagnostics .cmssy-diagnostics-status{font-weight:700;margin-right:.5rem}
+.cmssy-diagnostics .cmssy-diagnostics-ok{color:#1a7f37}
+.cmssy-diagnostics .cmssy-diagnostics-fail{color:#c5273c}
+.cmssy-diagnostics .cmssy-diagnostics-unknown{color:#9a6700}
+.cmssy-diagnostics .cmssy-diagnostics-fix{display:block;margin-top:.25rem;opacity:.75}
+.cmssy-diagnostics .cmssy-diagnostics-note{opacity:.65}
+@media (prefers-color-scheme:dark){
+.cmssy-diagnostics{color:#e6edf3}
+.cmssy-diagnostics li{border-color:#30363d}
+.cmssy-diagnostics .cmssy-diagnostics-ok{color:#3fb950}
+.cmssy-diagnostics .cmssy-diagnostics-fail{color:#f85149}
+.cmssy-diagnostics .cmssy-diagnostics-unknown{color:#d29922}
+}
+`.trim();
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+function renderEditDiagnostics(diagnostics) {
+  const items = diagnostics.checks.map(
+    (check) => `<li><span class="cmssy-diagnostics-status cmssy-diagnostics-${check.status}">${STATUS_LABEL[check.status]}</span><strong>${escapeHtml(check.name)}</strong>: ${escapeHtml(check.message)}${check.fix ? `<span class="cmssy-diagnostics-fix">fix: ${escapeHtml(check.fix)}</span>` : ""}</li>`
+  ).join("");
+  const workspaceLine = diagnostics.workspace ? `<p>workspace: <strong>${escapeHtml(diagnostics.workspace)}</strong></p>` : "";
+  return `<style>${DIAGNOSTICS_CSS}</style><main class="cmssy-diagnostics"><h1>cmssy editor diagnostics</h1><p>The editor request could not be verified, so the editor preview cannot render.</p>${workspaceLine}<ul>${items}</ul><p class="cmssy-diagnostics-note">This page is shown in development only - production keeps serving a 404 here.</p></main>`;
+}
+function renderEditDiagnosticsDocument(diagnostics) {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>cmssy editor diagnostics</title><style>body{margin:0;background:#fff}@media (prefers-color-scheme:dark){body{background:#0d1117}}</style></head><body>${renderEditDiagnostics(diagnostics)}</body></html>`;
+}
+
 // src/preflight.ts
 var CMSSY_ADMIN_ORIGIN = "https://www.cmssy.io";
 var ALLOWED_FRAME_HOSTS = ["cmssy.io", "www.cmssy.io"];
@@ -271,3 +424,6 @@ exports.checkDraftSecret = checkDraftSecret;
 exports.checkFrameAncestors = checkFrameAncestors;
 exports.checkPreviewUrl = checkPreviewUrl;
 exports.checkWorkspaceReachable = checkWorkspaceReachable;
+exports.collectEditDiagnostics = collectEditDiagnostics;
+exports.renderEditDiagnostics = renderEditDiagnostics;
+exports.renderEditDiagnosticsDocument = renderEditDiagnosticsDocument;

package/dist/preflight.d.cts

@@ -1,6 +1,32 @@
 import { F as FetchLike } from './content-client-D0EdiqbQ.cjs';
 import { CmssyClientConfig } from '@cmssy/types';
 
+interface EditDiagnosticsConfig {
+    apiUrl?: string;
+    org?: string;
+    workspaceSlug?: string;
+    draftSecret?: string;
+}
+interface EditDiagnosticsInput {
+    config: EditDiagnosticsConfig;
+    providedSecret?: string | null;
+    devOrigin?: string;
+    fetch?: FetchLike;
+}
+interface EditDiagnosticsCheck {
+    name: string;
+    status: PreflightStatus;
+    message: string;
+    fix?: string;
+}
+interface EditDiagnostics {
+    workspace: string | null;
+    checks: EditDiagnosticsCheck[];
+}
+declare function collectEditDiagnostics(input: EditDiagnosticsInput): Promise<EditDiagnostics>;
+declare function renderEditDiagnostics(diagnostics: EditDiagnostics): string;
+declare function renderEditDiagnosticsDocument(diagnostics: EditDiagnostics): string;
+
 type PreflightStatus = "ok" | "fail" | "unknown";
 interface PreflightResult {
     status: PreflightStatus;
@@ -20,4 +46,4 @@ declare function checkPreviewUrl(previewUrl: string | null | undefined, devOrigi
 declare function checkFrameAncestors(cspHeaderValue: string | null | undefined): PreflightResult;
 declare function buildEditorUrl(config: Pick<CmssyClientConfig, "org" | "workspaceSlug">, pageId?: string): string;
 
-export { type PreflightConfig, type PreflightResult, type PreflightStatus, type WorkspaceReachableResult, buildEditorUrl, checkDraftSecret, checkFrameAncestors, checkPreviewUrl, checkWorkspaceReachable };
+export { type EditDiagnostics, type EditDiagnosticsCheck, type EditDiagnosticsConfig, type EditDiagnosticsInput, type PreflightConfig, type PreflightResult, type PreflightStatus, type WorkspaceReachableResult, buildEditorUrl, checkDraftSecret, checkFrameAncestors, checkPreviewUrl, checkWorkspaceReachable, collectEditDiagnostics, renderEditDiagnostics, renderEditDiagnosticsDocument };

package/dist/preflight.d.ts

@@ -1,6 +1,32 @@
 import { F as FetchLike } from './content-client-D0EdiqbQ.js';
 import { CmssyClientConfig } from '@cmssy/types';
 
+interface EditDiagnosticsConfig {
+    apiUrl?: string;
+    org?: string;
+    workspaceSlug?: string;
+    draftSecret?: string;
+}
+interface EditDiagnosticsInput {
+    config: EditDiagnosticsConfig;
+    providedSecret?: string | null;
+    devOrigin?: string;
+    fetch?: FetchLike;
+}
+interface EditDiagnosticsCheck {
+    name: string;
+    status: PreflightStatus;
+    message: string;
+    fix?: string;
+}
+interface EditDiagnostics {
+    workspace: string | null;
+    checks: EditDiagnosticsCheck[];
+}
+declare function collectEditDiagnostics(input: EditDiagnosticsInput): Promise<EditDiagnostics>;
+declare function renderEditDiagnostics(diagnostics: EditDiagnostics): string;
+declare function renderEditDiagnosticsDocument(diagnostics: EditDiagnostics): string;
+
 type PreflightStatus = "ok" | "fail" | "unknown";
 interface PreflightResult {
     status: PreflightStatus;
@@ -20,4 +46,4 @@ declare function checkPreviewUrl(previewUrl: string | null | undefined, devOrigi
 declare function checkFrameAncestors(cspHeaderValue: string | null | undefined): PreflightResult;
 declare function buildEditorUrl(config: Pick<CmssyClientConfig, "org" | "workspaceSlug">, pageId?: string): string;
 
-export { type PreflightConfig, type PreflightResult, type PreflightStatus, type WorkspaceReachableResult, buildEditorUrl, checkDraftSecret, checkFrameAncestors, checkPreviewUrl, checkWorkspaceReachable };
+export { type EditDiagnostics, type EditDiagnosticsCheck, type EditDiagnosticsConfig, type EditDiagnosticsInput, type PreflightConfig, type PreflightResult, type PreflightStatus, type WorkspaceReachableResult, buildEditorUrl, checkDraftSecret, checkFrameAncestors, checkPreviewUrl, checkWorkspaceReachable, collectEditDiagnostics, renderEditDiagnostics, renderEditDiagnosticsDocument };

package/dist/preflight.js

@@ -12,6 +12,159 @@ function resolvePublicUrl(config) {
   return `${base}/public/${config.org}/${config.workspaceSlug}/graphql`;
 }
 
+// src/config.ts
+var DEFAULT_CMSSY_EDITOR_ORIGINS = [
+  "https://cmssy.io",
+  "https://www.cmssy.io"
+];
+
+// src/edit-diagnostics.ts
+var REQUIRED_ENV = [
+  ["org", "CMSSY_ORG_SLUG"],
+  ["workspaceSlug", "CMSSY_WORKSPACE_SLUG"],
+  ["draftSecret", "CMSSY_DRAFT_SECRET"]
+];
+var SETTINGS_FIX = "copy the values from Settings \u2192 Headless in the cmssy dashboard, or run npx @cmssy/cli link";
+async function collectEditDiagnostics(input) {
+  const { config } = input;
+  const checks = [];
+  const missing = REQUIRED_ENV.filter(([key]) => {
+    const value = config[key];
+    return !(typeof value === "string" && value.trim());
+  }).map(([, env]) => env);
+  if (missing.length > 0) {
+    checks.push({
+      name: "configuration",
+      status: "fail",
+      message: `missing environment variables: ${missing.join(", ")}`,
+      fix: SETTINGS_FIX
+    });
+  } else {
+    checks.push({
+      name: "configuration",
+      status: "ok",
+      message: "CMSSY_ORG_SLUG, CMSSY_WORKSPACE_SLUG and CMSSY_DRAFT_SECRET are set"
+    });
+  }
+  const org = config.org?.trim();
+  const workspaceSlug = config.workspaceSlug?.trim();
+  const workspace = org && workspaceSlug ? `${org}/${workspaceSlug}` : null;
+  let previewUrl;
+  if (org && workspaceSlug) {
+    const preflight = {
+      apiUrl: config.apiUrl,
+      org,
+      workspaceSlug,
+      ...input.fetch ? { fetch: input.fetch } : {}
+    };
+    const reachable = await checkWorkspaceReachable(preflight);
+    previewUrl = reachable.previewUrl;
+    checks.push({
+      name: "workspace",
+      status: reachable.status,
+      message: reachable.message,
+      ...reachable.fix ? { fix: reachable.fix } : {}
+    });
+    const draftSecret = config.draftSecret?.trim();
+    if (draftSecret) {
+      checks.push(
+        await diagnoseSecret(
+          { ...preflight, draftSecret },
+          input.providedSecret
+        )
+      );
+    }
+  }
+  if (input.devOrigin) {
+    const preview = checkPreviewUrl(previewUrl ?? null, input.devOrigin);
+    checks.push({
+      name: "preview URL",
+      status: preview.status,
+      message: preview.message,
+      ...preview.fix ? { fix: preview.fix } : {}
+    });
+  }
+  checks.push({
+    name: "frame-ancestors",
+    status: "unknown",
+    message: "CSP blocking cannot be detected from inside the frame - if this page never appears in the editor at all, the likely causes are the preview URL pointing elsewhere or a Content-Security-Policy frame-ancestors that blocks the editor",
+    fix: `frame-ancestors must allow ${DEFAULT_CMSSY_EDITOR_ORIGINS.join(" ")} (cmssyCspHeaders / applyCmssyCsp set this for you)`
+  });
+  return { workspace, checks };
+}
+async function diagnoseSecret(preflight, providedSecret) {
+  const name = "draft secret";
+  if (!providedSecret?.trim()) {
+    return {
+      name,
+      status: "fail",
+      message: "the request carried no cmssySecret - a bare cmssyEdit=1 is never trusted",
+      fix: "open the page from the cmssy editor, which appends the cmssySecret itself"
+    };
+  }
+  const platform = await checkDraftSecret(preflight);
+  if (platform.status === "fail") {
+    return {
+      name,
+      status: "fail",
+      message: `the provided cmssySecret does not match CMSSY_DRAFT_SECRET, and ${platform.message}`,
+      ...platform.fix ? { fix: platform.fix } : {}
+    };
+  }
+  if (platform.status === "ok") {
+    return {
+      name,
+      status: "fail",
+      message: "CMSSY_DRAFT_SECRET matches this workspace, but the cmssySecret sent with the request does not match it",
+      fix: "reload the editor so it opens the preview with the current secret"
+    };
+  }
+  return {
+    name,
+    status: "unknown",
+    message: `could not verify against the platform (${platform.message}); the provided cmssySecret failed local verification against CMSSY_DRAFT_SECRET`,
+    fix: `make sure CMSSY_DRAFT_SECRET matches Settings \u2192 Headless, then reload the editor`
+  };
+}
+var STATUS_LABEL = {
+  ok: "OK",
+  fail: "FAIL",
+  unknown: "?"
+};
+var DIAGNOSTICS_CSS = `
+.cmssy-diagnostics{font:14px/1.6 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;max-width:44rem;margin:3rem auto;padding:0 1.5rem;color:#1f2328}
+.cmssy-diagnostics h1{font-size:1.15rem;margin:0 0 .5rem}
+.cmssy-diagnostics p{margin:.5rem 0}
+.cmssy-diagnostics ul{list-style:none;margin:1.5rem 0;padding:0}
+.cmssy-diagnostics li{margin:0 0 .75rem;padding:.75rem 1rem;border:1px solid #d0d7de;border-radius:6px}
+.cmssy-diagnostics .cmssy-diagnostics-status{font-weight:700;margin-right:.5rem}
+.cmssy-diagnostics .cmssy-diagnostics-ok{color:#1a7f37}
+.cmssy-diagnostics .cmssy-diagnostics-fail{color:#c5273c}
+.cmssy-diagnostics .cmssy-diagnostics-unknown{color:#9a6700}
+.cmssy-diagnostics .cmssy-diagnostics-fix{display:block;margin-top:.25rem;opacity:.75}
+.cmssy-diagnostics .cmssy-diagnostics-note{opacity:.65}
+@media (prefers-color-scheme:dark){
+.cmssy-diagnostics{color:#e6edf3}
+.cmssy-diagnostics li{border-color:#30363d}
+.cmssy-diagnostics .cmssy-diagnostics-ok{color:#3fb950}
+.cmssy-diagnostics .cmssy-diagnostics-fail{color:#f85149}
+.cmssy-diagnostics .cmssy-diagnostics-unknown{color:#d29922}
+}
+`.trim();
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+function renderEditDiagnostics(diagnostics) {
+  const items = diagnostics.checks.map(
+    (check) => `<li><span class="cmssy-diagnostics-status cmssy-diagnostics-${check.status}">${STATUS_LABEL[check.status]}</span><strong>${escapeHtml(check.name)}</strong>: ${escapeHtml(check.message)}${check.fix ? `<span class="cmssy-diagnostics-fix">fix: ${escapeHtml(check.fix)}</span>` : ""}</li>`
+  ).join("");
+  const workspaceLine = diagnostics.workspace ? `<p>workspace: <strong>${escapeHtml(diagnostics.workspace)}</strong></p>` : "";
+  return `<style>${DIAGNOSTICS_CSS}</style><main class="cmssy-diagnostics"><h1>cmssy editor diagnostics</h1><p>The editor request could not be verified, so the editor preview cannot render.</p>${workspaceLine}<ul>${items}</ul><p class="cmssy-diagnostics-note">This page is shown in development only - production keeps serving a 404 here.</p></main>`;
+}
+function renderEditDiagnosticsDocument(diagnostics) {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>cmssy editor diagnostics</title><style>body{margin:0;background:#fff}@media (prefers-color-scheme:dark){body{background:#0d1117}}</style></head><body>${renderEditDiagnostics(diagnostics)}</body></html>`;
+}
+
 // src/preflight.ts
 var CMSSY_ADMIN_ORIGIN = "https://www.cmssy.io";
 var ALLOWED_FRAME_HOSTS = ["cmssy.io", "www.cmssy.io"];
@@ -264,4 +417,4 @@ function buildEditorUrl(config, pageId) {
   return pageId ? `${base}?pageId=${encodeURIComponent(pageId)}` : base;
 }
 
-export { buildEditorUrl, checkDraftSecret, checkFrameAncestors, checkPreviewUrl, checkWorkspaceReachable };
+export { buildEditorUrl, checkDraftSecret, checkFrameAncestors, checkPreviewUrl, checkWorkspaceReachable, collectEditDiagnostics, renderEditDiagnostics, renderEditDiagnosticsDocument };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmssy/core",
-  "version": "9.1.0",
+  "version": "9.2.0",
   "description": "Framework-agnostic cmssy client: content, commerce, config, editor protocol. No React, no Next.",
   "keywords": [
     "cmssy",