@cosmicdrift/kumiko-bundled-features 0.145.0 → 0.146.0

package/src/page-render/__tests__/layout.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { wrapInLayout } from "../layout";
+
+describe("wrapInLayout :: seo (opt-in OG/JSON-LD extension)", () => {
+  test("without `seo` — unchanged minimal title+description head (no regression)", () => {
+    const html = wrapInLayout({
+      title: "About",
+      bodyHtml: "<p>x</p>",
+      lang: "en",
+      description: "About us",
+    });
+    expect(html).toContain("<title>About</title>");
+    expect(html).toContain('<meta name="description" content="About us">');
+    expect(html).not.toContain("og:title");
+    expect(html).not.toContain("application/ld+json");
+  });
+
+  test("with `seo` — emits OG/canonical/JSON-LD via the shared apex head renderer", () => {
+    const html = wrapInLayout({
+      title: "About",
+      bodyHtml: "<p>x</p>",
+      lang: "en",
+      description: "About us",
+      seo: {
+        canonicalUrl: "https://acme.test/about",
+        ogImage: "https://acme.test/og.png",
+        siteName: "Acme",
+        schemaJson: { "@context": "https://schema.org", "@type": "WebPage", name: "About" },
+      },
+    });
+    expect(html).toContain("<title>About</title>");
+    expect(html).toContain('<meta property="og:title" content="About" />');
+    expect(html).toContain('<meta property="og:description" content="About us" />');
+    expect(html).toContain('<link rel="canonical" href="https://acme.test/about" />');
+    expect(html).toContain('<meta property="og:image" content="https://acme.test/og.png" />');
+    expect(html).toContain('<meta property="og:site_name" content="Acme" />');
+    expect(html).toContain('<script type="application/ld+json">');
+    expect(html).toContain('"@type":"WebPage"');
+    // no-`seo` minimal-description meta must NOT also appear (headTags replaces it)
+    expect(html).not.toContain('<meta name="description" content="About us">');
+  });
+
+  test("with `seo` — escapes title/description same as the non-seo path", () => {
+    const html = wrapInLayout({
+      title: "<script>alert(1)</script>",
+      bodyHtml: "x",
+      lang: "en",
+      seo: {},
+    });
+    expect(html).not.toContain("<script>alert(1)</script>");
+    expect(html).toContain("&lt;script&gt;");
+  });
+});

package/src/page-render/index.ts

@@ -12,6 +12,6 @@ export {
   cachedSecurePageResponse,
 } from "./cached-page-response";
 export { sanitizeTenantCss } from "./css-sanitize";
-export { TENANT_CONTENT_ATTR, tenantStyleBlock, wrapInLayout } from "./layout";
+export { type SeoHeadInput, TENANT_CONTENT_ATTR, tenantStyleBlock, wrapInLayout } from "./layout";
 export { renderSafeMarkdown } from "./markdown";
 export { securePageHeaders } from "./security-headers";

package/src/page-render/layout.ts

@@ -1,7 +1,13 @@
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { type ApexHead, renderApexHeadTags } from "@cosmicdrift/kumiko-headless/apex";
 import { type BrandingTokens, brandingHeaderHtml, brandingStyleBlock } from "./branding";
 import { sanitizeTenantCss } from "./css-sanitize";
 
+// Optional OG/JSON-LD/canonical extension for wrapInLayout — the same field
+// set renderApexPage accepts, minus title/description/lang (those come from
+// wrapInLayout's own opts, so callers don't repeat them).
+export type SeoHeadInput = Omit<ApexHead, "title" | "description" | "lang">;
+
 // Attribute marking the content container. The page body lives in
 // `<main data-tenant-content>`; tenant custom CSS is scoped to its descendants
 // and host containment clips its paint to this box. A custom wrapLayout that
@@ -52,6 +58,9 @@ export function wrapInLayout(opts: {
   lang: string;
   description?: string | null;
   branding?: BrandingTokens;
+  /** Adds Open Graph/Twitter/canonical/JSON-LD tags via the shared apex head
+   *  renderer. Omitted → unchanged minimal title+description behavior. */
+  seo?: SeoHeadInput;
 }): string {
   const themeStyleHtml = opts.branding ? brandingStyleBlock(opts.branding) : "";
   const header = opts.branding ? brandingHeaderHtml(opts.branding) : "";
@@ -69,12 +78,17 @@ export function wrapInLayout(opts: {
   const metaDescription = description
     ? `\n<meta name="description" content="${escapeHtmlAttr(description)}">`
     : "";
+  // Without `seo`: identical title+description emission as before (no
+  // behavior change for legal-pages/managed-pages callers that don't pass it).
+  const headHtml = opts.seo
+    ? renderApexHeadTags({ title: opts.title, description, lang: opts.lang, ...opts.seo })
+    : `<title>${escapeHtml(opts.title)}</title>${metaDescription}`;
   return `<!doctype html>
 <html lang="${escapeHtmlAttr(opts.lang)}">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtml(opts.title)}</title>${metaDescription}
+${headHtml}
 <style>
   :root { --accent: #0066cc; --page-max-width: 720px; }
   body { font-family: system-ui, -apple-system, sans-serif; max-width: var(--page-max-width);

package/src/seo/__tests__/llms-txt.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { buildLlmsTxt } from "../llms-txt";
+
+describe("buildLlmsTxt", () => {
+  test("emits H1 title + blockquote summary", () => {
+    const text = buildLlmsTxt({ title: "Acme", summary: "Acme does things." });
+    expect(text).toStartWith("# Acme\n\n> Acme does things.");
+  });
+
+  test("emits ## sections with markdown links", () => {
+    const text = buildLlmsTxt({
+      title: "Acme",
+      summary: "s",
+      sections: [
+        {
+          heading: "Pages",
+          links: [{ title: "About", url: "https://acme.test/about", desc: "About us" }],
+        },
+      ],
+    });
+    expect(text).toContain("## Pages");
+    expect(text).toContain("- [About](https://acme.test/about): About us");
+  });
+
+  test("empty sections are omitted, no trailing section markers", () => {
+    const text = buildLlmsTxt({
+      title: "Acme",
+      summary: "s",
+      sections: [{ heading: "Empty", links: [] }],
+    });
+    expect(text).not.toContain("## Empty");
+  });
+
+  test("no summary → no blockquote line", () => {
+    const text = buildLlmsTxt({ title: "Acme", summary: "" });
+    expect(text).toBe("# Acme\n");
+  });
+});

package/src/seo/__tests__/robots-txt.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { buildRobotsTxt } from "../robots-txt";
+
+describe("buildRobotsTxt", () => {
+  test("allow: true → no Disallow rule", () => {
+    expect(buildRobotsTxt({ allow: true })).toBe("User-agent: *\nDisallow:\n");
+  });
+
+  test("allow: false → Disallow: /", () => {
+    expect(buildRobotsTxt({ allow: false })).toBe("User-agent: *\nDisallow: /\n");
+  });
+
+  test("sitemapUrl appends a Sitemap line", () => {
+    expect(buildRobotsTxt({ allow: true, sitemapUrl: "https://acme.test/sitemap.xml" })).toBe(
+      "User-agent: *\nDisallow:\nSitemap: https://acme.test/sitemap.xml\n",
+    );
+  });
+});

package/src/seo/__tests__/schema-builders.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { faqPageSchema, organizationSchema, webPageSchema } from "../schema-builders";
+
+describe("organizationSchema", () => {
+  test("minimal input", () => {
+    expect(organizationSchema({ name: "Acme" })).toEqual({
+      "@context": "https://schema.org",
+      "@type": "Organization",
+      name: "Acme",
+    });
+  });
+
+  test("full input", () => {
+    expect(
+      organizationSchema({
+        name: "Acme",
+        url: "https://acme.test",
+        logoUrl: "https://acme.test/logo.png",
+        sameAs: ["https://x.com/acme"],
+      }),
+    ).toEqual({
+      "@context": "https://schema.org",
+      "@type": "Organization",
+      name: "Acme",
+      url: "https://acme.test",
+      logo: "https://acme.test/logo.png",
+      sameAs: ["https://x.com/acme"],
+    });
+  });
+});
+
+describe("webPageSchema", () => {
+  test("emits WebPage type", () => {
+    expect(webPageSchema({ name: "About", url: "https://acme.test/about" })).toMatchObject({
+      "@type": "WebPage",
+      name: "About",
+      url: "https://acme.test/about",
+    });
+  });
+});
+
+describe("faqPageSchema", () => {
+  test("maps question/answer pairs to mainEntity", () => {
+    const schema = faqPageSchema([{ question: "Q1?", answer: "A1." }]);
+    expect(schema).toEqual({
+      "@context": "https://schema.org",
+      "@type": "FAQPage",
+      mainEntity: [
+        {
+          "@type": "Question",
+          name: "Q1?",
+          acceptedAnswer: { "@type": "Answer", text: "A1." },
+        },
+      ],
+    });
+  });
+});

package/src/seo/__tests__/seo.integration.test.ts

@@ -0,0 +1,258 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createLegalPagesFeature } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
+import {
+  createManagedPagesFeature,
+  pageEntity,
+} from "@cosmicdrift/kumiko-bundled-features/managed-pages";
+import { seedPage } from "@cosmicdrift/kumiko-bundled-features/managed-pages/seeding";
+import {
+  createTextContentApi,
+  createTextContentFeature,
+  textBlockEntity,
+} from "@cosmicdrift/kumiko-bundled-features/text-content";
+import { seedTextBlock } from "@cosmicdrift/kumiko-bundled-features/text-content/seeding";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createConfigAccessorFactory, createConfigFeature } from "../../config/feature";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { SEO_CONFIG_QN } from "../constants";
+import { createSeoFeature, runSeoBootCheck } from "../feature";
+
+const TENANT_A = "11111111-1111-4111-8111-111111111111";
+
+let stack: TestStack;
+
+const seo = createSeoFeature({
+  sitemapEntries: (host) => [{ loc: `https://${host}/`, changefreq: "daily" }],
+  includeLegalPages: true,
+  managedPages: {
+    resolveApexTenant: (host) => (host.startsWith("a.") ? TENANT_A : null),
+  },
+});
+const managed = createManagedPagesFeature({
+  resolveApexTenant: (host) => (host.startsWith("a.") ? TENANT_A : null),
+});
+const legal = createLegalPagesFeature();
+const configFeature = createConfigFeature();
+const textContent = createTextContentFeature();
+
+beforeAll(async () => {
+  const resolver = createConfigResolver();
+  stack = await setupTestStack({
+    features: [configFeature, textContent, managed, legal, seo],
+    anonymousAccess: {
+      tenantExists: async (id) => id === TENANT_A || id === SYSTEM_TENANT_ID,
+    },
+    extraContext: ({ registry, db }) => ({
+      configResolver: resolver,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      textContent: createTextContentApi(db),
+    }),
+  });
+  await unsafeCreateEntityTable(stack.db, pageEntity);
+  await unsafeCreateEntityTable(stack.db, textBlockEntity);
+  await unsafePushTables(stack.db, { configValuesTable });
+  await createEventsTable(stack.db);
+
+  await seedTextBlock(stack.db, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug: "imprint",
+    lang: "de",
+    title: "Impressum",
+    body: "## Test\n\nAcme",
+  });
+  await seedTextBlock(stack.db, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug: "privacy",
+    lang: "de",
+    title: "Datenschutz",
+    body: "## Test\n\nAcme",
+  });
+
+  await seedPage(stack.db, {
+    tenantId: TENANT_A,
+    slug: "about",
+    lang: "en",
+    title: "About",
+    body: "# About",
+    published: true,
+  });
+  await seedPage(stack.db, {
+    tenantId: TENANT_A,
+    slug: "draft",
+    lang: "en",
+    title: "Draft",
+    body: "# Draft",
+    published: false,
+  });
+
+  const admin = createTestUser({ id: 1, roles: ["TenantAdmin"], tenantId: TENANT_A });
+  await stack.http.writeOk(
+    "config:write:set",
+    { key: SEO_CONFIG_QN.organizationName, value: "Acme" },
+    admin,
+  );
+  await stack.http.writeOk(
+    "config:write:set",
+    { key: SEO_CONFIG_QN.llmsSummary, value: "Acme builds things." },
+    admin,
+  );
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("seo :: GET /sitemap.xml", () => {
+  test("merges the app callback + legal-pages routes + managed-pages published slugs", async () => {
+    const res = await stack.app.request("http://a.example.com/sitemap.xml");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/xml");
+    const xml = await res.text();
+    expect(xml).toContain("<loc>https://a.example.com/</loc>");
+    expect(xml).toContain("<loc>http://a.example.com/legal/impressum</loc>");
+    expect(xml).toContain("<loc>http://a.example.com/p/about</loc>");
+    expect(xml).not.toContain("/p/draft");
+  });
+
+  test("cache-control revalidate + etag", async () => {
+    const res = await stack.app.request("http://a.example.com/sitemap.xml");
+    expect(res.headers.get("cache-control")).toBe("public, max-age=300, must-revalidate");
+    expect(res.headers.get("etag")).toBeTruthy();
+  });
+
+  test("host without a managed-pages tenant → callback + legal-pages entries only", async () => {
+    const res = await stack.app.request("http://unknown.example.com/sitemap.xml");
+    expect(res.status).toBe(200);
+    const xml = await res.text();
+    expect(xml).toContain("<loc>https://unknown.example.com/</loc>");
+    expect(xml).toContain("/legal/impressum");
+    expect(xml).not.toContain("/p/about");
+  });
+});
+
+describe("seo :: GET /llms.txt", () => {
+  test("emits org name + summary + a Pages section with all entries", async () => {
+    const res = await stack.app.request("http://a.example.com/llms.txt");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/plain");
+    const text = await res.text();
+    expect(text).toStartWith("# Acme");
+    expect(text).toContain("> Acme builds things.");
+    expect(text).toContain("## Pages");
+    expect(text).toContain("http://a.example.com/p/about");
+  });
+});
+
+describe("seo :: GET /robots.txt (not registered without robotsPolicy)", () => {
+  test("404 — no route registered", async () => {
+    const res = await stack.app.request("http://a.example.com/robots.txt");
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("seo :: GET /robots.txt (opted in)", () => {
+  let robotsStack: TestStack;
+
+  beforeAll(async () => {
+    const seoWithRobots = createSeoFeature({
+      sitemapEntries: () => [],
+      includeLegalPages: true,
+      robotsPolicy: (host) => ({
+        allow: host !== "staging.example.com",
+        sitemapUrl: `https://${host}/sitemap.xml`,
+      }),
+    });
+    robotsStack = await setupTestStack({
+      features: [createConfigFeature(), seoWithRobots],
+      anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
+    });
+  });
+
+  afterAll(async () => {
+    await robotsStack.cleanup();
+  });
+
+  test("allow host → no Disallow rule + Sitemap line", async () => {
+    const res = await robotsStack.app.request("http://prod.example.com/robots.txt");
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    expect(text).toBe("User-agent: *\nDisallow:\nSitemap: https://prod.example.com/sitemap.xml\n");
+  });
+
+  test("disallowed host → Disallow: /", async () => {
+    const res = await robotsStack.app.request("http://staging.example.com/robots.txt");
+    const text = await res.text();
+    expect(text).toContain("Disallow: /");
+  });
+});
+
+describe("seo :: runSeoBootCheck (direct unit-tests)", () => {
+  test("has a source (non-empty callback) → log.info, no throw", async () => {
+    const infos: string[] = [];
+    await expect(
+      runSeoBootCheck({
+        sitemapEntries: () => [{ loc: "https://x.test/" }],
+        includeLegalPages: false,
+        hasManagedPages: false,
+        log: { info: (m) => infos.push(m) },
+      }),
+    ).resolves.toBeUndefined();
+    expect(infos).toHaveLength(1);
+  });
+
+  test("no source + includeLegalPages true → counts as a source", async () => {
+    const infos: string[] = [];
+    await runSeoBootCheck({
+      sitemapEntries: () => [],
+      includeLegalPages: true,
+      hasManagedPages: false,
+      log: { info: (m) => infos.push(m) },
+    });
+    expect(infos).toHaveLength(1);
+  });
+
+  test("no source at all + NODE_ENV=production → throws", async () => {
+    const originalEnv = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "production";
+    try {
+      await expect(
+        runSeoBootCheck({
+          sitemapEntries: () => [],
+          includeLegalPages: false,
+          hasManagedPages: false,
+        }),
+      ).rejects.toThrow(/Boot-Validation failed/);
+    } finally {
+      if (originalEnv === undefined) delete process.env["NODE_ENV"];
+      else process.env["NODE_ENV"] = originalEnv;
+    }
+  });
+
+  test("no source at all + NODE_ENV!=production → log.warn, no throw", async () => {
+    const warns: string[] = [];
+    const originalEnv = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "development";
+    try {
+      await runSeoBootCheck({
+        sitemapEntries: () => [],
+        includeLegalPages: false,
+        hasManagedPages: false,
+        log: { warn: (m) => warns.push(m) },
+      });
+      expect(warns).toHaveLength(1);
+      expect(warns[0]).toContain("sitemap.xml/llms.txt will serve an empty document");
+    } finally {
+      if (originalEnv === undefined) delete process.env["NODE_ENV"];
+      else process.env["NODE_ENV"] = originalEnv;
+    }
+  });
+});

package/src/seo/__tests__/sitemap.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { buildSitemapXml } from "../sitemap";
+
+describe("buildSitemapXml", () => {
+  test("emits urlset with loc/lastmod/changefreq", () => {
+    const xml = buildSitemapXml([
+      { loc: "https://example.com/", lastmod: "2026-01-01", changefreq: "weekly" },
+    ]);
+    expect(xml).toContain('<?xml version="1.0" encoding="UTF-8"?>');
+    expect(xml).toContain("<loc>https://example.com/</loc>");
+    expect(xml).toContain("<lastmod>2026-01-01</lastmod>");
+    expect(xml).toContain("<changefreq>weekly</changefreq>");
+  });
+
+  test("emits hreflang alternates", () => {
+    const xml = buildSitemapXml([
+      {
+        loc: "https://example.com/",
+        alternates: [{ hreflang: "de", href: "https://example.com/de" }],
+      },
+    ]);
+    expect(xml).toContain(
+      '<xhtml:link rel="alternate" hreflang="de" href="https://example.com/de" />',
+    );
+  });
+
+  test("escapes XML-unsafe characters in loc", () => {
+    const xml = buildSitemapXml([{ loc: "https://example.com/?a=1&b=2" }]);
+    expect(xml).toContain("https://example.com/?a=1&amp;b=2");
+    expect(xml).not.toContain("&b=2<");
+  });
+
+  test("empty entries → valid empty urlset", () => {
+    const xml = buildSitemapXml([]);
+    expect(xml).toContain("<urlset");
+    expect(xml).not.toContain("<url>");
+  });
+});

package/src/seo/constants.ts

@@ -0,0 +1,60 @@
+import {
+  access,
+  type ConfigKeyDefinition,
+  createTenantConfig,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const SEO_FEATURE = "seo" as const;
+
+// Default mount paths — override per-app via SeoOptions.basePaths for
+// non-standard mounts (e.g. a reverse-proxy that already serves /robots.txt).
+export const SEO_DEFAULT_PATHS = {
+  sitemap: "/sitemap.xml",
+  llmsTxt: "/llms.txt",
+  robots: "/robots.txt",
+} as const;
+
+// Tenant-scoped, admin-writable metadata feeding the Organization JSON-LD
+// helper + llms.txt summary + OG default image. No `seo-site-url` key —
+// absolute URLs are derived from the request's own Host (mirrors managed-
+// pages' resolveApexTenant pattern), so a single seo mount works correctly
+// across multiple apex hosts without a static site-url config drifting.
+const TEXT_PATTERN = { regex: "^[\\s\\S]{0,500}$" } as const;
+const HTTPS_PATTERN = { regex: "^$|^https://[^\\s\"'<>]{1,2000}$" } as const;
+const SEO_WRITE = access.withSystem(access.admin);
+
+export const SEO_CONFIG_KEYS = {
+  seoOrganizationName: createTenantConfig("text", {
+    default: "",
+    pattern: TEXT_PATTERN,
+    write: SEO_WRITE,
+  }),
+  seoOrganizationLogoUrl: createTenantConfig("text", {
+    default: "",
+    pattern: HTTPS_PATTERN,
+    write: SEO_WRITE,
+  }),
+  seoTwitterSite: createTenantConfig("text", {
+    default: "",
+    pattern: TEXT_PATTERN,
+    write: SEO_WRITE,
+  }),
+  seoLlmsSummary: createTenantConfig("text", {
+    default: "",
+    pattern: TEXT_PATTERN,
+    write: SEO_WRITE,
+  }),
+  seoDefaultOgImage: createTenantConfig("text", {
+    default: "",
+    pattern: HTTPS_PATTERN,
+    write: SEO_WRITE,
+  }),
+} satisfies Record<string, ConfigKeyDefinition>;
+
+export const SEO_CONFIG_QN = {
+  organizationName: "seo:config:seo-organization-name",
+  organizationLogoUrl: "seo:config:seo-organization-logo-url",
+  twitterSite: "seo:config:seo-twitter-site",
+  llmsSummary: "seo:config:seo-llms-summary",
+  defaultOgImage: "seo:config:seo-default-og-image",
+} as const;