@cosmicdrift/kumiko-bundled-features 0.145.0 → 0.146.0

package/src/seo/feature.ts

@@ -0,0 +1,313 @@
+import { computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
+import {
+  defineFeature,
+  type FeatureDefinition,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { LEGAL_ROUTES } from "../legal-pages";
+import { cachedSecurePageResponse } from "../page-render";
+import { SEO_CONFIG_KEYS, SEO_DEFAULT_PATHS } from "./constants";
+import { seoConfigQuery } from "./handlers/seo-config.query";
+import { buildLlmsTxt } from "./llms-txt";
+import { buildRobotsTxt, type RobotsPolicy } from "./robots-txt";
+import { buildSitemapXml, type SitemapEntry } from "./sitemap";
+
+// 300s-shared-cache: sitemap/llms.txt change rarely (new page publish, not
+// per-request), longer than legal-pages/managed-pages' 60s content cache.
+const SEO_CACHE = { kind: "revalidate", maxAgeSeconds: 300 } as const;
+
+const MANAGED_PAGES_BY_TENANT_PUBLISHED_QN = "managed-pages:query:by-tenant-published";
+const SEO_CONFIG_QUERY_QN = "seo:query:config";
+
+// Minimal shape of the httpRoute handler's `{ app }` dep — just enough to
+// make an internal /api/query call. Not importing HttpRouteHandlerDeps
+// itself: it isn't part of the engine's public surface (only the
+// httpRoute-registration types are).
+type FetchApp = { readonly fetch: (req: Request) => Promise<Response> | Response };
+
+export type ManagedPagesDiscoveryOptions = {
+  /** Same per-host tenant resolver the app already passes to
+   *  createManagedPagesFeature — needed to X-Tenant-scope the anonymous
+   *  by-tenant-published query. */
+  readonly resolveApexTenant: (host: string) => Promise<string | null> | string | null;
+  /** Must match the basePath passed to createManagedPagesFeature. Default "/p". */
+  readonly basePath?: string;
+};
+
+export type SeoOptions = {
+  /** Primary page inventory for sitemap.xml/llms.txt. App-authored, trusted
+   *  (same trust boundary as ApexCta.href) — return fully-qualified absolute
+   *  URLs. Called once per request with the resolved request Host. */
+  readonly sitemapEntries: (
+    host: string,
+  ) => Promise<readonly SitemapEntry[]> | readonly SitemapEntry[];
+  /** Merge legal-pages' 4 fixed routes into sitemap.xml/llms.txt. Set true
+   *  only when the app ALSO mounts createLegalPagesFeature() — this does not
+   *  detect it automatically (no such feature-presence hook exists at the
+   *  httpRoute layer). Default false. */
+  readonly includeLegalPages?: boolean;
+  /** Merge managed-pages' published slugs (via its anonymous
+   *  by-tenant-published query) into sitemap.xml/llms.txt. Omit if the app
+   *  doesn't mount managed-pages, or already includes those URLs in
+   *  `sitemapEntries` itself. */
+  readonly managedPages?: ManagedPagesDiscoveryOptions;
+  /** Serves GET /robots.txt with per-host policy. Default: no route — the
+   *  static `public/robots.txt` dev-server already ships covers the common
+   *  case (no per-host logic needed). Only opt in for staging/preview hosts
+   *  that need a different (e.g. Disallow: /) policy at runtime. */
+  readonly robotsPolicy?: (host: string) => Promise<RobotsPolicy> | RobotsPolicy;
+  /** Override the 3 mount paths. Default: /sitemap.xml, /llms.txt, /robots.txt. */
+  readonly basePaths?: Partial<typeof SEO_DEFAULT_PATHS>;
+};
+
+type SeoConfigValues = {
+  readonly organizationName: string;
+  readonly organizationLogoUrl: string;
+  readonly twitterSite: string;
+  readonly llmsSummary: string;
+  readonly defaultOgImage: string;
+};
+
+const EMPTY_SEO_CONFIG: SeoConfigValues = {
+  organizationName: "",
+  organizationLogoUrl: "",
+  twitterSite: "",
+  llmsSummary: "",
+  defaultOgImage: "",
+};
+
+function queryRequest(origin: string, tenantId: string, type: string, payload: unknown): Request {
+  return new Request(`${origin}/api/query`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "X-Tenant": tenantId },
+    body: JSON.stringify({ type, payload }),
+  });
+}
+
+// Config is decoration, not a hard dependency — a failed/unreachable read
+// degrades to empty strings (same posture as managed-pages' readBrandingResponse).
+async function readSeoConfig(
+  app: FetchApp,
+  origin: string,
+  tenantId: string,
+): Promise<SeoConfigValues> {
+  try {
+    const res = await app.fetch(queryRequest(origin, tenantId, SEO_CONFIG_QUERY_QN, {}));
+    if (!res.ok) return EMPTY_SEO_CONFIG;
+    const body: { data?: Partial<SeoConfigValues> } = await res.json();
+    return { ...EMPTY_SEO_CONFIG, ...body.data };
+  } catch {
+    return EMPTY_SEO_CONFIG;
+  }
+}
+
+// Merges the app callback with the optional legal-pages/managed-pages
+// sources. legal-pages routes are static (no per-tenant data) — merged
+// directly from the public LEGAL_ROUTES constant. managed-pages entries need
+// a live query (per-tenant published slugs) — merged via app.fetch, same
+// cross-feature decoupling as legal-pages' own text-content calls; a
+// failed/unreachable read degrades to "no managed-pages entries" rather than
+// failing the whole route.
+async function gatherEntries(
+  opts: SeoOptions,
+  app: FetchApp,
+  origin: string,
+  host: string,
+): Promise<SitemapEntry[]> {
+  const entries: SitemapEntry[] = [...(await opts.sitemapEntries(host))];
+
+  if (opts.includeLegalPages) {
+    for (const route of LEGAL_ROUTES) {
+      entries.push({ loc: `${origin}${route.path}` });
+    }
+  }
+
+  if (opts.managedPages) {
+    const tenantId = await opts.managedPages.resolveApexTenant(host);
+    if (tenantId) {
+      try {
+        const res = await app.fetch(
+          queryRequest(origin, tenantId, MANAGED_PAGES_BY_TENANT_PUBLISHED_QN, {}),
+        );
+        if (res.ok) {
+          const body: {
+            data?: { pages?: readonly { slug: string; updatedAt: string }[] };
+          } = await res.json();
+          const basePath = opts.managedPages.basePath ?? "/p";
+          for (const page of body.data?.pages ?? []) {
+            entries.push({ loc: `${origin}${basePath}/${page.slug}`, lastmod: page.updatedAt });
+          }
+        }
+      } catch {
+        // managed-pages unreachable/not mounted — degrade to callback-only entries.
+      }
+    }
+  }
+
+  return entries;
+}
+
+function requestHost(c: { req: { header: (name: string) => string | undefined; url: string } }): {
+  origin: string;
+  host: string;
+} {
+  const url = new URL(c.req.url);
+  return { origin: url.origin, host: c.req.header("host") ?? url.host };
+}
+
+// seo — site-discovery routes (sitemap.xml/llms.txt/robots.txt) plus the
+// wrapInLayout OG/JSON-LD extension (page-render/layout.ts's `seo` opt) and
+// the organizationSchema/webPageSchema/faqPageSchema JSON-LD builders
+// (schema-builders.ts, imported directly by apps — not wired into this
+// feature's own routes). Complements the apex ApexHead/renderApexPage
+// renderer, which already ships full OG/JSON-LD/canonical head handling —
+// this feature only fills the site-discovery + CMS-page-head gaps.
+export function createSeoFeature(opts: SeoOptions): FeatureDefinition {
+  const paths = { ...SEO_DEFAULT_PATHS, ...opts.basePaths };
+
+  return defineFeature("seo", (r) => {
+    r.describe(
+      `Site-discovery + SEO/AEO/GEO surface for apex/content pages. Serves GET ${paths.sitemap} and GET ${paths.llmsTxt} (both anonymous, revalidate-cached), merging the app-supplied sitemapEntries() callback with legal-pages' fixed routes (includeLegalPages) and/or managed-pages' published slugs (managedPages.resolveApexTenant) when opted in. Serves GET ${paths.robots} only when robotsPolicy is supplied (default off — the static public/robots.txt already covers the common case). Tenant-scoped config keys (seo:config:seo-organization-{name,logo-url}, seo:config:seo-twitter-site, seo:config:seo-llms-summary, seo:config:seo-default-og-image) feed the Organization JSON-LD helper + llms.txt summary. Also exports pure schema.org JSON-LD builders (organizationSchema/webPageSchema/faqPageSchema) for apps to pass into ApexHead.schemaJson or wrapInLayout({ seo: { schemaJson } }) directly — this feature does not inject JSON-LD on its own routes.`,
+    );
+    r.uiHints({
+      displayLabel: "SEO / Site Discovery",
+      category: "content",
+      recommended: false,
+    });
+    // config keys need the config feature's write/read machinery to actually
+    // function (same hard dependency managed-pages has) — only legal-pages/
+    // managed-pages are genuinely optional (merged only when opted in).
+    r.requires("config");
+    r.optionalRequires("legal-pages", "managed-pages");
+
+    r.config({ keys: SEO_CONFIG_KEYS });
+    r.queryHandler(seoConfigQuery);
+
+    r.httpRoute({
+      method: "GET",
+      path: paths.sitemap,
+      anonymous: true,
+      handler: async (c, { app }) => {
+        const { origin, host } = requestHost(c);
+        const entries = await gatherEntries(opts, app, origin, host);
+        const xml = buildSitemapXml(entries);
+        const etag = computeRevisionEtag([host, xml]);
+        return cachedSecurePageResponse(c.req.raw, {
+          body: xml,
+          etag,
+          cache: SEO_CACHE,
+          extra: { "content-type": "application/xml; charset=utf-8" },
+        });
+      },
+    });
+
+    r.httpRoute({
+      method: "GET",
+      path: paths.llmsTxt,
+      anonymous: true,
+      handler: async (c, { app }) => {
+        const { origin, host } = requestHost(c);
+        const tenantId = opts.managedPages
+          ? ((await opts.managedPages.resolveApexTenant(host)) ?? SYSTEM_TENANT_ID)
+          : SYSTEM_TENANT_ID;
+        const [entries, seoConfig] = await Promise.all([
+          gatherEntries(opts, app, origin, host),
+          readSeoConfig(app, origin, tenantId),
+        ]);
+        const sections =
+          entries.length > 0
+            ? [{ heading: "Pages", links: entries.map((e) => ({ title: e.loc, url: e.loc })) }]
+            : [];
+        const text = buildLlmsTxt({
+          title: seoConfig.organizationName || host,
+          summary: seoConfig.llmsSummary,
+          sections,
+        });
+        const etag = computeRevisionEtag([host, text]);
+        return cachedSecurePageResponse(c.req.raw, {
+          body: text,
+          etag,
+          cache: SEO_CACHE,
+          extra: { "content-type": "text/plain; charset=utf-8" },
+        });
+      },
+    });
+
+    if (opts.robotsPolicy) {
+      const robotsPolicy = opts.robotsPolicy;
+      r.httpRoute({
+        method: "GET",
+        path: paths.robots,
+        anonymous: true,
+        handler: async (c) => {
+          const { host } = requestHost(c);
+          const policy = await robotsPolicy(host);
+          const text = buildRobotsTxt(policy);
+          const etag = computeRevisionEtag([host, text]);
+          return cachedSecurePageResponse(c.req.raw, {
+            body: text,
+            etag,
+            cache: SEO_CACHE,
+            extra: { "content-type": "text/plain; charset=utf-8" },
+          });
+        },
+      });
+    }
+
+    // Boot-Check body als named function extrahiert — direkt unit-testbar,
+    // gleiches "thin job-shell ruft testable function"-Pattern wie
+    // legal-pages' runLegalPagesBootCheck.
+    r.job(
+      "seo-boot-check",
+      { trigger: { manual: true }, runOnBoot: true, runIn: "api" },
+      async (_payload, ctx) =>
+        runSeoBootCheck({
+          sitemapEntries: opts.sitemapEntries,
+          includeLegalPages: opts.includeLegalPages ?? false,
+          hasManagedPages: opts.managedPages !== undefined,
+          log: ctx.log,
+        }),
+    );
+
+    return {};
+  });
+}
+
+export type SeoBootCheckCtx = {
+  readonly sitemapEntries: (
+    host: string,
+  ) => Promise<readonly SitemapEntry[]> | readonly SitemapEntry[];
+  readonly includeLegalPages: boolean;
+  /** managedPages entries are only resolvable per-request (need a live
+   *  tenant + query) — the boot-check can't probe them, so their mere
+   *  presence counts as "has a source" rather than sampling actual rows. */
+  readonly hasManagedPages: boolean;
+  readonly log?: {
+    readonly info?: (msg: string) => void;
+    readonly warn?: (msg: string) => void;
+  };
+};
+
+// Exported for direct tests. Throws in NODE_ENV=production when NONE of the
+// three entry sources (sitemapEntries() probe, includeLegalPages,
+// managedPages) can supply anything — the routes would otherwise serve a
+// permanently empty document. Otherwise log.warn. Logs log.info when at
+// least one source is present.
+export async function runSeoBootCheck(ctx: SeoBootCheckCtx): Promise<void> {
+  const sample = await ctx.sitemapEntries("boot-check.invalid");
+  const hasSource = sample.length > 0 || ctx.includeLegalPages || ctx.hasManagedPages;
+
+  if (hasSource) {
+    ctx.log?.info?.("seo boot-check: sitemap/llms.txt have at least one entry source");
+  } else {
+    const message =
+      "seo: sitemapEntries() returned no entries and neither includeLegalPages " +
+      "nor managedPages is set — sitemap.xml/llms.txt will serve an empty " +
+      "document. Wire real entries, set includeLegalPages:true, or pass managedPages.";
+
+    if (process.env["NODE_ENV"] === "production") {
+      throw new Error(`Boot-Validation failed: ${message}`);
+    }
+    ctx.log?.warn?.(message);
+  }
+}

package/src/seo/handlers/seo-config.query.ts

@@ -0,0 +1,35 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { SEO_CONFIG_QN } from "../constants";
+
+// Public read of the seo feature's own tenant-config values, for the
+// anonymous sitemap.xml/llms.txt routes (a Response is per-request; those
+// routes only get `{ app }`, not `ctx.config` directly, so they reach this
+// the same way managed-pages' render route reaches its branding query — an
+// internal app.fetch with X-Tenant set to the resolved tenant).
+//
+// config:query:values (the generic config feature query) is NOT usable here:
+// it requires an authenticated caller (any role) even though its per-key
+// access defaults to read:all — a genuinely anonymous visitor gets 403 before
+// per-key filtering ever runs. This mirrors managed-pages' branding query
+// instead (`access: { roles: ["anonymous", ...] }`), the pattern actually
+// proven to work for anonymous-served pages.
+export const seoConfigQuery = defineQueryHandler({
+  name: "config",
+  schema: z.object({}),
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  handler: async (_query, ctx) => {
+    const read = async (qualifiedKey: string): Promise<string> => {
+      if (!ctx.config) return "";
+      const value = await ctx.config(qualifiedKey);
+      return typeof value === "string" ? value : "";
+    };
+    return {
+      organizationName: await read(SEO_CONFIG_QN.organizationName),
+      organizationLogoUrl: await read(SEO_CONFIG_QN.organizationLogoUrl),
+      twitterSite: await read(SEO_CONFIG_QN.twitterSite),
+      llmsSummary: await read(SEO_CONFIG_QN.llmsSummary),
+      defaultOgImage: await read(SEO_CONFIG_QN.defaultOgImage),
+    };
+  },
+});

package/src/seo/index.ts

@@ -0,0 +1,19 @@
+export { SEO_CONFIG_KEYS, SEO_CONFIG_QN, SEO_DEFAULT_PATHS, SEO_FEATURE } from "./constants";
+export {
+  createSeoFeature,
+  type ManagedPagesDiscoveryOptions,
+  runSeoBootCheck,
+  type SeoBootCheckCtx,
+  type SeoOptions,
+} from "./feature";
+export { buildLlmsTxt, type LlmsTxtInput, type LlmsTxtLink, type LlmsTxtSection } from "./llms-txt";
+export { buildRobotsTxt, type RobotsPolicy } from "./robots-txt";
+export {
+  type FaqItem,
+  faqPageSchema,
+  type OrganizationSchemaInput,
+  organizationSchema,
+  type WebPageSchemaInput,
+  webPageSchema,
+} from "./schema-builders";
+export { buildSitemapXml, type SitemapEntry } from "./sitemap";

package/src/seo/llms-txt.ts

@@ -0,0 +1,33 @@
+export type LlmsTxtLink = {
+  readonly title: string;
+  readonly url: string;
+  readonly desc?: string;
+};
+
+export type LlmsTxtSection = {
+  readonly heading: string;
+  readonly links: readonly LlmsTxtLink[];
+};
+
+export type LlmsTxtInput = {
+  readonly title: string;
+  readonly summary: string;
+  readonly sections?: readonly LlmsTxtSection[];
+};
+
+// Plain-text builder for the community llms.txt convention (H1 title,
+// blockquote summary, `## `-headed link lists). No HTML escaping needed —
+// Markdown link syntax, plain-text output.
+export function buildLlmsTxt(input: LlmsTxtInput): string {
+  const sections = (input.sections ?? [])
+    .filter((s) => s.links.length > 0)
+    .map((s) => {
+      const links = s.links
+        .map((l) => `- [${l.title}](${l.url})${l.desc ? `: ${l.desc}` : ""}`)
+        .join("\n");
+      return `## ${s.heading}\n\n${links}`;
+    })
+    .join("\n\n");
+  const summary = input.summary ? `\n\n> ${input.summary}` : "";
+  return `# ${input.title}${summary}${sections ? `\n\n${sections}` : ""}\n`;
+}

package/src/seo/robots-txt.ts

@@ -0,0 +1,13 @@
+export type RobotsPolicy = {
+  readonly allow: boolean;
+  readonly sitemapUrl?: string;
+};
+
+// Only used when an app opts into GET /robots.txt (SeoOptions.robotsPolicy) —
+// the common case (no per-host logic) is already covered by dev-server's
+// static public/robots.txt passthrough.
+export function buildRobotsTxt(policy: RobotsPolicy): string {
+  const rule = policy.allow ? "Disallow:" : "Disallow: /";
+  const sitemap = policy.sitemapUrl ? `\nSitemap: ${policy.sitemapUrl}` : "";
+  return `User-agent: *\n${rule}${sitemap}\n`;
+}

package/src/seo/schema-builders.ts

@@ -0,0 +1,57 @@
+// Pure schema.org JSON-LD builders — plain data, no HTML/escaping (the
+// serialization boundary is `renderApexHeadTags`'s `scriptSafeJsonHtml`,
+// which already escapes `<` so a value can't break out of the
+// `<script type="application/ld+json">` block). Feed the result into
+// `ApexHead.schemaJson` (renderApexPage) or `wrapInLayout({ seo: { schemaJson
+// } })` (CMS pages) — this feature does not inject JSON-LD on its own routes.
+
+export type OrganizationSchemaInput = {
+  readonly name: string;
+  readonly url?: string;
+  readonly logoUrl?: string;
+  readonly sameAs?: readonly string[];
+};
+
+export function organizationSchema(input: OrganizationSchemaInput): Record<string, unknown> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: input.name,
+    ...(input.url ? { url: input.url } : {}),
+    ...(input.logoUrl ? { logo: input.logoUrl } : {}),
+    ...(input.sameAs && input.sameAs.length > 0 ? { sameAs: input.sameAs } : {}),
+  };
+}
+
+export type WebPageSchemaInput = {
+  readonly name: string;
+  readonly url: string;
+  readonly description?: string;
+};
+
+export function webPageSchema(input: WebPageSchemaInput): Record<string, unknown> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebPage",
+    name: input.name,
+    url: input.url,
+    ...(input.description ? { description: input.description } : {}),
+  };
+}
+
+export type FaqItem = { readonly question: string; readonly answer: string };
+
+// Feeds Google's FAQ rich-result + is the most directly LLM-answer-engine-
+// legible JSON-LD shape (question/answer pairs) — the "AEO/GEO" half of the
+// schema-builder set, same emission path as organizationSchema/webPageSchema.
+export function faqPageSchema(items: readonly FaqItem[]): Record<string, unknown> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: items.map((item) => ({
+      "@type": "Question",
+      name: item.question,
+      acceptedAnswer: { "@type": "Answer", text: item.answer },
+    })),
+  };
+}

package/src/seo/sitemap.ts

@@ -0,0 +1,30 @@
+import { escapeXml } from "@cosmicdrift/kumiko-headless";
+
+export type SitemapEntry = {
+  readonly loc: string;
+  /** ISO-8601 date/datetime. */
+  readonly lastmod?: string;
+  readonly changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+  /** hreflang alternates for the same logical page (multilingual sitemaps). */
+  readonly alternates?: readonly { readonly hreflang: string; readonly href: string }[];
+};
+
+// Pure XML builder — sitemaps.org urlset + xhtml:link alternates. No
+// dedup/sort: callers control ordering, entries are trusted app/feature data
+// (see feature.ts's trust boundary — same posture as ApexCta.href).
+export function buildSitemapXml(entries: readonly SitemapEntry[]): string {
+  const urls = entries
+    .map((e) => {
+      const lastmod = e.lastmod ? `\n    <lastmod>${escapeXml(e.lastmod)}</lastmod>` : "";
+      const changefreq = e.changefreq ? `\n    <changefreq>${e.changefreq}</changefreq>` : "";
+      const alternates = (e.alternates ?? [])
+        .map(
+          (a) =>
+            `\n    <xhtml:link rel="alternate" hreflang="${escapeXml(a.hreflang)}" href="${escapeXml(a.href)}" />`,
+        )
+        .join("");
+      return `  <url>\n    <loc>${escapeXml(e.loc)}</loc>${lastmod}${changefreq}${alternates}\n  </url>`;
+    })
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">\n${urls}\n</urlset>\n`;
+}