@caltho/site-kit 0.1.0 → 0.2.0

package/dist/schema.js

@@ -0,0 +1,237 @@
+// Working with a site's declaration as data, with no zod and nothing else: CalOS (its server and its
+// editor in the browser) has only the JSON Schema a site's build wrote, not the site's code. From it:
+// check content with messages a person can act on, make a blank new item (a block, a list entry),
+// and find the kinds of block a site has. Also the checks that need no schema at all (pages, home,
+// links), and readable places in the content.
+const unions = (s) => s.anyOf ?? s.oneOf;
+/** Follows a `$ref` to its definition in the same document. */
+export function resolve(s, root) {
+    if (!s.$ref)
+        return s;
+    const name = s.$ref.replace(/^#\/\$defs\//, "");
+    return root.$defs?.[name] ?? s;
+}
+const kind = (s) => (Array.isArray(s.type) ? s.type.find((t) => t !== "null") : s.type);
+const isNull = (s) => s.type === "null";
+/** A union of objects told apart by a `type` field: its branches by that field's value; else null. */
+export function branches(s, root) {
+    const u = unions(resolve(s, root));
+    if (!u)
+        return null;
+    const out = {};
+    for (const b0 of u) {
+        const b = resolve(b0, root);
+        const t = b.properties?.type?.const ?? b.properties?.type?.enum?.[0];
+        if (typeof t !== "string")
+            return null;
+        out[t] = b;
+    }
+    return out;
+}
+/** The kinds of block (or any discriminated list item) a list's items can be, in the order the site gave them. */
+export function kindsOf(items, root) {
+    return Object.keys(branches(items, root) ?? {});
+}
+const words = (path) => path.filter((p) => typeof p === "string").at(-1);
+/** What's wrong with `value` against `schema`, as places and plain messages. */
+export function validate(schema, value, root = schema, path = []) {
+    const s = resolve(schema, root);
+    const issues = [];
+    const at = (message) => issues.push({ path, message: s["x-error"] ?? message });
+    const u = unions(s);
+    if (u) {
+        if (value === null && u.some(isNull))
+            return [];
+        const by = branches(s, root);
+        if (by) {
+            const t = value && typeof value === "object" ? value.type : undefined;
+            const branch = typeof t === "string" ? by[t] : undefined;
+            if (!branch)
+                return [{ path: [...path, "type"], message: `Choose one of: ${Object.keys(by).join(", ")}` }];
+            return validate(branch, value, root, path);
+        }
+        // Any one of them will do; if none does, say what's wrong with the nearest.
+        const tried = u.filter((b) => !isNull(b)).map((b) => validate(b, value, root, path));
+        return tried.some((t) => !t.length) ? [] : tried.sort((a, b) => a.length - b.length)[0] ?? [];
+    }
+    if (s.const !== undefined)
+        return value === s.const ? [] : [{ path, message: `Should be ${JSON.stringify(s.const)}` }];
+    if (s.enum)
+        return s.enum.includes(value) ? [] : [{ path, message: `Choose one of: ${s.enum.join(", ")}` }];
+    switch (kind(s)) {
+        case "object": {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return [{ path, message: "Should be a group of fields" }];
+            const o = value;
+            for (const key of s.required ?? []) {
+                if (o[key] === undefined || o[key] === null)
+                    issues.push({ path: [...path, key], message: "This is needed" });
+            }
+            for (const [key, sub] of Object.entries(s.properties ?? {})) {
+                if (o[key] === undefined || o[key] === null)
+                    continue;
+                issues.push(...validate(sub, o[key], root, [...path, key]));
+            }
+            return issues;
+        }
+        case "array": {
+            if (!Array.isArray(value))
+                return [{ path, message: "Should be a list" }];
+            if (s.minItems && value.length < s.minItems)
+                at(s.minItems === 1 ? "Add at least one" : `Add at least ${s.minItems}`);
+            if (s.maxItems && value.length > s.maxItems)
+                at(`At most ${s.maxItems}`);
+            if (s.items)
+                value.forEach((v, i) => issues.push(...validate(s.items, v, root, [...path, i])));
+            return issues;
+        }
+        case "string": {
+            if (typeof value !== "string")
+                return [{ path, message: "Should be text" }];
+            if (s.minLength && value.trim().length < s.minLength)
+                return [{ path, message: s.minLength === 1 ? "This can't be empty" : `At least ${s.minLength} characters` }];
+            if (s.maxLength && value.length > s.maxLength)
+                return [{ path, message: `At most ${s.maxLength} characters` }];
+            if (s.format === "email" && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
+                return [{ path, message: "An email address like name@example.com" }];
+            if (s.format === "uri" && !/^[a-z][a-z0-9+.-]*:\/\/\S+$/i.test(value))
+                return [{ path, message: "A full address starting https://" }];
+            if (s.pattern && !safeRegex(s.pattern).test(value))
+                return [{ path, message: s["x-error"] ?? `That doesn't look right` }];
+            return [];
+        }
+        case "integer":
+        case "number": {
+            if (typeof value !== "number" || !Number.isFinite(value))
+                return [{ path, message: "Should be a number" }];
+            if (kind(s) === "integer" && !Number.isInteger(value))
+                return [{ path, message: "Should be a whole number" }];
+            if (s.minimum !== undefined && value < s.minimum)
+                return [{ path, message: `At least ${s.minimum}` }];
+            if (s.maximum !== undefined && value > s.maximum)
+                return [{ path, message: `At most ${s.maximum}` }];
+            return [];
+        }
+        case "boolean":
+            return typeof value === "boolean" ? [] : [{ path, message: "Should be yes or no" }];
+        default:
+            return [];
+    }
+}
+const cache = new Map();
+function safeRegex(pattern) {
+    let r = cache.get(pattern);
+    if (!r) {
+        try {
+            r = new RegExp(pattern);
+        }
+        catch {
+            r = /.*/s;
+        }
+        cache.set(pattern, r);
+    }
+    return r;
+}
+/** A blank value for a schema: what a new list entry or block starts as, with what's needed in place. */
+export function blank(schema, root = schema, kindOfBlock) {
+    const s = resolve(schema, root);
+    if (s.default !== undefined)
+        return structuredClone(s.default);
+    const u = unions(s);
+    if (u) {
+        const by = branches(s, root);
+        if (by)
+            return blank(by[kindOfBlock ?? Object.keys(by)[0]], root);
+        return blank(u.find((b) => !isNull(b)) ?? u[0], root);
+    }
+    if (s.const !== undefined)
+        return s.const;
+    if (s.enum)
+        return s.enum[0];
+    switch (kind(s)) {
+        case "object": {
+            const out = {};
+            for (const [key, sub] of Object.entries(s.properties ?? {})) {
+                const r = resolve(sub, root);
+                if (s.required?.includes(key) || r.default !== undefined)
+                    out[key] = blank(sub, root);
+            }
+            return out;
+        }
+        case "array": {
+            const n = s.minItems ?? 0;
+            return Array.from({ length: n }, () => blank(s.items ?? {}, root));
+        }
+        case "boolean":
+            return false;
+        case "integer":
+        case "number":
+            return s.minimum ?? 0;
+        default:
+            return "";
+    }
+}
+/**
+ * What's wrong with a site's content that no field's shape can say: two pages at one path, no home
+ * page, a link to a page that isn't there or to a part of a page that isn't. Pure, on the content as
+ * data, so CalOS can run the same check on a draft as the build does.
+ */
+export function checkStructure(site) {
+    const issues = [];
+    const paths = new Set();
+    site.pages.forEach((p, i) => {
+        if (paths.has(p.path))
+            issues.push({ path: ["pages", i, "path"], message: `Two pages at ${p.path}` });
+        paths.add(p.path);
+    });
+    if (!paths.has("/"))
+        issues.push({ path: ["pages"], message: "There's no home page: add a page with path /" });
+    return [...issues, ...linkIssues(site)];
+}
+/** Every link to a page of the site must land on one, and every link to a part of a page must have that part. */
+function linkIssues(site) {
+    const issues = [];
+    const ids = new Map(site.pages.map((p) => [p.path, new Set(p.blocks.map((b) => b.id).filter(Boolean))]));
+    const visit = (value, path, pagePath) => {
+        if (Array.isArray(value))
+            value.forEach((v, i) => visit(v, [...path, i], pagePath));
+        else if (value && typeof value === "object") {
+            for (const [k, v] of Object.entries(value)) {
+                if (k === "href" && typeof v === "string" && (v.startsWith("#") || v.startsWith("/"))) {
+                    const to = v.startsWith("#") && pagePath ? pagePath + v : v;
+                    const [p, hash] = to.split("#");
+                    const target = p.split("?")[0];
+                    if (!ids.has(target))
+                        issues.push({ path: [...path, k], message: `No page at ${target}` });
+                    else if (hash && !ids.get(target).has(hash))
+                        issues.push({ path: [...path, k], message: `${target} has no block with id "${hash}"` });
+                }
+                else
+                    visit(v, [...path, k], pagePath);
+            }
+        }
+    };
+    site.pages.forEach((p, i) => visit(p.blocks, ["pages", i, "blocks"], p.path));
+    for (const [k, v] of Object.entries(site))
+        if (k !== "pages" && k !== "redirects")
+            visit(v, [k], null);
+    return issues;
+}
+/** "pages[2] (/services/) › blocks[1] (services) › items[0].title", readable in a build log or an editor. */
+export function describePath(raw, path) {
+    let at = raw;
+    const out = [];
+    for (const key of path) {
+        at = at && typeof at === "object" ? at[key] : undefined;
+        if (typeof key === "number") {
+            const o = at;
+            const label = o && typeof o === "object" ? (o.path ?? o.type ?? o.title ?? o.name ?? o.label) : undefined;
+            out[out.length - 1] = `${out[out.length - 1] ?? ""}[${key}]${typeof label === "string" ? ` (${label})` : ""}`;
+        }
+        else
+            out.push(String(key));
+    }
+    return out.join(" › ") || "site.json";
+}
+/** The last named field in a path, for a short label. */
+export const fieldOf = words;

package/dist/seo.d.ts

@@ -17,13 +17,15 @@ export declare function ldJson(data: unknown): string;
 export declare function robotsTxt(site: Site): string;
 /** Every page search engines should list, at its canonical address. */
 export declare function sitemapXml(site: Site): string;
+/** Where CalOS's preview draws a draft (./next/preview.tsx): framed by CalOS, never indexed. */
+export declare const PREVIEW_PATH = "/calos-preview";
 /**
  * Cloudflare Pages' `_headers`: the security headers our site checks look for (the content
  * security policy itself is in each page, with hashes of the page's own scripts and styles), long
  * caching for the fingerprinted assets, and `noindex` on the preview addresses (<site>.caltho.site
  * and <project>.pages.dev) so only the real domain is in search results.
  */
-export declare function headersFile(): string;
+export declare function headersFile(editors?: string[]): string;
 /**
  * The site's `_redirects`: CalOS's list for this site when the build is given its address
  * (CALOS_REDIRECTS_URL, the Website › Redirects page's list), otherwise the content's own. A

package/dist/seo.js

@@ -75,7 +75,7 @@ export function breadcrumbData(site, page) {
     const crumbs = [{ name: "Home", path: "/" }];
     const parts = page.path.split("/").filter(Boolean);
     parts.forEach((_, i) => {
-        const path = `/${parts.slice(0, i + 1).join("/")}/`;
+        const path = `/${parts.slice(0, i + 1).join("/")}${site.trailingSlash === false ? "" : "/"}`;
         const p = site.pages.find((x) => x.path === path);
         if (p)
             crumbs.push({ name: p.menu ?? p.title, path });
@@ -99,19 +99,25 @@ export function sitemapXml(site) {
     const urls = site.pages.filter((p) => !p.noindex).map((p) => `  <url><loc>${canonical(site, p.path)}</loc></url>`);
     return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls.join("\n")}\n</urlset>\n`;
 }
+/** Where CalOS's preview draws a draft (./next/preview.tsx): framed by CalOS, never indexed. */
+export const PREVIEW_PATH = "/calos-preview";
 /**
  * Cloudflare Pages' `_headers`: the security headers our site checks look for (the content
  * security policy itself is in each page, with hashes of the page's own scripts and styles), long
  * caching for the fingerprinted assets, and `noindex` on the preview addresses (<site>.caltho.site
  * and <project>.pages.dev) so only the real domain is in search results.
  */
-export function headersFile() {
+export function headersFile(editors = []) {
+    // Every page refuses to be framed (X-Frame-Options, which every browser honours), but the
+    // preview: there, only the CalOS addresses the build was given (./next/preview.tsx), which is
+    // why the refusal isn't also a frame-ancestors policy on every page, which the preview's couldn't
+    // loosen. With no CalOS addresses, the preview refuses too.
+    const preview = editors.length ? `  ! X-Frame-Options\n  Content-Security-Policy: frame-ancestors ${editors.join(" ")}\n` : "";
     return `/*
   X-Content-Type-Options: nosniff
   Referrer-Policy: strict-origin-when-cross-origin
   Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=()
   X-Frame-Options: DENY
-  Content-Security-Policy: frame-ancestors 'none'
   Strict-Transport-Security: max-age=31536000
 
 /_next/static/*
@@ -123,6 +129,10 @@ export function headersFile() {
 /_fonts/*
   Cache-Control: public, max-age=31536000, immutable
 
+${PREVIEW_PATH}
+${preview}  X-Robots-Tag: noindex
+  Cache-Control: no-store
+
 https://:project.pages.dev/*
   X-Robots-Tag: noindex
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caltho/site-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "What every Caltho site is built with: the contract with CalOS (content, and how a site declares what is editable), images, search and security, and the checks",
   "license": "MIT",
   "type": "module",
@@ -32,8 +32,18 @@
       "default": "./dist/lib.js"
     },
     "./next": {
-      "types": "./dist/next/index.d.ts",
+      "types": "./dist/next/index.server.d.ts",
+      "react-server": "./dist/next/index.server.js",
+      "node": "./dist/next/index.server.js",
       "default": "./dist/next/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "default": "./dist/schema.js"
+    },
+    "./next/preview": {
+      "types": "./dist/next/preview.d.ts",
+      "default": "./dist/next/preview.js"
     }
   },
   "engines": {