@warpgogol/werkstatt-shared 0.2.0

package/src/share/semantic/organization-profile.ts

@@ -0,0 +1,160 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0148: the single, framework-agnostic organization-profile assembler. The mapping from business-schema fields to SemanticOrganization lives here once; the disk llms path and the Astro JSON-LD path both resolve their own data (each reads + substitutes content references in its own way) and delegate the assembly here. Replaces the two duplicated org builders (no legacy).</purpose>
+<non-goals>
+  <item>Do not read files or substitute content references — callers pass resolved values.</item>
+  <item>Do not iterate pages — this builds the site-wide profile only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0148: extracted the shared org-profile assembler from the disk + Astro builders.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { getBaseUrl, toAbsoluteUrl } from "./ids.ts";
+import type {
+  SemanticInitiative,
+  SemanticLocation,
+  SemanticOffer,
+  SemanticOrganization,
+  SemanticPerson,
+  SemanticService,
+} from "./models.ts";
+
+export type SemanticSiteProfile = {
+  organization: SemanticOrganization;
+  people: SemanticPerson[];
+  initiatives: SemanticInitiative[];
+};
+
+/** Resolved owner address primitives (content references already substituted). */
+export interface ProfileAddressInput {
+  street?: string;
+  streetNumber?: string;
+  zip?: string;
+  city?: string;
+  country?: string;
+}
+
+/** Resolved bank primitives (accountHolder already substituted). */
+export interface ProfileBankInput {
+  accountHolder?: string;
+  iban?: string;
+  bic?: string;
+  bankName?: string;
+  konto?: string;
+  blz?: string;
+}
+
+/**
+ * Normalized, fully-resolved business primitives. Each caller (disk fs reader,
+ * Astro content-layer reader) maps its source into this shape — including any
+ * RFC-0045 content-reference substitution — so the assembly below is identical
+ * regardless of source.
+ */
+export interface OrganizationProfileInput {
+  lang: string;
+  siteUrl: URL | string;
+  /** Resolved brand name. */
+  brandName: string;
+  description: string;
+  foundingYear?: string;
+  areaServed?: string[];
+  founders: SemanticPerson[];
+  boardMembers: SemanticPerson[];
+  legalName?: string;
+  registration?: string;
+  representativeName?: string;
+  address?: ProfileAddressInput;
+  /** Present when a bank block exists (drives donationAccount emission). */
+  bank?: ProfileBankInput;
+  email?: string;
+  contactType?: string;
+  offer?: SemanticOffer;
+  location?: SemanticLocation;
+  team?: SemanticPerson[];
+  /* RFC-0163: social/profile URLs → Organization.sameAs. */
+  sameAs?: string[];
+  /* RFC-0163: absolute logo URL → Organization.logo. */
+  logoUrl?: string;
+  /** RFC-0373: projected business service catalog. */
+  services?: SemanticService[];
+  /** RFC-0242: explicit schema.org @type override (e.g. Bodenstation → Organization/ProfessionalService). */
+  schemaType?: string[];
+}
+
+/** RFC-0148: assemble the site profile from resolved business primitives. */
+export function buildOrganizationProfile(input: OrganizationProfileInput): SemanticSiteProfile {
+  const baseUrl = getBaseUrl(input.siteUrl);
+  // Use the full team when available (includes founders, board, team, patron, etc.),
+  // otherwise fall back to founders + boardMembers. Deduplicate by name.
+  const rawPeople = input.team?.length
+    ? [...input.team]
+    : [...input.founders, ...input.boardMembers];
+  const seen = new Set<string>();
+  const people: SemanticPerson[] = [];
+  for (const p of rawPeople) {
+    if (!seen.has(p.name)) {
+      seen.add(p.name);
+      people.push(p);
+    }
+  }
+
+  const organization: SemanticOrganization = {
+    name: input.brandName,
+    legalName: input.legalName,
+    description: input.description,
+    url: toAbsoluteUrl(baseUrl, `/${input.lang}/`),
+    foundingYear: input.foundingYear,
+    email: input.email,
+    registration: input.registration,
+    representative: input.representativeName,
+    ...(input.address
+      ? {
+          address: {
+            streetAddress: `${input.address.street} ${input.address.streetNumber}`,
+            postalCode: input.address.zip,
+            addressLocality: input.address.city,
+            addressCountry: input.address.country,
+          },
+        }
+      : {}),
+    ...(input.areaServed?.length ? { areaServed: input.areaServed } : {}),
+    ...(input.founders.length ? { founders: input.founders } : {}),
+    ...(input.boardMembers.length ? { boardMembers: input.boardMembers } : {}),
+    ...(input.contactType || input.email
+      ? {
+          contactPoints: [
+            {
+              contactType: input.contactType ?? "",
+              email: input.email,
+            },
+          ],
+        }
+      : {}),
+    ...(input.bank
+      ? {
+          donationAccount: {
+            accountHolder: input.bank.accountHolder ?? "",
+            iban: input.bank.iban,
+            bic: input.bank.bic,
+            bankName: input.bank.bankName,
+            accountNumber: input.bank.konto,
+            bankCode: input.bank.blz,
+          },
+        }
+      : {}),
+    ...(input.offer ? { offer: input.offer } : {}),
+    ...(input.location ? { location: input.location } : {}),
+    ...(input.team?.length ? { team: input.team } : {}),
+    // RFC-0163: entity-grounding signals. `image` always points at the guaranteed
+    // /og-image.png fallback (a real, present asset); sameAs/logo emit only when authored.
+    image: toAbsoluteUrl(baseUrl, "/og-image.png"),
+    ...(input.sameAs?.length ? { sameAs: input.sameAs } : {}),
+    ...(input.logoUrl ? { logo: input.logoUrl } : {}),
+    ...(input.schemaType?.length ? { schemaType: input.schemaType } : {}),
+    ...(input.services?.length ? { services: input.services } : {}),
+  };
+
+  return { organization, people, initiatives: [] };
+}

package/src/share/semantic/output-projection.ts

@@ -0,0 +1,131 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0143: pure resolution of the per-page `output` projection container. Single resolution point shared by every per-page output generator (sitemap, llms) so the static disk loader, the Astro runtime path, and the sitemap command cannot drift.</purpose>
+<non-goals>
+  <item>Do not read files — pure function only.</item>
+  <item>Do not own site-wide policy blocks (ai:, robots:) — those are separate top-level surfaces.</item>
+  <item>Do not own per-generator value semantics beyond defaulting (llms depth lives in llms-policy.ts).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0143: Initial implementation. Folds legacy sitemapExclude + per-page sitemap block into output.sitemap.</item>
+  <item>RFC-0328: Apply legal-page default sitemap category when semanticType is "legal".</item>
+  <item>RFC-0143 cleanup: Removed deprecated sitemapExclude and top-level sitemap alias handling.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  PageOutputProjection,
+  RobotsProjection,
+  SemanticImage,
+  SitemapProjection,
+} from "./models.ts";
+import { resolveLlmsPolicy, type RawLlmsPolicy } from "./llms-policy.ts";
+
+/** Raw `output.image` as authored in system.md. RFC-0165/0167. */
+export type RawImageProjection = {
+  url: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+};
+
+/**
+ * Resolve the author-declared per-page content image. Returns a SemanticImage
+ * tagged `contentImage: true` (eligible for the image sitemap), or undefined
+ * when no image is declared or the url is empty.
+ */
+function resolveImage(raw: RawImageProjection | undefined): SemanticImage | undefined {
+  if (!raw || typeof raw.url !== "string" || raw.url.trim() === "") return undefined;
+  return {
+    url: raw.url,
+    ...(raw.alt !== undefined ? { alt: raw.alt } : {}),
+    ...(raw.width !== undefined ? { width: raw.width } : {}),
+    ...(raw.height !== undefined ? { height: raw.height } : {}),
+    contentImage: true,
+  };
+}
+
+/** Raw `output.robots` as authored in system.md. RFC-0165. */
+export type RawRobotsProjection =
+  | boolean
+  | {
+      index?: boolean;
+      follow?: boolean;
+    };
+
+function resolveRobots(raw: RawRobotsProjection | undefined): RobotsProjection {
+  if (typeof raw === "boolean") {
+    // `output.robots: false` is shorthand for noindex,nofollow.
+    return { index: raw, follow: raw };
+  }
+  const obj = raw ?? {};
+  return { index: obj.index ?? true, follow: obj.follow ?? true };
+}
+
+/** Raw `output.sitemap` as authored in system.md (boolean shorthand or object). */
+export type RawSitemapProjection =
+  | boolean
+  | {
+      include?: boolean;
+      category?: string;
+      lastmod?: string;
+      includeLastmod?: boolean;
+    };
+
+/** Raw `output` block as authored in system.md. Closed: only known generator keys. */
+export type RawPageOutput = {
+  sitemap?: RawSitemapProjection;
+  llms?: RawLlmsPolicy;
+  /** RFC-0165: per-page indexability. */
+  robots?: RawRobotsProjection;
+  /** RFC-0165/0167: author-declared content illustration (absolute https url). */
+  image?: RawImageProjection;
+};
+
+export interface ResolvePageOutputOptions {
+  semanticType?: string;
+}
+
+const DEFAULT_SITEMAP_CATEGORY = "content";
+
+function resolveSitemap(
+  raw: RawSitemapProjection | undefined,
+  defaultCategory: string = DEFAULT_SITEMAP_CATEGORY,
+): SitemapProjection {
+  // Boolean shorthand: `output.sitemap: false`
+  if (typeof raw === "boolean") {
+    return {
+      include: raw,
+      category: defaultCategory,
+      lastmod: undefined,
+      includeLastmod: true,
+    };
+  }
+
+  const obj = raw ?? {};
+  return {
+    include: obj.include ?? true,
+    category: obj.category ?? defaultCategory,
+    lastmod: obj.lastmod,
+    includeLastmod: obj.includeLastmod ?? true,
+  };
+}
+
+/**
+ * RFC-0143: resolve every per-page projection from the raw `output` block.
+ * The single resolution point for all per-page output generators.
+ */
+export function resolvePageOutput(
+  raw: RawPageOutput | undefined,
+  options: ResolvePageOutputOptions = {},
+): PageOutputProjection {
+  const output = raw ?? {};
+  const defaultCategory = options.semanticType === "legal" ? "legal" : DEFAULT_SITEMAP_CATEGORY;
+  return {
+    sitemap: resolveSitemap(output.sitemap, defaultCategory),
+    llms: resolveLlmsPolicy(output.llms, options.semanticType ?? ""),
+    robots: resolveRobots(output.robots),
+    ...(resolveImage(output.image) ? { image: resolveImage(output.image) } : {}),
+  };
+}

package/src/share/semantic/page-builders/markdown-page.ts

@@ -0,0 +1,84 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Generic semantic builder for markdown-based pages (impressum, datenschutz, agb, widerruf, open-source, etc.). Replaces 7 copy-paste page builders.</purpose>
+<non-goals>
+  <item>Do not handle home page or other specialized page types.</item>
+  <item>Do not contain app-specific extractor logic.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Consolidated 7 copy-paste page builders (impressum, datenschutz, agb, widerruf, open-source, projekte, wir-ueber-uns) into one generic function.</item>
+  <item>Introduced app-agnostic markdown-page semantic builder and breadcrumb normalization.</item>
+  <item>Unified blocksToMarkdown signature — eliminated duplication.</item>
+  <item>RFC-0372: MarkdownPageInput now accepts blocks: SemanticBlock[] directly; removed bodyText/contentBlocks/answerBlocks from input and output.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { getBaseUrl, toAbsoluteUrl, toCanonicalUrl } from "../ids.ts";
+import type {
+  SemanticBlock,
+  SemanticBreadcrumb,
+  SemanticPageModel,
+  SemanticPageType,
+} from "../models.ts";
+
+export interface MarkdownPageInput {
+  type: SemanticPageType;
+  lang: string;
+  url: URL | string;
+  title: string;
+  description: string;
+  /** RFC-0377: optional audience override for the page. */
+  audience?: string;
+  heading: string;
+  lead?: string;
+  /** RFC-0372: unified block array — replaces bodyText/contentBlocks/answerBlocks. */
+  blocks: SemanticBlock[];
+  breadcrumbsContent?: { homeLabel: string };
+  /**
+   * RFC-0229: the canonical breadcrumb trail (Home → live ancestors → self), supplied by the
+   * render pipeline so the JSON-LD BreadcrumbList matches the visible section exactly. When omitted
+   * the builder falls back to a flat Home → self trail (used by source paths with no ancestor
+   * resolver, e.g. the disk-side llms model).
+   */
+  breadcrumbs?: SemanticBreadcrumb[];
+  people?: Array<{ name: string; role?: string; description?: string; isDeceased?: boolean }>;
+  initiatives?: Array<{ id: string; name: string; summary: string; facts?: string[] }>;
+  faqEntries?: Array<{
+    id: string;
+    question: string;
+    answer: string;
+    tags?: string[];
+    serviceSlug?: string;
+  }>;
+}
+
+export function buildMarkdownPageSemantic(input: MarkdownPageInput): SemanticPageModel {
+  return {
+    type: input.type,
+    lang: input.lang,
+    url: toCanonicalUrl(input.url),
+    title: input.title,
+    description: input.description,
+    ...(input.audience ? { audience: input.audience } : {}),
+    heading: input.heading,
+    lead: input.lead,
+    // RFC-0229: prefer the canonical trail from the render pipeline; otherwise build the flat
+    // Home → self fallback (preserves behavior for source paths with no ancestor resolver).
+    breadcrumbs:
+      input.breadcrumbs && input.breadcrumbs.length > 0
+        ? input.breadcrumbs
+        : [
+            {
+              name: input.breadcrumbsContent?.homeLabel ?? "Home",
+              url: toAbsoluteUrl(getBaseUrl(input.url), `/${input.lang}/`),
+            },
+            { name: input.heading, url: toCanonicalUrl(input.url) },
+          ],
+    blocks: input.blocks,
+    organization: {} as SemanticPageModel["organization"],
+    people: input.people,
+    initiatives: input.initiatives,
+    faqEntries: input.faqEntries?.length ? input.faqEntries : undefined,
+  };
+}

package/src/share/semantic/page-markdown.ts

@@ -0,0 +1,234 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0377: pure per-page Markdown projector. Turns a SemanticPageModel into a clean,
+agent-structured Markdown document with a predictable section hierarchy (Summary, Business context,
+Data / APIs, User flows, Constraints) plus optional People, Initiatives, and FAQ. Framework-agnostic
+— no DOM, no fetch, no HTML scraping.</purpose>
+<non-goals>
+  <item>Do not convert HTML — content is already structured. HTML→Markdown (CMS richText) lives
+        in the content-source adapter, never here.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0166: initial implementation — build-time per-page Markdown twin.</item>
+  <item>RFC-0372: buildPageMarkdown now renders from unified page.blocks instead of answerBlocks + contentBlocks.</item>
+  <item>RFC-0377: restructured body into standardized sections (Summary, Business context, Data / APIs, User flows, Constraints) with heuristic block classification.</item>
+</CHANGE_SUMMARY>
+*/
+
+import {
+  canonicalizeGeneratedMarkdownText,
+  formatGeneratedMarkdownListItem,
+} from "./markdown-hygiene.ts";
+import type { SemanticBlock, SemanticPageModel } from "./models.ts";
+
+type SectionKind = "summary" | "business-context" | "data-apis" | "user-flows" | "constraints";
+
+function clean(page: SemanticPageModel, text: string | undefined): string {
+  const baseUrl = (() => {
+    try {
+      return new URL(page.url).origin;
+    } catch {
+      return undefined;
+    }
+  })();
+  return canonicalizeGeneratedMarkdownText(text, {
+    baseUrl,
+    defaultLanguage: page.defaultLanguage,
+  });
+}
+
+function blockHasContent(block: SemanticBlock): boolean {
+  return Boolean(
+    block.heading || block.summary || block.body || block.facts?.length || block.items?.length,
+  );
+}
+
+function classifyBlock(block: SemanticBlock): Exclude<SectionKind, "summary"> {
+  const heading = block.heading.toLowerCase();
+  const blockType = (block.blockType ?? "").toLowerCase();
+
+  const constraintTokens = [
+    "legal",
+    "recht",
+    "datenschutz",
+    "privacy",
+    "impressum",
+    "terms",
+    "conditions",
+    "constraints",
+    "pflicht",
+    "liability",
+    "haftung",
+  ];
+  if (constraintTokens.some((token) => heading.includes(token) || blockType.includes(token))) {
+    return "constraints";
+  }
+
+  const flowTokens = [
+    "flow",
+    "how it works",
+    "so funktioniert",
+    "steps",
+    "schritte",
+    "process",
+    "ablauf",
+    "cta",
+    "call-to-action",
+  ];
+  if (
+    flowTokens.some((token) => heading.includes(token) || blockType.includes(token)) ||
+    blockType.includes("hero-decision-card")
+  ) {
+    return "user-flows";
+  }
+
+  if (block.facts?.length || block.items?.length) {
+    return "data-apis";
+  }
+
+  return "business-context";
+}
+
+function extractSummaryText(page: SemanticPageModel): string | undefined {
+  if (page.lead) return page.lead;
+  if (page.description) return page.description;
+  for (const block of page.blocks) {
+    if (block.summary) return block.summary;
+    if (block.body) return block.body;
+  }
+  return undefined;
+}
+
+function renderBlock(page: SemanticPageModel, block: SemanticBlock, depth = 3): string[] {
+  const lines: string[] = [];
+  const prefix = "#".repeat(depth);
+
+  if (block.heading) {
+    lines.push(`${prefix} ${block.heading}`);
+  }
+  if (block.summary) {
+    lines.push("");
+    lines.push(clean(page, block.summary));
+  }
+  if (block.body) {
+    lines.push("");
+    lines.push(clean(page, block.body));
+  }
+  if (block.facts?.length) {
+    lines.push("");
+    for (const fact of block.facts) {
+      lines.push(...formatGeneratedMarkdownListItem(clean(page, fact)));
+    }
+  }
+  if (block.items?.length) {
+    lines.push("");
+    for (const item of block.items) {
+      lines.push(`${"#".repeat(depth + 1)} ${item.title}`);
+      if (item.description) {
+        lines.push("");
+        lines.push(clean(page, item.description));
+      }
+      lines.push("");
+    }
+  }
+
+  return lines;
+}
+
+function renderSection(
+  page: SemanticPageModel,
+  heading: string,
+  blocks: SemanticBlock[],
+): string[] {
+  const lines: string[] = ["", `## ${heading}`, ""];
+  for (const block of blocks) {
+    lines.push(...renderBlock(page, block));
+  }
+  return lines;
+}
+
+export function buildPageMarkdown(page: SemanticPageModel): string {
+  const lines: string[] = [];
+
+  lines.push(`# ${page.title}`);
+  lines.push("");
+
+  // RFC-0377: Summary section is required. Fallback chain: lead → description → first block summary → first block body.
+  const summaryText = extractSummaryText(page);
+  if (summaryText) {
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(clean(page, summaryText));
+  }
+
+  // RFC-0320: the old relative `Source: /path` footer is retired.
+  // Provenance now lives in YAML frontmatter added by the generator.
+
+  // RFC-0377: classify blocks into standardized sections.
+  const businessContext: SemanticBlock[] = [];
+  const dataApis: SemanticBlock[] = [];
+  const userFlows: SemanticBlock[] = [];
+  const constraints: SemanticBlock[] = [];
+
+  for (const block of page.blocks) {
+    if (!blockHasContent(block)) continue;
+    const section = classifyBlock(block);
+    if (section === "business-context") businessContext.push(block);
+    if (section === "data-apis") dataApis.push(block);
+    if (section === "user-flows") userFlows.push(block);
+    if (section === "constraints") constraints.push(block);
+  }
+
+  lines.push(...renderSection(page, "Business context", businessContext));
+  lines.push(...renderSection(page, "Data / APIs", dataApis));
+  lines.push(...renderSection(page, "User flows", userFlows));
+  lines.push(...renderSection(page, "Constraints", constraints));
+
+  if (page.people?.length) {
+    lines.push("");
+    lines.push("## People");
+    for (const person of page.people) {
+      lines.push("");
+      lines.push(`### ${person.name}`);
+      if (person.role) {
+        lines.push(`**${person.role}**`);
+      }
+      if (person.affiliations?.length) {
+        lines.push(`*${person.affiliations.join(", ")}*`);
+      }
+      if (person.description) {
+        lines.push("");
+        lines.push(clean(page, person.description));
+      }
+    }
+    lines.push("");
+  }
+
+  if (page.initiatives?.length) {
+    lines.push("");
+    lines.push("## Initiatives");
+    for (const initiative of page.initiatives) {
+      const facts = initiative.facts?.length ? ` (${initiative.facts.join("; ")})` : "";
+      lines.push(`- ${initiative.name}: ${initiative.summary}${facts}`);
+    }
+    lines.push("");
+  }
+
+  if (page.faqEntries?.length) {
+    lines.push("");
+    lines.push("## FAQ");
+    for (const entry of page.faqEntries) {
+      lines.push("");
+      lines.push(`### ${entry.question}`);
+      lines.push("");
+      lines.push(clean(page, entry.answer));
+    }
+    lines.push("");
+  }
+
+  return `${lines
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim()}\n`;
+}