@eox/pages-theme-eox 2.0.0-alpha.5 → 2.0.0-alpha.7

package/src/llms/storiesPlugin.js

@@ -0,0 +1,771 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import pc from "picocolors";
+import { createLogger } from "vite";
+
+const prefix = pc.blue("llmstxt (stories)") + pc.dim(" »");
+let logger = createLogger("info", { prefix });
+
+/**
+ * Creates the stories build-time Vite plugin.
+ * @param {object} params
+ * @param {object | boolean | string} [params.storiesOption]
+ * @param {object} [params.brandConfig]
+ * @param {string | null} [params.domain]
+ * @returns {import("vite").Plugin}
+ */
+export function createStoriesPlugin({
+  storiesOption,
+  brandConfig = {},
+  domain = null,
+}) {
+  let outDir = "dist";
+  let base = "/";
+  let srcDir = process.cwd();
+  let isSsrBuild = false;
+
+  const config =
+    typeof storiesOption === "object" && storiesOption !== null
+      ? storiesOption
+      : typeof storiesOption === "string"
+        ? { manifest: storiesOption }
+        : {};
+
+  const heading = config.heading || "Stories";
+  const concurrency = config.concurrency || 8;
+
+  return {
+    name: "@eox/pages-theme-eox:llms-stories",
+    enforce: "post",
+    apply: "build",
+    configResolved(resolvedConfig) {
+      logger = createLogger(resolvedConfig.logLevel, {
+        prefix,
+        allowClearScreen: resolvedConfig.clearScreen,
+      });
+      outDir =
+        resolvedConfig.vitepress?.outDir ||
+        (resolvedConfig.build?.outDir
+          ? path.resolve(
+              resolvedConfig.root || process.cwd(),
+              resolvedConfig.build.outDir,
+            )
+          : path.resolve(resolvedConfig.root || process.cwd(), "dist"));
+      base = resolvedConfig.base || resolvedConfig.vitepress?.site?.base || "/";
+      srcDir =
+        resolvedConfig.vitepress?.srcDir ||
+        resolvedConfig.root ||
+        process.cwd();
+      isSsrBuild = Boolean(resolvedConfig.build?.ssr);
+    },
+    async closeBundle() {
+      if (isSsrBuild) return;
+
+      try {
+        const resolved = await resolveAndFetchManifest({
+          explicitUrl: config.manifest,
+          brandStories: brandConfig.stories,
+          srcDir,
+        });
+
+        if (!resolved) return;
+        const { manifestUrl, manifest, sourceMarkdownPath } = resolved;
+
+        const manifestBaseUrl = manifestUrl.substring(
+          0,
+          manifestUrl.lastIndexOf("/"),
+        );
+        const sourceRelPath = sourceMarkdownPath
+          ? path.relative(srcDir, sourceMarkdownPath)
+          : null;
+        const routing = resolveStoryRouting({
+          sourceRelPath,
+          configuredPath: config.storyPath || config.path,
+        });
+
+        const stories = await fetchStories({
+          manifest,
+          manifestBaseUrl,
+          base,
+          domain,
+          routing,
+          concurrency,
+        });
+
+        if (stories.length === 0) return;
+
+        if (routing.isDynamic) {
+          await writeIndividualStoryFiles({
+            outDir,
+            routeDir: routing.routeDir,
+            stories,
+          });
+        }
+
+        await appendToLlmsTxt({ outDir, heading, stories });
+        await appendToLlmsFullTxt({ outDir, heading, stories });
+        await appendToStoryRoutePage({
+          outDir,
+          heading,
+          stories,
+          sourceMarkdownPath,
+          srcDir,
+          routing,
+        });
+      } catch (err) {
+        logger.warn(`Failed during stories processing: ${err?.message || err}`);
+      }
+    },
+  };
+}
+
+/**
+ * Converts a relative markdown file path to a route URL path.
+ * @param {string | null | undefined} relPath
+ * @returns {string}
+ */
+export function routeFromRelativePath(relPath) {
+  if (!relPath || typeof relPath !== "string") return "/story";
+  let clean = relPath.replace(/\\/g, "/").replace(/\.(md|html)$/, "");
+  if (clean === "index" || clean === "") return "/";
+  if (clean.endsWith("/index")) clean = clean.slice(0, -"/index".length);
+  return clean.startsWith("/") ? clean : `/${clean}`;
+}
+
+const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Strips common markdown and dynamic route script extensions.
+ */
+const ROUTE_EXT_REGEX = /\.(md|html|paths\.[cm]?[jt]s)$/;
+
+/**
+ * Resolves routing information for stories based on source file and configuration.
+ * Detects whether the stories are hosted on a dynamic route (e.g. narratives/[narrative].md or [narrative].paths.js)
+ * or a single page (e.g. story.md).
+ * @param {object} [params]
+ * @param {string | null} [params.sourceRelPath]
+ * @param {string} [params.configuredPath]
+ * @returns {{ isDynamic: boolean, routeDir: string, routePath: string }}
+ */
+export function resolveStoryRouting({
+  sourceRelPath = null,
+  configuredPath = "",
+} = {}) {
+  if (configuredPath) {
+    const cleanConfigured = configuredPath
+      .replace(/\\/g, "/")
+      .replace(ROUTE_EXT_REGEX, "");
+    const isDynamic = cleanConfigured.includes("[");
+    if (isDynamic) {
+      const parts = cleanConfigured.split("/");
+      if (parts[parts.length - 1].startsWith("[")) {
+        parts.pop();
+      }
+      const routeDir = parts.join("/").replace(/^\/+|\/+$/g, "");
+      const routePath = routeDir ? `/${routeDir}` : "/";
+      return { isDynamic, routeDir, routePath };
+    }
+    const routePath = routeFromRelativePath(cleanConfigured);
+    const routeDir = routePath.replace(/^\/+|\/+$/g, "");
+    return { isDynamic: false, routeDir, routePath };
+  }
+
+  if (sourceRelPath) {
+    const cleanSource = sourceRelPath
+      .replace(/\\/g, "/")
+      .replace(ROUTE_EXT_REGEX, "");
+    if (/(?:^|\/)\[.+?\]/.test(cleanSource)) {
+      const parts = cleanSource.split("/");
+      parts.pop();
+      const routeDir = parts.join("/").replace(/^\/+|\/+$/g, "");
+      return {
+        isDynamic: true,
+        routeDir,
+        routePath: routeDir ? `/${routeDir}` : "/",
+      };
+    }
+    const routePath = routeFromRelativePath(sourceRelPath);
+    const routeDir = routePath.replace(/^\/+|\/+$/g, "");
+    return { isDynamic: false, routeDir, routePath };
+  }
+
+  return { isDynamic: false, routeDir: "story", routePath: "/story" };
+}
+
+/**
+ * Builds a story URL.
+ * Dynamic routes produce clean path URLs: /{base}/{routeDir}/{storyId}{extension}
+ * Single-page routes produce query param URLs: /{base}/{storyPath}?id={storyId}
+ * @param {object} params
+ * @param {string | null} [params.domain]
+ * @param {string} [params.base]
+ * @param {string} [params.routeDir]
+ * @param {string} [params.storyPath]
+ * @param {string} [params.storyId]
+ * @param {boolean} [params.isDynamic]
+ * @param {string} [params.extension]
+ * @returns {string}
+ */
+export function buildStoryUrl({
+  domain = null,
+  base = "/",
+  routeDir = "story",
+  storyPath = "/story",
+  storyId = "",
+  isDynamic = false,
+  extension = "",
+}) {
+  const baseSegment = base === "/" ? "" : base.replace(/^\/+|\/+$/g, "");
+
+  if (isDynamic) {
+    const dirSegment = routeDir ? routeDir.replace(/^\/+|\/+$/g, "") : "";
+    const idSegment = storyId ? `${storyId}${extension}` : "";
+    const segments = [baseSegment, dirSegment, idSegment].filter(Boolean);
+    const pathWithBase = `/${segments.join("/")}`;
+    return domain ? `${domain}${pathWithBase}` : pathWithBase;
+  }
+
+  const pathSegment = storyPath ? storyPath.replace(/^\/+|\/+$/g, "") : "";
+  const segments = [baseSegment, pathSegment].filter(Boolean);
+  const pathWithBase = `/${segments.join("/")}`;
+  const query = storyId ? `?id=${storyId}` : "";
+  return domain
+    ? `${domain}${pathWithBase}${query}`
+    : `${pathWithBase}${query}`;
+}
+
+/**
+ * Writes individual sanitized markdown files for dynamic route stories.
+ * E.g., dist/narratives/austrian-air-source-heating-potential.md
+ * @param {object} params
+ * @param {string} params.outDir
+ * @param {string} params.routeDir
+ * @param {any[]} params.stories
+ */
+export async function writeIndividualStoryFiles({ outDir, routeDir, stories }) {
+  const resolvedOutDir = path.resolve(outDir);
+  const cleanDir = routeDir
+    ? routeDir.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "")
+    : "";
+  const targetDir = cleanDir
+    ? path.resolve(resolvedOutDir, cleanDir)
+    : resolvedOutDir;
+
+  if (
+    targetDir !== resolvedOutDir &&
+    !targetDir.startsWith(resolvedOutDir + path.sep)
+  ) {
+    logger.warn(
+      `Security warning: targetDir "${targetDir}" is outside outDir "${resolvedOutDir}"`,
+    );
+    return;
+  }
+
+  await fs.mkdir(targetDir, { recursive: true });
+
+  for (const story of stories) {
+    if (!story.cleanedBody || !story.storyId) continue;
+    try {
+      const safeId = path.basename(story.storyId);
+      if (!safeId || safeId === "." || safeId === "..") continue;
+      const filePath = path.resolve(targetDir, `${safeId}.md`);
+      if (!filePath.startsWith(resolvedOutDir + path.sep)) {
+        logger.warn(
+          `Security warning: skipping file path outside outDir: ${filePath}`,
+        );
+        continue;
+      }
+      const content = `# ${story.title}\n\n${story.cleanedBody}\n`;
+      await fs.writeFile(filePath, content, "utf8");
+    } catch (err) {
+      logger.warn(
+        `Failed to write story file for ${story.storyId}: ${err?.message || err}`,
+      );
+    }
+  }
+}
+
+/**
+ * Normalizes text by trimming and collapsing contiguous whitespace.
+ * @param {string | undefined | null} str
+ * @returns {string}
+ */
+export function normalizeWhitespace(str) {
+  if (!str || typeof str !== "string") return "";
+  return str.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Derives story id from file path matching upstream behavior:
+ * last path segment, truncated at the first dot.
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function deriveStoryId(filePath) {
+  if (!filePath || typeof filePath !== "string") return "";
+  const filename = filePath.split("/").pop() || "";
+  return filename.split(".")[0];
+}
+
+/**
+ * Cleans story markdown by stripping metadata, comments, and normalizing headings.
+ * @param {string} content
+ * @param {string} title
+ * @param {string} [manifestBaseUrl]
+ * @returns {string}
+ */
+export function cleanStory(content, title, manifestBaseUrl = "") {
+  if (!content || typeof content !== "string") return "";
+
+  let cleaned = content
+    .replace(/^---[\s\S]*?---\n?/, "")
+    .replace(/<!--\{[\s\S]*?\}-->/g, "")
+    .replace(/<!--[\s\S]*?-->/g, "");
+
+  if (manifestBaseUrl) {
+    const base = manifestBaseUrl.replace(/\/+$/, "");
+    cleaned = cleaned.replace(
+      /!\[(.*?)\]\((?!https?:\/\/|\/)(.*?)\)/g,
+      (_, alt, imgPath) => `![${alt}](${base}/${imgPath.replace(/^\.\//, "")})`,
+    );
+  }
+
+  return normalizeHeadings(cleaned, title);
+}
+
+/**
+ * Normalizes headings: drops redundant leading H1 matching title, demotes remaining headings.
+ * @param {string} content
+ * @param {string} title
+ * @returns {string}
+ */
+export function normalizeHeadings(content, title) {
+  const normalizedTitle = normalizeWhitespace(title).toLowerCase();
+  const lines = content.split("\n");
+  const processedLines = [];
+  let droppedLeadingH1 = false;
+
+  for (const line of lines) {
+    const h1Match = line.match(/^#\s+(.*)$/);
+    if (
+      !droppedLeadingH1 &&
+      h1Match &&
+      normalizeWhitespace(h1Match[1]).toLowerCase() === normalizedTitle
+    ) {
+      droppedLeadingH1 = true;
+      continue;
+    }
+    processedLines.push(/^#{1,5}\s+/.test(line) ? `#${line}` : line);
+  }
+
+  return processedLines.join("\n").trim();
+}
+
+/**
+ * Maps items with a concurrency limit.
+ * @template T, R
+ * @param {T[]} items
+ * @param {number} limit
+ * @param {(item: T) => Promise<R>} iterator
+ * @returns {Promise<R[]>}
+ */
+export async function mapConcurrent(items, limit, iterator) {
+  const results = new Array(items.length);
+  let currentIndex = 0;
+
+  const workers = Array.from(
+    { length: Math.min(limit, items.length) },
+    async () => {
+      while (currentIndex < items.length) {
+        const index = currentIndex++;
+        results[index] = await iterator(items[index]);
+      }
+    },
+  );
+
+  await Promise.all(workers);
+  return results;
+}
+
+/**
+ * Scans markdown and script files in srcDir to discover candidate story manifest URLs.
+ * @param {string} srcDir
+ * @returns {Promise<Array<{ url: string, filePath: string }>>}
+ */
+export async function detectManifestCandidates(srcDir) {
+  const candidates = new Map();
+  const urlRegex = /https?:\/\/[^\s'"\)\`]+(?:stories|narratives)\.json/g;
+
+  async function scanDir(dir) {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (
+          entry.isDirectory() &&
+          entry.name !== "node_modules" &&
+          entry.name !== ".vitepress"
+        ) {
+          await scanDir(fullPath);
+        } else if (entry.isFile() && /\.(md|js|mjs|ts)$/.test(entry.name)) {
+          const content = await fs.readFile(fullPath, "utf8");
+          const matches = content.match(urlRegex) || [];
+          matches.forEach((url) => {
+            if (!candidates.has(url)) {
+              candidates.set(url, fullPath);
+            }
+          });
+        }
+      }
+    } catch {
+      // Ignore read errors gracefully
+    }
+  }
+
+  await scanDir(srcDir);
+  return Array.from(candidates.entries()).map(([url, filePath]) => ({
+    url,
+    filePath,
+  }));
+}
+
+/**
+ * Fetches and parses a manifest JSON array.
+ * @param {string} url
+ * @returns {Promise<any[] | null>}
+ */
+export async function fetchManifest(url) {
+  try {
+    const res = await fetch(url);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return Array.isArray(data) ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolves manifest URL from options, brand config, or source files, and fetches the manifest.
+ * @param {object} params
+ * @param {string} [params.explicitUrl]
+ * @param {string | object} [params.brandStories]
+ * @param {string} params.srcDir
+ * @returns {Promise<{ manifestUrl: string, manifest: any[], sourceMarkdownPath: string | null } | null>}
+ */
+export async function resolveAndFetchManifest({
+  explicitUrl,
+  brandStories,
+  srcDir,
+}) {
+  let manifestUrl = explicitUrl || null;
+
+  if (!manifestUrl && brandStories) {
+    manifestUrl =
+      typeof brandStories === "string" ? brandStories : brandStories.manifest;
+  }
+
+  if (manifestUrl) {
+    const manifest = await fetchManifest(manifestUrl);
+    return manifest
+      ? { manifestUrl, manifest, sourceMarkdownPath: null }
+      : null;
+  }
+
+  const candidates = await detectManifestCandidates(srcDir);
+  if (candidates.length === 1) {
+    const { url, filePath } = candidates[0];
+    const manifest = await fetchManifest(url);
+    if (manifest) {
+      logger.info(`Detected stories manifest: ${pc.cyan(url)}`);
+      return { manifestUrl: url, manifest, sourceMarkdownPath: filePath };
+    }
+  } else if (candidates.length > 1) {
+    logger.warn(
+      `Multiple story manifest candidates detected; skipping: ${candidates.map((c) => c.url).join(", ")}`,
+    );
+  }
+
+  return null;
+}
+
+/**
+ * Fetches and processes story records concurrently.
+ * @param {object} params
+ * @returns {Promise<any[]>}
+ */
+export async function fetchStories({
+  manifest,
+  manifestBaseUrl,
+  base = "/",
+  routing = { isDynamic: false, routeDir: "story", routePath: "/story" },
+  domain = null,
+  concurrency = 8,
+}) {
+  const stories = await mapConcurrent(manifest, concurrency, (entry, index) =>
+    fetchStory({
+      entry,
+      index,
+      manifestBaseUrl,
+      base,
+      routing,
+      domain,
+    }),
+  );
+
+  return stories.filter(Boolean);
+}
+
+/**
+ * Fetches and processes an individual story.
+ * @param {object} params
+ * @returns {Promise<object | null>}
+ */
+export async function fetchStory({
+  entry,
+  index,
+  manifestBaseUrl,
+  base = "/",
+  routing = { isDynamic: false, routeDir: "story", routePath: "/story" },
+  domain = null,
+}) {
+  if (!entry || typeof entry !== "object" || !entry.file || !entry.title) {
+    logger.warn(`Skipping invalid story at index ${index}`);
+    return null;
+  }
+
+  const title = normalizeWhitespace(entry.title);
+  const subtitle = normalizeWhitespace(entry.subtitle);
+  const storyId = deriveStoryId(entry.file);
+  const markdownUrl = /^https?:\/\//.test(entry.file)
+    ? entry.file
+    : `${manifestBaseUrl}/${entry.file.replace(/^\.\//, "")}`;
+
+  const { isDynamic, routeDir, routePath } = routing;
+
+  const storyUrl = buildStoryUrl({
+    domain,
+    base,
+    routeDir,
+    storyPath: routePath,
+    storyId,
+    isDynamic,
+    extension: "",
+  });
+
+  const cleanedBody = await fetchStoryMarkdown(
+    markdownUrl,
+    title,
+    manifestBaseUrl,
+  );
+
+  const docUrl =
+    isDynamic && cleanedBody
+      ? buildStoryUrl({
+          domain,
+          base,
+          routeDir,
+          storyPath: routePath,
+          storyId,
+          isDynamic: true,
+          extension: ".md",
+        })
+      : markdownUrl;
+
+  return {
+    title,
+    subtitle,
+    storyId,
+    markdownUrl,
+    docUrl,
+    storyUrl,
+    cleanedBody,
+  };
+}
+
+/**
+ * Fetches and sanitizes markdown for a story.
+ * @param {string} markdownUrl
+ * @param {string} title
+ * @param {string} manifestBaseUrl
+ * @returns {Promise<string | null>}
+ */
+export async function fetchStoryMarkdown(markdownUrl, title, manifestBaseUrl) {
+  try {
+    const res = await fetch(markdownUrl);
+    if (!res.ok) {
+      logger.warn(`Failed to fetch story body: ${markdownUrl} (${res.status})`);
+      return null;
+    }
+    const text = await res.text();
+    return cleanStory(text, title, manifestBaseUrl);
+  } catch {
+    logger.warn(`Network error fetching story: ${markdownUrl}`);
+    return null;
+  }
+}
+
+/**
+ * Appends stories index section to llms.txt if it exists.
+ * @param {object} params
+ */
+export async function appendToLlmsTxt({ outDir, heading, stories }) {
+  const llmsTxtPath = path.resolve(outDir, "llms.txt");
+  let existing;
+  try {
+    existing = await fs.readFile(llmsTxtPath, "utf8");
+  } catch (err) {
+    if (err?.code !== "ENOENT") {
+      logger.warn(`Failed to read llms.txt: ${err?.message || err}`);
+    }
+    return;
+  }
+
+  const headingRegex = new RegExp(`^##\\s+${escapeRegex(heading)}\\s*$`, "m");
+  if (headingRegex.test(existing)) {
+    return;
+  }
+
+  const indexLines = stories.map((e) => {
+    const targetUrl = !e.cleanedBody
+      ? e.markdownUrl
+      : e.docUrl || e.markdownUrl;
+    const desc = e.subtitle
+      ? `${e.subtitle}. Story page: ${e.storyUrl}`
+      : `Story page: ${e.storyUrl}`;
+    return `- [${e.title}](${targetUrl}): ${desc}`;
+  });
+  const appendContent = `\n\n## ${heading}\n\n${indexLines.join("\n")}\n`;
+  try {
+    await fs.appendFile(llmsTxtPath, appendContent, "utf8");
+  } catch (err) {
+    logger.warn(`Failed to append to llms.txt: ${err?.message || err}`);
+  }
+}
+
+/**
+ * Appends full stories text to llms-full.txt if it exists.
+ * @param {object} params
+ */
+export async function appendToLlmsFullTxt({ outDir, heading, stories }) {
+  const llmsFullTxtPath = path.resolve(outDir, "llms-full.txt");
+  let existing;
+  try {
+    existing = await fs.readFile(llmsFullTxtPath, "utf8");
+  } catch (err) {
+    if (err?.code !== "ENOENT") {
+      logger.warn(`Failed to read llms-full.txt: ${err?.message || err}`);
+    }
+    return;
+  }
+
+  const headingRegex = new RegExp(`^#\\s+${escapeRegex(heading)}\\s*$`, "m");
+  if (headingRegex.test(existing)) {
+    return;
+  }
+
+  const fullSections = stories
+    .filter((e) => e.cleanedBody)
+    .map(
+      (e) =>
+        `## ${e.title}\n\nSource: ${e.docUrl || e.markdownUrl}\nStory: ${e.storyUrl}\n\n${e.cleanedBody}`,
+    );
+
+  if (fullSections.length > 0) {
+    const appendContent = `\n\n# ${heading}\n\n${fullSections.join("\n\n---\n\n")}\n`;
+    try {
+      await fs.appendFile(llmsFullTxtPath, appendContent, "utf8");
+    } catch (err) {
+      logger.warn(`Failed to append to llms-full.txt: ${err?.message || err}`);
+    }
+  }
+}
+
+/**
+ * Appends stories index section to the generated story markdown page in outDir.
+ * @param {object} params
+ */
+export async function appendToStoryRoutePage({
+  outDir,
+  heading,
+  stories,
+  sourceMarkdownPath = null,
+  srcDir = null,
+  routing = { isDynamic: false, routeDir: "story", routePath: "/story" },
+}) {
+  let targetStoryPath = null;
+  const { isDynamic, routeDir, routePath } = routing;
+
+  if (sourceMarkdownPath && srcDir) {
+    const relativePath = path.relative(srcDir, sourceMarkdownPath);
+    if (!/\[.+?\]/.test(relativePath) && relativePath.endsWith(".md")) {
+      const candidatePath = path.resolve(outDir, relativePath);
+      try {
+        await fs.access(candidatePath);
+        targetStoryPath = candidatePath;
+      } catch {
+        // Fall through to fallback paths
+      }
+    }
+  }
+
+  if (!targetStoryPath) {
+    const cleanRoute = (isDynamic ? routeDir : routePath)
+      .replace(/\\/g, "/")
+      .replace(/^\/+|\/+$/g, "")
+      .replace(/\.md$/, "");
+    const candidatePaths = cleanRoute
+      ? [
+          path.resolve(outDir, `${cleanRoute}.md`),
+          path.resolve(outDir, cleanRoute, "index.md"),
+        ]
+      : isDynamic
+        ? []
+        : [path.resolve(outDir, "index.md")];
+
+    for (const candidate of candidatePaths) {
+      try {
+        await fs.access(candidate);
+        targetStoryPath = candidate;
+        break;
+      } catch {
+        // Continue
+      }
+    }
+  }
+
+  if (!targetStoryPath) return;
+
+  const indexLines = stories.map((e) => {
+    const targetUrl = !e.cleanedBody
+      ? e.markdownUrl
+      : e.docUrl || e.markdownUrl;
+    const desc = e.subtitle
+      ? `${e.subtitle}. [View story](${e.storyUrl})`
+      : `[View story](${e.storyUrl})`;
+    return `- [${e.title}](${targetUrl}) — ${desc}`;
+  });
+
+  let existing;
+  try {
+    existing = await fs.readFile(targetStoryPath, "utf8");
+  } catch (err) {
+    if (err?.code !== "ENOENT") {
+      logger.warn(`Failed to read story route page: ${err?.message || err}`);
+    }
+    return;
+  }
+
+  const headingRegex = new RegExp(`^##\\s+${escapeRegex(heading)}\\s*$`, "m");
+  if (headingRegex.test(existing)) {
+    return;
+  }
+
+  const appendContent = `\n\n## ${heading}\n\n${indexLines.join("\n")}\n`;
+  try {
+    await fs.appendFile(targetStoryPath, appendContent, "utf8");
+  } catch (err) {
+    logger.warn(`Failed to append to story route page: ${err?.message || err}`);
+  }
+}