@warpgogol/werkstatt-shared 0.2.0

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

@@ -0,0 +1,125 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared utilities for semantic page builders: slug generation, markdown answer block extraction, and conversion helpers.</purpose>
+<non-goals>
+  <item>Do not contain page-specific logic or component content loading.</item>
+  <item>Do not interact with astro:content — use astro/semantic-page.ts for that.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Extracted from app semantic pages _shared — framework-agnostic utilities moved to packages/share.</item>
+  <item>Unified single blocksToMarkdown signature (was duplicated with different signatures in app).</item>
+  <item>Added slugify export and markdown answer-block extraction utilities.</item>
+  <item>RFC-0372: toSemanticAnswerBlocks now returns SemanticBlock[] with blockType: "prose".</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { SemanticBlock } from "./models.ts";
+import { slugify } from "./extract.ts";
+
+export { slugify };
+
+/**
+ * Creates a URL-friendly slug from a string.
+ * Re-exports from extract.ts to keep page-utils self-contained for consumers.
+ */
+
+/**
+ * Extracts structured answer blocks from markdown body text.
+ * Looks for h2 headings (## ...) and captures content until the next h2 or end of document.
+ */
+export function extractAnswerBlocksFromMarkdown(
+  bodyText: string,
+): Array<{ heading: string; content: string }> {
+  const blocks: Array<{ heading: string; content: string }> = [];
+  const lines = bodyText.split("\n");
+  let currentHeading = "";
+  let currentContent: string[] = [];
+
+  for (const line of lines) {
+    const h2Match = line.match(/^##\s+(.+)$/);
+    if (h2Match) {
+      if (currentHeading && currentContent.length > 0) {
+        blocks.push({
+          heading: currentHeading,
+          content: currentContent.join("\n").trim(),
+        });
+      }
+      currentHeading = h2Match[1];
+      currentContent = [];
+    } else if (currentHeading) {
+      currentContent.push(line);
+    }
+  }
+
+  if (currentHeading && currentContent.length > 0) {
+    blocks.push({
+      heading: currentHeading,
+      content: currentContent.join("\n").trim(),
+    });
+  }
+
+  return blocks;
+}
+
+/**
+ * Converts structured answer blocks back to markdown format.
+ */
+export function blocksToMarkdown(blocks: Array<{ heading: string; content: string }>): string {
+  return blocks
+    .map((block) => `## ${block.heading}\n\n${block.content}`)
+    .join("\n\n")
+    .trim();
+}
+
+/**
+ * Generates a page entry ID from a URL path.
+ * Removes language prefix and .html extension, then converts to kebab-case.
+ */
+export function toPageEntryId(url: URL): string {
+  const pathname = url.pathname;
+  const withoutLang = pathname.replace(/^\/[a-z]{2}\//, "/");
+  const clean = withoutLang.replace(/^\//, "").replace(/\.html$/, "");
+  return clean.replace(/\//g, "-") || "index";
+}
+
+/**
+ * RFC-0372: Transforms markdown answer blocks to SemanticBlock[] with blockType: "prose".
+ * Adds id, summary, and facts fields according to SemanticBlock type.
+ */
+export function toSemanticAnswerBlocks(
+  blocks: Array<{ heading: string; content: string }>,
+): SemanticBlock[] {
+  return blocks.map((block) => {
+    // A GFM table or a section with more than one paragraph carries structure that a flat
+    // one-line-per-fact split would destroy (table rows becoming stray bullets, an unrelated
+    // closing paragraph merging into the fact list). Preserve that content verbatim as the
+    // block summary instead of fragmenting it.
+    const hasTable = /^\s*\|/m.test(block.content);
+    const hasMultipleParagraphs = /\n[ \t]*\n/.test(block.content.trim());
+    if (hasTable || hasMultipleParagraphs) {
+      return {
+        id: slugify(block.heading),
+        blockType: "prose",
+        heading: block.heading,
+        summary: block.content.trim(),
+        facts: undefined,
+      };
+    }
+
+    const lines = block.content.split("\n").filter((line) => line.trim());
+    const firstLine = lines[0] || "";
+    const remainingLines = lines.slice(1);
+
+    const isSummary =
+      !firstLine.startsWith("-") && !firstLine.startsWith("*") && !firstLine.startsWith("#");
+
+    return {
+      id: slugify(block.heading),
+      blockType: "prose",
+      heading: block.heading,
+      summary: isSummary ? firstLine : undefined,
+      facts: isSummary ? remainingLines : lines,
+    };
+  });
+}

package/src/share/semantic/price-marker-resolver.ts

@@ -0,0 +1,92 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Price marker resolution for semantic projections (RFC-0767). Resolves {price:offering:chargeRef} markers to source-currency (EUR) strings for JSON-LD and meta tags. Also hosts the relocated DerivedPriceEntry type, OFFERING_URI_PREFIX constant, and PRICE_MARKER_RE regex shared between the semantic layer and packages/ui.</purpose>
+<non-goals>
+  <item>Does not read files — derived prices are passed as a parameter. File I/O lives in derived-prices-loader.ts.</item>
+  <item>Does not append recurrence suffixes — JSON-LD headline/description are free-text strings where recurrence is in the surrounding sentence.</item>
+  <item>Does not resolve markers in block-derived content or prose body — only heading, lead, description (RFC-0767 nonGoals).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0767: relocated DerivedPriceEntry, OFFERING_URI_PREFIX, PRICE_MARKER_RE from packages/ui to packages/share to break circular dependency.</item>
+  <item>RFC-0767: added formatSourcePrice and resolvePriceMarkersForSemantic for semantic-layer marker resolution.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * Derived price entry shape (moved from packages/ui to packages/share
+ * so both the semantic layer and UI components share a single type).
+ */
+export interface DerivedPriceEntry {
+  chargeRef: string;
+  targetCurrency: string;
+  amount: { value: string; currency: string };
+  trace: {
+    source: { amount: string; currency: string };
+    rate: { value: string; pair: string };
+    calculation?: {
+      rounding?: {
+        mode: string;
+        increment?: string;
+        decimalPlaces?: number;
+        output: string;
+      };
+    };
+  };
+}
+
+export const OFFERING_URI_PREFIX = "https://warpgogol.com/id/offerings/";
+export const PRICE_MARKER_RE = /\{price:([a-zA-Z0-9_-]+):([a-zA-Z0-9_.-]+)\}/g;
+export const AMOUNT_MARKER_RE = /\{amount:([0-9]+(?:\.[0-9]+)?)\}/g;
+
+/**
+ * Format a source-currency amount for semantic projections.
+ * Unlike formatPrice in packages/ui, this does NOT append a recurrence
+ * suffix — JSON-LD headline/description fields are free-text strings
+ * where the recurrence context is already in the surrounding sentence.
+ * Uses Intl.NumberFormat with currencyDisplay: "narrowSymbol".
+ * Output contains a non-breaking space (U+00A0) between number and symbol.
+ */
+export function formatSourcePrice(amount: string, lang: string): string {
+  const numericAmount = Number(amount);
+  if (!Number.isFinite(numericAmount)) return "0\u00A0€";
+  return new Intl.NumberFormat(lang, {
+    style: "currency",
+    currency: "EUR",
+    currencyDisplay: "narrowSymbol",
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 2,
+  }).format(numericAmount);
+}
+
+/**
+ * Resolve {price:offering:chargeRef} markers in a string to source-currency
+ * (EUR) formatted strings for use in semantic projections (JSON-LD, meta tags).
+ *
+ * Returns the input string unchanged if no markers are present.
+ * Returns "0 €" (with non-breaking space) for unknown offerings or chargeRefs
+ * (same fallback as parsePriceMarkers in packages/ui).
+ */
+export function resolvePriceMarkersForSemantic(
+  text: string,
+  lang: string,
+  derivedPrices?: Record<string, DerivedPriceEntry[]> | null,
+): string {
+  return text.replace(PRICE_MARKER_RE, (_match, offeringId: string, chargeRef: string) => {
+    const ref = OFFERING_URI_PREFIX + offeringId;
+    const entry = derivedPrices?.[ref]?.find((e) => e.chargeRef === chargeRef);
+    const sourceAmount = entry?.trace?.source?.amount ?? "0";
+    return formatSourcePrice(sourceAmount, lang);
+  });
+}
+
+/**
+ * Resolve {amount:NNNN} markers to source-currency (EUR) formatted strings
+ * for semantic projections (JSON-LD, meta tags). These markers represent
+ * literal EUR amounts (e.g. thresholds) that are not tied to an offering.
+ */
+export function resolveAmountMarkersForSemantic(text: string, lang: string): string {
+  return text.replace(AMOUNT_MARKER_RE, (_match, amount: string) => {
+    return formatSourcePrice(amount, lang);
+  });
+}

package/src/share/semantic/robots.ts

@@ -0,0 +1,127 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0052 robots.txt generation. Pure function buildRobotsTxt produces the
+  robots exclusion standard file from a structured RobotsPolicy config.
+</purpose>
+<non-goals>
+  <item>Do not read content files or validate input — the caller is responsible.</item>
+  <item>Do not manage default policy fallback — caller decides skip vs fallback.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0052: Initial implementation.</item>
+  <item>RFC-0784: Add contentSignal field and Content-Signal directive output.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface RobotsRule {
+  userAgent: string;
+  disallow: string[];
+  allow: string[];
+}
+
+export interface RobotsPolicy {
+  defaultPolicy?: "allow" | "disallow";
+  disallowedPaths?: string[];
+  allowedPaths?: string[];
+  crawlerBlocklist?: string[];
+  crawlerAllowlist?: string[];
+  sitemap?: string;
+  customRules?: RobotsRule[];
+  /** RFC-0784: Content-Signal directive — AI usage preferences (ai-train, search, ai-input). */
+  contentSignal?: string[];
+}
+
+export function buildRobotsTxt(policy: RobotsPolicy): string {
+  const lines: string[] = [];
+
+  lines.push("# robots.txt");
+  lines.push(`# Generated by robots.generate (RFC-0052)`);
+  lines.push("");
+
+  // RFC-0784: Content-Signal directive — placed after header comment, before User-agent block.
+  if (policy.contentSignal && policy.contentSignal.length > 0) {
+    lines.push(`Content-Signal: ${policy.contentSignal.join(", ")}`);
+    lines.push("");
+  }
+
+  const defaultPolicy = policy.defaultPolicy ?? "allow";
+  const defaultDisallow = policy.disallowedPaths ?? [];
+  const defaultAllow = policy.allowedPaths ?? [];
+  const blocklist = policy.crawlerBlocklist ?? [];
+  const allowlist = policy.crawlerAllowlist ?? [];
+  const customRules = policy.customRules ?? [];
+
+  // Default User-agent group
+  lines.push("# Default crawl policy");
+  lines.push("User-agent: *");
+
+  if (defaultPolicy === "disallow") {
+    if (defaultDisallow.length === 0) {
+      lines.push("Disallow: /");
+    } else {
+      for (const path of defaultDisallow) {
+        lines.push(`Disallow: ${path}`);
+      }
+    }
+  } else if (defaultDisallow.length > 0 || defaultAllow.length > 0) {
+    // Default allow with specific overrides
+    for (const path of defaultAllow) {
+      lines.push(`Allow: ${path}`);
+    }
+    for (const path of defaultDisallow) {
+      lines.push(`Disallow: ${path}`);
+    }
+  }
+  // Default allow with no overrides — omit redundant "Allow: /" (PUBTXT-09);
+  // the auxiliary discovery files below are explicitly allowed.
+
+  // Auxiliary discovery files — explicitly allowed for all crawlers
+  lines.push("");
+  lines.push("# Auxiliary discovery files — explicitly allowed for all crawlers");
+  lines.push("Allow: /robots.txt");
+  lines.push("Allow: /llms.txt");
+  lines.push("Allow: /llms-full.txt");
+  lines.push("Allow: /sitemap.xml");
+  lines.push("Allow: /sitemap-content.xml");
+
+  // Crawler allowlist (friendly AI / search crawlers)
+  if (allowlist.length > 0) {
+    lines.push("");
+    lines.push("# Allow known friendly crawlers explicitly");
+    for (const agent of allowlist) {
+      lines.push(`User-agent: ${agent}`);
+    }
+    lines.push("Allow: /");
+  }
+
+  // Crawler blocklist
+  if (blocklist.length > 0) {
+    lines.push("");
+    lines.push("# Block known low-value crawlers");
+    for (const agent of blocklist) {
+      lines.push(`User-agent: ${agent}`);
+    }
+    lines.push("Disallow: /");
+  }
+
+  // Custom per-user-agent rules
+  for (const rule of customRules) {
+    lines.push("");
+    lines.push(`User-agent: ${rule.userAgent}`);
+    for (const path of rule.disallow) {
+      lines.push(`Disallow: ${path}`);
+    }
+    for (const path of rule.allow) {
+      lines.push(`Allow: ${path}`);
+    }
+  }
+
+  // Sitemap reference
+  const sitemap = policy.sitemap ?? "/sitemap.xml";
+  lines.push("");
+  lines.push(`Sitemap: ${sitemap}`);
+
+  return lines.join("\n") + "\n";
+}

package/src/share/semantic/update-stamp.ts

@@ -0,0 +1,136 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0317: source-backed update-stamp resolver. Provides a deterministic,
+non-fabricated lastmod date for sitemap, feed, and Markdown twin provenance.
+Never uses build date, current time, or filesystem mtime.
+</purpose>
+<non-goals>
+  <item>Do not use new Date(), build time, or file mtime as a stamp source.</item>
+  <item>Do not fabricate stamps when no source is available — return undefined.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0317: initial implementation — authored frontmatter + sitemap.lastmod + CKL ledger sources.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type UpdateStampSource =
+  | "authored-page-frontmatter"
+  | "authored-system-output"
+  | "ckl-claim-ledger"
+  | "git-content-history";
+
+export interface PageUpdateStamp {
+  date: string; // YYYY-MM-DD
+  source: UpdateStampSource;
+  inputs: string[]; // content files or records that contributed
+}
+
+export type UpdateStampMissingReason =
+  "not-authored" | "git-unavailable" | "insufficient-history" | "no-content-source";
+
+export interface PageUpdateStampResult {
+  pageId: string;
+  lang: string;
+  stamp?: PageUpdateStamp;
+  missingReason?: UpdateStampMissingReason;
+}
+
+/** RFC-0317: validate a date string is YYYY-MM-DD. */
+export function isValidStampDate(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  return /^\d{4}-\d{2}-\d{2}$/.test(value);
+}
+
+/**
+ * RFC-0317 priority 1: explicit authored content date.
+ * Checks `output.sitemap.lastmod` and `article.updatedAt` / `article.publishedAt`
+ * from the system.md page entry.
+ */
+export function resolveAuthoredStamp(
+  pageEntry: Record<string, unknown>,
+): PageUpdateStamp | undefined {
+  const output = pageEntry.output as
+    | { sitemap?: { lastmod?: string }; article?: { updatedAt?: string; publishedAt?: string } }
+    | undefined;
+
+  const lastmod = output?.sitemap?.lastmod;
+  if (isValidStampDate(lastmod)) {
+    return {
+      date: lastmod,
+      source: "authored-system-output",
+      inputs: ["system.md:output.sitemap.lastmod"],
+    };
+  }
+
+  const article =
+    (pageEntry.article as { updatedAt?: string; publishedAt?: string } | undefined) ??
+    output?.article;
+  if (article) {
+    if (isValidStampDate(article.updatedAt)) {
+      return {
+        date: article.updatedAt,
+        source: "authored-page-frontmatter",
+        inputs: ["system.md:article.updatedAt"],
+      };
+    }
+    if (isValidStampDate(article.publishedAt)) {
+      return {
+        date: article.publishedAt,
+        source: "authored-page-frontmatter",
+        inputs: ["system.md:article.publishedAt"],
+      };
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * RFC-0317 priority 2: CKL claim ledger dates.
+ * Given a list of ledger asOf dates that match the page's business domain,
+ * return the latest one as a stamp.
+ */
+export function resolveCklStamp(
+  ledgerDates: string[],
+  inputs: string[],
+): PageUpdateStamp | undefined {
+  const valid = ledgerDates.filter(isValidStampDate);
+  if (valid.length === 0) return undefined;
+  const latest = [...valid].sort().at(-1)!;
+  return {
+    date: latest,
+    source: "ckl-claim-ledger",
+    inputs,
+  };
+}
+
+/**
+ * RFC-0317: resolve a single page's update stamp.
+ * Tries authored sources first, then CKL ledger if provided.
+ * Returns `stamp: undefined` when no allowed source is available.
+ */
+export function resolvePageUpdateStamp(params: {
+  pageId: string;
+  lang: string;
+  pageEntry: Record<string, unknown>;
+  cklLedgerDates?: string[];
+  cklInputs?: string[];
+}): PageUpdateStampResult {
+  const { pageId, lang, pageEntry, cklLedgerDates, cklInputs } = params;
+
+  const authored = resolveAuthoredStamp(pageEntry);
+  if (authored) {
+    return { pageId, lang, stamp: authored };
+  }
+
+  if (cklLedgerDates && cklLedgerDates.length > 0) {
+    const ckl = resolveCklStamp(cklLedgerDates, cklInputs ?? []);
+    if (ckl) {
+      return { pageId, lang, stamp: ckl };
+    }
+  }
+
+  return { pageId, lang, missingReason: "no-content-source" };
+}

package/src/share/shared-context.ts

@@ -0,0 +1,177 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Implements RFC-0099 page-driven shared component context resolution.
+Provides app-agnostic helpers that merge block props from other pages using
+priority order derived from system.md.
+</purpose>
+<non-goals>
+  <item>Do not read files or Astro collections directly.</item>
+  <item>Do not validate propsSchema correctness.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0099: Added shared page-driven context fallback helpers.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { deepMergeEntryData } from "./content/merge.ts";
+
+export interface SharedContextBlockLike {
+  id?: string;
+  type?: string;
+  use?: string;
+  props?: Record<string, unknown>;
+}
+
+export interface SharedContextPageLike {
+  pageId: string;
+  blocks: SharedContextBlockLike[];
+}
+
+export interface SharedContextCandidate {
+  pageId: string;
+  block: SharedContextBlockLike;
+}
+
+export interface SharedContextCandidatesByLevel {
+  home: SharedContextCandidate[];
+  required: SharedContextCandidate[];
+  other: SharedContextCandidate[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function getBlockSelector(block: SharedContextBlockLike): string | null {
+  return block.type ?? block.use ?? null;
+}
+
+function matchesSharedBlock(
+  source: SharedContextBlockLike,
+  target: SharedContextBlockLike,
+): boolean {
+  if (!source.id || !target.id || source.id !== target.id) {
+    return false;
+  }
+
+  const sourceSelector = getBlockSelector(source);
+  const targetSelector = getBlockSelector(target);
+
+  if (sourceSelector && targetSelector) {
+    return sourceSelector === targetSelector;
+  }
+
+  return true;
+}
+
+export function buildSharedContextPageOrder(options: {
+  currentPageId: string;
+  allPageIds: string[];
+  requiredPageIds?: string[];
+  homePageId?: string;
+}): string[] {
+  const { currentPageId, allPageIds, requiredPageIds = [], homePageId = "home" } = options;
+
+  const remaining = allPageIds.filter((pageId) => pageId !== currentPageId);
+  const ordered: string[] = [];
+
+  if (remaining.includes(homePageId)) {
+    ordered.push(homePageId);
+  }
+
+  for (const pageId of requiredPageIds) {
+    if (pageId !== currentPageId && pageId !== homePageId && remaining.includes(pageId)) {
+      ordered.push(pageId);
+    }
+  }
+
+  for (const pageId of remaining) {
+    if (!ordered.includes(pageId)) {
+      ordered.push(pageId);
+    }
+  }
+
+  return ordered;
+}
+
+export function collectSharedContextCandidatesByLevel(options: {
+  currentPageId: string;
+  block: SharedContextBlockLike;
+  pages: Map<string, SharedContextPageLike>;
+  requiredPageIds?: string[];
+  homePageId?: string;
+}): SharedContextCandidatesByLevel {
+  const { currentPageId, block, pages, requiredPageIds = [], homePageId = "home" } = options;
+
+  const result: SharedContextCandidatesByLevel = {
+    home: [],
+    required: [],
+    other: [],
+  };
+
+  if (!block.id) {
+    return result;
+  }
+
+  const allPageIds = [...pages.keys()];
+  const ordered = buildSharedContextPageOrder({
+    currentPageId,
+    allPageIds,
+    requiredPageIds,
+    homePageId,
+  });
+
+  for (const pageId of ordered) {
+    const page = pages.get(pageId);
+    if (!page) continue;
+
+    const candidateBlock = page.blocks.find((sourceBlock) =>
+      matchesSharedBlock(sourceBlock, block),
+    );
+    if (!candidateBlock) continue;
+
+    const candidate = { pageId, block: candidateBlock };
+
+    if (pageId === homePageId) {
+      result.home.push(candidate);
+    } else if (requiredPageIds.includes(pageId)) {
+      result.required.push(candidate);
+    } else {
+      result.other.push(candidate);
+    }
+  }
+
+  return result;
+}
+
+export function resolveSharedContextProps(options: {
+  currentPageId: string;
+  block: SharedContextBlockLike;
+  pages: Map<string, SharedContextPageLike>;
+  requiredPageIds?: string[];
+  homePageId?: string;
+}): Record<string, unknown> {
+  const { currentPageId, block, pages, requiredPageIds = [], homePageId = "home" } = options;
+
+  const explicitProps = isRecord(block.props) ? block.props : {};
+  if (!block.id) {
+    return explicitProps;
+  }
+
+  const candidates = collectSharedContextCandidatesByLevel({
+    currentPageId,
+    block,
+    pages,
+    requiredPageIds,
+    homePageId,
+  });
+
+  const source = candidates.home[0] ?? candidates.required[0] ?? candidates.other[0];
+  if (!source || !isRecord(source.block.props)) {
+    return explicitProps;
+  }
+
+  return deepMergeEntryData(source.block.props, explicitProps);
+}

package/src/share/string-utils.ts

@@ -0,0 +1,19 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/string-utils.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Dedup: centralise the kebab-case helper previously duplicated in site-kernel and site-kernel-checks.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** Lowercase, dash-only kebab-case. Strips leading/trailing hyphens. */
+export function toKebabCase(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}