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

package/src/llms/llms.test.js

@@ -0,0 +1,980 @@
+import { describe, it, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { resolveLlms, normalizeDomain } from "./index.js";
+import {
+  cleanStory,
+  deriveStoryId,
+  normalizeWhitespace,
+  normalizeHeadings,
+  mapConcurrent,
+  detectManifestCandidates,
+  fetchManifest,
+  resolveAndFetchManifest,
+  fetchStoryMarkdown,
+  fetchStory,
+  fetchStories,
+  appendToLlmsTxt,
+  appendToLlmsFullTxt,
+  appendToStoryRoutePage,
+  routeFromRelativePath,
+  buildStoryUrl,
+  resolveStoryRouting,
+  writeIndividualStoryFiles,
+} from "./storiesPlugin.js";
+
+describe("normalizeDomain", () => {
+  it("strips trailing slashes correctly", () => {
+    assert.equal(
+      normalizeDomain("https://example.com/"),
+      "https://example.com",
+    );
+    assert.equal(
+      normalizeDomain("https://example.com///"),
+      "https://example.com",
+    );
+    assert.equal(normalizeDomain("https://example.com"), "https://example.com");
+    assert.equal(normalizeDomain(""), null);
+    assert.equal(normalizeDomain(null), null);
+    assert.equal(normalizeDomain(undefined), null);
+  });
+});
+
+describe("resolveLlms", () => {
+  it("returns empty plugins when option is false", () => {
+    const res = resolveLlms(false, "https://example.com");
+    assert.deepEqual(res.plugins, []);
+  });
+
+  it("enables default plugins when option is undefined or true", () => {
+    const res1 = resolveLlms(undefined, "https://example.com/");
+    assert.equal(res1.plugins.length, 3);
+
+    const res2 = resolveLlms(true, "https://example.com/");
+    assert.equal(res2.plugins.length, 3);
+  });
+
+  it("normalizes domain and strips trailing slashes", () => {
+    const res = resolveLlms(
+      { domain: "https://hub.eox.at///" },
+      "https://example.com",
+    );
+    assert.equal(res.plugins.length, 3);
+    assert.equal(res.domain, "https://hub.eox.at");
+  });
+
+  it("excludes stories plugin when stories is false", () => {
+    const res = resolveLlms({ stories: false }, "https://example.com");
+    assert.equal(res.plugins.length, 2);
+    assert.ok(res.plugins.some((p) => p.name === "vitepress-plugin-llms"));
+    assert.ok(
+      !res.plugins.some((p) => p.name === "@eox/pages-theme-eox:llms-stories"),
+    );
+  });
+
+  it("separates package-specific flags from upstream options", () => {
+    const res = resolveLlms(
+      {
+        copyButtons: true,
+        stories: { heading: "Featured Stories" },
+        ignorePaths: ["private/**"],
+      },
+      "https://example.com",
+    );
+    assert.equal(res.plugins.length, 3);
+    assert.equal(res.plugins[2].name, "@eox/pages-theme-eox:llms-stories");
+    assert.equal(res.copyButtons, true);
+    assert.deepEqual(res.stories, { heading: "Featured Stories" });
+  });
+});
+
+describe("deriveStoryId", () => {
+  it("extracts filename segment before the first dot", () => {
+    assert.equal(deriveStoryId("stories/air-quality.v1.md"), "air-quality");
+    assert.equal(deriveStoryId("./wildfire.md"), "wildfire");
+    assert.equal(
+      deriveStoryId("https://example.com/narratives/flood-monitoring.step2.md"),
+      "flood-monitoring",
+    );
+    assert.equal(deriveStoryId("simple-slug"), "simple-slug");
+    assert.equal(deriveStoryId(""), "");
+    assert.equal(deriveStoryId(null), "");
+    assert.equal(deriveStoryId(undefined), "");
+  });
+});
+
+describe("normalizeWhitespace", () => {
+  it("collapses multiple spaces, tabs, and newlines into a single space and trims", () => {
+    assert.equal(
+      normalizeWhitespace("   Hello \n\n  world!  \t"),
+      "Hello world!",
+    );
+    assert.equal(normalizeWhitespace("NoExtraSpaces"), "NoExtraSpaces");
+    assert.equal(normalizeWhitespace(null), "");
+    assert.equal(normalizeWhitespace(undefined), "");
+  });
+});
+
+describe("normalizeHeadings", () => {
+  it("demotes all headings by one level (# -> ##, ## -> ###)", () => {
+    const markdown = `# Title\n## Sub\n### Subsub\n#### Level 4\n##### Level 5`;
+    const res = normalizeHeadings(markdown, "Different Title");
+    assert.ok(res.includes("## Title"));
+    assert.ok(res.includes("### Sub"));
+    assert.ok(res.includes("#### Subsub"));
+    assert.ok(res.includes("##### Level 4"));
+    assert.ok(res.includes("###### Level 5"));
+  });
+
+  it("does not demote text lines starting with # but without space", () => {
+    const markdown = `#hashtag and #123 should remain`;
+    const res = normalizeHeadings(markdown, "Title");
+    assert.equal(res, `#hashtag and #123 should remain`);
+  });
+});
+
+describe("cleanStory", () => {
+  it("strips frontmatter, comments, storytelling directives and demotes headings", () => {
+    const raw = `---
+title: Ignored Frontmatter Title
+layout: story
+---
+<!--{
+  "theme": "dark",
+  "steps": [1, 2]
+}-->
+# My Story Title
+
+<!-- A normal HTML comment -->
+Some story introductory text.
+
+## Background
+
+![Map Image](./images/map.png)
+![External Image](https://cdn.example.com/ext.png)
+![Absolute Image](/images/abs.png)
+
+### Details
+More details here.
+`;
+
+    const cleaned = cleanStory(
+      raw,
+      "My Story Title",
+      "https://cdn.example.com/stories",
+    );
+
+    assert.ok(!cleaned.includes("---"));
+    assert.ok(!cleaned.includes("Ignored Frontmatter Title"));
+    assert.ok(!cleaned.includes("theme"));
+    assert.ok(!cleaned.includes("steps"));
+    assert.ok(!cleaned.includes("A normal HTML comment"));
+    // Leading H1 matching title removed
+    assert.ok(!cleaned.includes("# My Story Title"));
+    // Headings demoted by one level: ## -> ###, ### -> ####
+    assert.ok(cleaned.includes("### Background"));
+    assert.ok(cleaned.includes("#### Details"));
+    // Relative image resolved
+    assert.ok(
+      cleaned.includes(
+        "![Map Image](https://cdn.example.com/stories/images/map.png)",
+      ),
+    );
+    // Absolute & external images kept untouched
+    assert.ok(
+      cleaned.includes("![External Image](https://cdn.example.com/ext.png)"),
+    );
+    assert.ok(cleaned.includes("![Absolute Image](/images/abs.png)"));
+  });
+
+  it("handles null or empty content safely", () => {
+    assert.equal(cleanStory(null, "Title"), "");
+    assert.equal(cleanStory("", "Title"), "");
+  });
+});
+
+describe("mapConcurrent", () => {
+  it("preserves ordering and processes all items within concurrency limit", async () => {
+    const items = [1, 2, 3, 4, 5, 6, 7];
+    const results = await mapConcurrent(items, 3, async (num) => num * 2);
+    assert.deepEqual(results, [2, 4, 6, 8, 10, 12, 14]);
+  });
+});
+
+describe("detectManifestCandidates", () => {
+  it("scans directory and ignores .vitepress and node_modules", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "detect-test-"));
+    const mdPath = path.join(tmpDir, "page.md");
+    await fs.writeFile(
+      mdPath,
+      `<eox-storytelling src="https://cdn.eox.at/test/narratives.json"></eox-storytelling>`,
+    );
+
+    const ignoredDir = path.join(tmpDir, ".vitepress");
+    await fs.mkdir(ignoredDir);
+    await fs.writeFile(
+      path.join(ignoredDir, "config.js"),
+      `const url = "https://cdn.eox.at/ignored/narratives.json";`,
+    );
+
+    const candidates = await detectManifestCandidates(tmpDir);
+    assert.equal(candidates.length, 1);
+    assert.equal(candidates[0].url, "https://cdn.eox.at/test/narratives.json");
+    assert.equal(candidates[0].filePath, mdPath);
+
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+});
+
+describe("routeFromRelativePath", () => {
+  it("converts relative paths to clean route paths", () => {
+    assert.equal(routeFromRelativePath("story.md"), "/story");
+    assert.equal(
+      routeFromRelativePath("showcase/stories.md"),
+      "/showcase/stories",
+    );
+    assert.equal(routeFromRelativePath("story/index.md"), "/story");
+    assert.equal(routeFromRelativePath("index.md"), "/");
+    assert.equal(routeFromRelativePath(""), "/story");
+    assert.equal(routeFromRelativePath(null), "/story");
+    assert.equal(routeFromRelativePath(undefined), "/story");
+  });
+});
+
+describe("resolveStoryRouting", () => {
+  it("detects dynamic routes from VitePress paths and template files", () => {
+    assert.deepEqual(
+      resolveStoryRouting({
+        sourceRelPath: "narratives/[narrative].paths.js",
+      }),
+      {
+        isDynamic: true,
+        routeDir: "narratives",
+        routePath: "/narratives",
+      },
+    );
+
+    assert.deepEqual(
+      resolveStoryRouting({
+        sourceRelPath: "stories/[story].md",
+      }),
+      {
+        isDynamic: true,
+        routeDir: "stories",
+        routePath: "/stories",
+      },
+    );
+
+    assert.deepEqual(
+      resolveStoryRouting({
+        sourceRelPath: "narratives/[narrative].paths.ts",
+      }),
+      {
+        isDynamic: true,
+        routeDir: "narratives",
+        routePath: "/narratives",
+      },
+    );
+
+    assert.deepEqual(
+      resolveStoryRouting({
+        sourceRelPath: "stories/[story].paths.mjs",
+      }),
+      {
+        isDynamic: true,
+        routeDir: "stories",
+        routePath: "/stories",
+      },
+    );
+
+    assert.deepEqual(
+      resolveStoryRouting({
+        sourceRelPath: "[narrative].paths.js",
+      }),
+      {
+        isDynamic: true,
+        routeDir: "",
+        routePath: "/",
+      },
+    );
+  });
+
+  it("handles static routes from normal markdown files", () => {
+    assert.deepEqual(
+      resolveStoryRouting({
+        sourceRelPath: "stories.md",
+      }),
+      {
+        isDynamic: false,
+        routeDir: "stories",
+        routePath: "/stories",
+      },
+    );
+
+    assert.deepEqual(
+      resolveStoryRouting({
+        sourceRelPath: "showcase/index.md",
+      }),
+      {
+        isDynamic: false,
+        routeDir: "showcase",
+        routePath: "/showcase",
+      },
+    );
+  });
+
+  it("respects configuredPath overrides for both dynamic and static routes", () => {
+    assert.deepEqual(
+      resolveStoryRouting({
+        configuredPath: "narratives/[narrative]",
+      }),
+      {
+        isDynamic: true,
+        routeDir: "narratives",
+        routePath: "/narratives",
+      },
+    );
+
+    assert.deepEqual(
+      resolveStoryRouting({
+        configuredPath: "narratives/[narrative].md",
+      }),
+      {
+        isDynamic: true,
+        routeDir: "narratives",
+        routePath: "/narratives",
+      },
+    );
+
+    assert.deepEqual(
+      resolveStoryRouting({
+        configuredPath: "/custom-stories.md",
+      }),
+      {
+        isDynamic: false,
+        routeDir: "custom-stories",
+        routePath: "/custom-stories",
+      },
+    );
+
+    assert.deepEqual(
+      resolveStoryRouting({
+        configuredPath: "stories/index.md",
+      }),
+      {
+        isDynamic: false,
+        routeDir: "stories",
+        routePath: "/stories",
+      },
+    );
+  });
+
+  it("falls back to default /story route when no source or config provided", () => {
+    assert.deepEqual(resolveStoryRouting(), {
+      isDynamic: false,
+      routeDir: "story",
+      routePath: "/story",
+    });
+  });
+});
+
+describe("buildStoryUrl", () => {
+  it("constructs url with domain, base, storyPath, and storyId", () => {
+    assert.equal(
+      buildStoryUrl({
+        domain: "https://hub.eox.at",
+        base: "/portal/",
+        storyPath: "/story",
+        storyId: "clean-energy",
+      }),
+      "https://hub.eox.at/portal/story?id=clean-energy",
+    );
+  });
+
+  it("constructs dynamic route URLs for markdown docs and html pages", () => {
+    assert.equal(
+      buildStoryUrl({
+        domain: "https://gtif-austria.info",
+        base: "/",
+        routeDir: "narratives",
+        storyId: "air-heating-potential",
+        isDynamic: true,
+        extension: ".md",
+      }),
+      "https://gtif-austria.info/narratives/air-heating-potential.md",
+    );
+
+    assert.equal(
+      buildStoryUrl({
+        domain: "https://gtif-austria.info",
+        base: "/portal",
+        routeDir: "narratives",
+        storyId: "air-heating-potential",
+        isDynamic: true,
+        extension: "",
+      }),
+      "https://gtif-austria.info/portal/narratives/air-heating-potential",
+    );
+  });
+
+  it("handles empty domain and root base", () => {
+    assert.equal(
+      buildStoryUrl({
+        domain: null,
+        base: "/",
+        storyPath: "showcase/stories",
+        storyId: "wildfire",
+      }),
+      "/showcase/stories?id=wildfire",
+    );
+  });
+
+  it("handles base without slashes and no storyId", () => {
+    assert.equal(
+      buildStoryUrl({
+        domain: "https://example.com",
+        base: "subpath",
+        storyPath: "stories",
+      }),
+      "https://example.com/subpath/stories",
+    );
+  });
+});
+
+describe("resolveAndFetchManifest", () => {
+  it("resolves tier 1 explicit URL with highest precedence", async (t) => {
+    const mockManifest = [{ title: "Story 1", file: "story1.md" }];
+    t.mock.method(globalThis, "fetch", async (url) => ({
+      ok: true,
+      json: async () => mockManifest,
+    }));
+
+    const res = await resolveAndFetchManifest({
+      explicitUrl: "https://example.com/explicit/narratives.json",
+      brandStories: "https://example.com/brand/narratives.json",
+      srcDir: "/tmp",
+    });
+
+    assert.ok(res);
+    assert.equal(
+      res.manifestUrl,
+      "https://example.com/explicit/narratives.json",
+    );
+    assert.deepEqual(res.manifest, mockManifest);
+    assert.equal(res.sourceMarkdownPath, null);
+  });
+
+  it("resolves tier 2 brandStories when explicitUrl is absent", async (t) => {
+    const mockManifest = [{ title: "Story 2", file: "story2.md" }];
+    t.mock.method(globalThis, "fetch", async (url) => ({
+      ok: true,
+      json: async () => mockManifest,
+    }));
+
+    const res = await resolveAndFetchManifest({
+      explicitUrl: null,
+      brandStories: "https://example.com/brand/narratives.json",
+      srcDir: "/tmp",
+    });
+
+    assert.ok(res);
+    assert.equal(res.manifestUrl, "https://example.com/brand/narratives.json");
+    assert.deepEqual(res.manifest, mockManifest);
+    assert.equal(res.sourceMarkdownPath, null);
+  });
+
+  it("resolves tier 3 source scan when exactly one candidate found", async (t) => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "tier3-test-"));
+    const storyMdPath = path.join(tmpDir, "story.md");
+    await fs.writeFile(
+      storyMdPath,
+      `<eox-storytelling src="https://cdn.eox.at/manifest/narratives.json"></eox-storytelling>`,
+    );
+
+    const mockManifest = [{ title: "Story 3", file: "story3.md" }];
+    t.mock.method(globalThis, "fetch", async (url) => ({
+      ok: true,
+      json: async () => mockManifest,
+    }));
+
+    const res = await resolveAndFetchManifest({
+      explicitUrl: null,
+      brandStories: null,
+      srcDir: tmpDir,
+    });
+
+    assert.ok(res);
+    assert.equal(
+      res.manifestUrl,
+      "https://cdn.eox.at/manifest/narratives.json",
+    );
+    assert.deepEqual(res.manifest, mockManifest);
+    assert.equal(res.sourceMarkdownPath, storyMdPath);
+
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("skips and returns null when multiple candidate URLs are detected in Tier 3", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "multi-cand-test-"));
+    await fs.writeFile(
+      path.join(tmpDir, "p1.md"),
+      `https://cdn.eox.at/first/narratives.json`,
+    );
+    await fs.writeFile(
+      path.join(tmpDir, "p2.md"),
+      `https://cdn.eox.at/second/narratives.json`,
+    );
+
+    const res = await resolveAndFetchManifest({
+      explicitUrl: null,
+      brandStories: null,
+      srcDir: tmpDir,
+    });
+
+    assert.equal(res, null);
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns null gracefully if manifest fetch fails (fail-soft)", async (t) => {
+    t.mock.method(globalThis, "fetch", async () => ({
+      ok: false,
+      status: 404,
+    }));
+
+    const res = await resolveAndFetchManifest({
+      explicitUrl: "https://example.com/missing/narratives.json",
+    });
+
+    assert.equal(res, null);
+  });
+});
+
+describe("story fetching and processing", () => {
+  it("fetchStoryMarkdown returns cleaned markdown on success", async (t) => {
+    t.mock.method(globalThis, "fetch", async () => ({
+      ok: true,
+      text: async () => "# My Title\nBody text",
+    }));
+
+    const body = await fetchStoryMarkdown(
+      "https://example.com/story.md",
+      "My Title",
+      "https://example.com",
+    );
+    assert.equal(body, "Body text");
+  });
+
+  it("fetchStoryMarkdown returns null on HTTP error or timeout", async (t) => {
+    t.mock.method(globalThis, "fetch", async () => ({
+      ok: false,
+      status: 500,
+    }));
+
+    const body = await fetchStoryMarkdown(
+      "https://example.com/story.md",
+      "My Title",
+      "https://example.com",
+    );
+    assert.equal(body, null);
+  });
+
+  it("fetchStory skips invalid entries", async () => {
+    assert.equal(await fetchStory({ entry: null }), null);
+    assert.equal(await fetchStory({ entry: { title: "No file" } }), null);
+    assert.equal(await fetchStory({ entry: { file: "no-title.md" } }), null);
+  });
+
+  it("fetchStory correctly formats relative markdownUrl and storyUrl with domain", async (t) => {
+    t.mock.method(globalThis, "fetch", async () => ({
+      ok: true,
+      text: async () => "Story content",
+    }));
+
+    const story = await fetchStory({
+      entry: {
+        title: "Clean Energy",
+        subtitle: "Solar and wind",
+        file: "./clean-energy.v1.md",
+      },
+      index: 0,
+      manifestBaseUrl: "https://cdn.eox.at/manifest",
+      base: "/portal/",
+      storyPath: "/story",
+      domain: "https://hub.eox.at",
+    });
+
+    assert.ok(story);
+    assert.equal(story.storyId, "clean-energy");
+    assert.equal(
+      story.markdownUrl,
+      "https://cdn.eox.at/manifest/clean-energy.v1.md",
+    );
+    assert.equal(
+      story.storyUrl,
+      "https://hub.eox.at/portal/story?id=clean-energy",
+    );
+    assert.equal(story.cleanedBody, "Story content");
+  });
+
+  it("fetchStory supports dynamic routing with distinct docUrl and storyUrl", async (t) => {
+    t.mock.method(globalThis, "fetch", async () => ({
+      ok: true,
+      text: async () => "Story content",
+    }));
+
+    const story = await fetchStory({
+      entry: {
+        title: "Air Heating Potential",
+        file: "./air-heating.md",
+      },
+      index: 0,
+      manifestBaseUrl: "https://gtif-austria.info/data",
+      base: "/",
+      routing: {
+        isDynamic: true,
+        routeDir: "narratives",
+        routePath: "/narratives",
+      },
+      domain: "https://gtif-austria.info",
+    });
+
+    assert.ok(story);
+    assert.equal(story.storyId, "air-heating");
+    assert.equal(
+      story.docUrl,
+      "https://gtif-austria.info/narratives/air-heating.md",
+    );
+    assert.equal(
+      story.storyUrl,
+      "https://gtif-austria.info/narratives/air-heating",
+    );
+  });
+
+  it("fetchStory falls back to markdownUrl for docUrl when fetch fails", async (t) => {
+    t.mock.method(globalThis, "fetch", async () => ({
+      ok: false,
+      status: 404,
+    }));
+
+    const story = await fetchStory({
+      entry: {
+        title: "Air Heating",
+        file: "./air-heating.md",
+      },
+      index: 0,
+      manifestBaseUrl: "https://gtif-austria.info/data",
+      base: "/",
+      routing: {
+        isDynamic: true,
+        routeDir: "narratives",
+        routePath: "/narratives",
+      },
+      domain: "https://gtif-austria.info",
+    });
+
+    assert.ok(story);
+    assert.equal(story.cleanedBody, null);
+    assert.equal(story.docUrl, story.markdownUrl);
+  });
+
+  it("fetchStory falls back to markdownUrl when body is empty string", async (t) => {
+    t.mock.method(globalThis, "fetch", async () => ({
+      ok: true,
+      text: async () => "",
+    }));
+
+    const story = await fetchStory({
+      entry: {
+        title: "Empty Title",
+        file: "./empty.md",
+      },
+      index: 0,
+      manifestBaseUrl: "https://gtif-austria.info/data",
+      base: "/",
+      routing: {
+        isDynamic: true,
+        routeDir: "narratives",
+        routePath: "/narratives",
+      },
+      domain: "https://gtif-austria.info",
+    });
+
+    assert.ok(story);
+    assert.equal(story.cleanedBody, "");
+    assert.equal(story.docUrl, story.markdownUrl);
+  });
+
+  it("fetchStories filters invalid entries and processes list", async (t) => {
+    t.mock.method(globalThis, "fetch", async () => ({
+      ok: true,
+      text: async () => "Content",
+    }));
+
+    const manifest = [
+      { title: "Story A", file: "a.md" },
+      { invalid: true },
+      { title: "Story B", file: "b.md" },
+    ];
+
+    const results = await fetchStories({
+      manifest,
+      manifestBaseUrl: "https://cdn.example.com",
+      base: "/",
+      storyPath: "/story",
+      domain: null,
+      concurrency: 2,
+    });
+
+    assert.equal(results.length, 2);
+    assert.equal(results[0].title, "Story A");
+    assert.equal(results[1].title, "Story B");
+  });
+});
+
+describe("appending functions", () => {
+  it("appendToLlmsTxt creates or appends heading and stories index", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "llms-test-"));
+    const llmsTxt = path.join(tmpDir, "llms.txt");
+    await fs.writeFile(llmsTxt, "# Main Docs\n\n- [Page 1](/page1)\n");
+
+    const stories = [
+      {
+        title: "Test Story",
+        subtitle: "A story for testing",
+        markdownUrl: "https://cdn.example.com/story.md",
+        storyUrl: "https://example.com/story?id=test",
+      },
+    ];
+
+    await appendToLlmsTxt({ outDir: tmpDir, heading: "Stories", stories });
+
+    const content = await fs.readFile(llmsTxt, "utf8");
+    assert.ok(content.includes("## Stories"));
+    assert.ok(
+      content.includes(
+        "- [Test Story](https://cdn.example.com/story.md): A story for testing. Story page: https://example.com/story?id=test",
+      ),
+    );
+
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("appendToLlmsTxt avoids substring deduplication false-positives", async () => {
+    const tmpDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), "llms-prefix-test-"),
+    );
+    const llmsTxt = path.join(tmpDir, "llms.txt");
+    await fs.writeFile(
+      llmsTxt,
+      "# Main Docs\n\n## Stories from our Partners\n\n- [Partner Story](/partner)\n",
+    );
+
+    const stories = [
+      {
+        title: "Test Story",
+        markdownUrl: "https://cdn.example.com/story.md",
+        storyUrl: "https://example.com/story?id=test",
+      },
+    ];
+
+    await appendToLlmsTxt({ outDir: tmpDir, heading: "Stories", stories });
+
+    const content = await fs.readFile(llmsTxt, "utf8");
+    const matches = content.match(/## Stories\b/g);
+    assert.equal(matches.length, 2);
+
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("appendToLlmsFullTxt appends full cleaned content", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "llms-full-test-"));
+    const llmsFull = path.join(tmpDir, "llms-full.txt");
+    await fs.writeFile(llmsFull, "# Full Documentation\n");
+
+    const stories = [
+      {
+        title: "Full Story",
+        markdownUrl: "https://cdn.example.com/full.md",
+        storyUrl: "https://example.com/story?id=full",
+        cleanedBody: "### Section 1\nClean body content",
+      },
+    ];
+
+    await appendToLlmsFullTxt({ outDir: tmpDir, heading: "Stories", stories });
+
+    const content = await fs.readFile(llmsFull, "utf8");
+    assert.ok(content.includes("# Stories"));
+    assert.ok(content.includes("## Full Story"));
+    assert.ok(content.includes("Source: https://cdn.example.com/full.md"));
+    assert.ok(content.includes("Clean body content"));
+
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("appendToStoryRoutePage appends index to target story markdown page in outDir", async () => {
+    const srcDir = await fs.mkdtemp(path.join(os.tmpdir(), "src-test-"));
+    const outDir = await fs.mkdtemp(path.join(os.tmpdir(), "out-test-"));
+
+    const sourceMarkdownPath = path.join(srcDir, "story.md");
+    await fs.writeFile(sourceMarkdownPath, "# Story Page\n");
+
+    const targetStoryPath = path.join(outDir, "story.md");
+    await fs.writeFile(targetStoryPath, "# Story Page Output\n");
+
+    const stories = [
+      {
+        title: "Story One",
+        subtitle: "Subtitle One",
+        markdownUrl: "https://cdn.example.com/1.md",
+        storyUrl: "/story?id=1",
+      },
+    ];
+
+    await appendToStoryRoutePage({
+      outDir,
+      heading: "Stories",
+      stories,
+      sourceMarkdownPath,
+      srcDir,
+    });
+
+    const targetContent = await fs.readFile(targetStoryPath, "utf8");
+    assert.ok(targetContent.includes("## Stories"));
+    assert.ok(
+      targetContent.includes(
+        "- [Story One](https://cdn.example.com/1.md) — Subtitle One. [View story](/story?id=1)",
+      ),
+    );
+
+    await fs.rm(srcDir, { recursive: true, force: true });
+    await fs.rm(outDir, { recursive: true, force: true });
+  });
+
+  it("appendToStoryRoutePage supports dynamic routing targeting matching route markdown page", async () => {
+    const outDir = await fs.mkdtemp(path.join(os.tmpdir(), "dyn-route-test-"));
+    const targetPath = path.join(outDir, "narratives.md");
+    await fs.writeFile(targetPath, "# Narratives Gallery\n");
+
+    const stories = [
+      {
+        title: "Dynamic Story",
+        subtitle: "Dynamic Subtitle",
+        markdownUrl: "https://cdn.example.com/dyn.md",
+        docUrl: "https://example.com/narratives/dyn.md",
+        storyUrl: "https://example.com/narratives/dyn",
+        cleanedBody: "A dynamic story body",
+      },
+    ];
+
+    await appendToStoryRoutePage({
+      outDir,
+      heading: "Available Narratives",
+      stories,
+      routing: {
+        isDynamic: true,
+        routeDir: "narratives",
+        routePath: "/narratives",
+      },
+    });
+
+    const content = await fs.readFile(targetPath, "utf8");
+    assert.ok(content.includes("## Available Narratives"));
+    assert.ok(
+      content.includes(
+        "- [Dynamic Story](https://example.com/narratives/dyn.md) — Dynamic Subtitle. [View story](https://example.com/narratives/dyn)",
+      ),
+    );
+
+    await fs.rm(outDir, { recursive: true, force: true });
+  });
+
+  it("appendToStoryRoutePage does not throw if no candidate files exist", async () => {
+    await appendToStoryRoutePage({
+      outDir: "/nonexistent-dir",
+      heading: "Stories",
+      stories: [],
+    });
+  });
+});
+
+describe("writeIndividualStoryFiles", () => {
+  it("writes individual story markdown files in the routeDir output directory", async () => {
+    const outDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), "individual-stories-"),
+    );
+    const stories = [
+      {
+        storyId: "austrian-air-heating",
+        title: "Austrian Air Heating Potential",
+        cleanedBody: "Cleaned story content for LLMs.",
+      },
+      {
+        storyId: "solar-rooftops",
+        title: "Solar Rooftops",
+        cleanedBody: "Solar energy potential breakdown.",
+      },
+    ];
+
+    await writeIndividualStoryFiles({
+      outDir,
+      routeDir: "narratives",
+      stories,
+    });
+
+    const story1Path = path.join(
+      outDir,
+      "narratives",
+      "austrian-air-heating.md",
+    );
+    const story2Path = path.join(outDir, "narratives", "solar-rooftops.md");
+
+    const story1Content = await fs.readFile(story1Path, "utf8");
+    assert.ok(story1Content.includes("# Austrian Air Heating Potential"));
+    assert.ok(story1Content.includes("Cleaned story content for LLMs."));
+
+    const story2Content = await fs.readFile(story2Path, "utf8");
+    assert.ok(story2Content.includes("# Solar Rooftops"));
+    assert.ok(story2Content.includes("Solar energy potential breakdown."));
+
+    await fs.rm(outDir, { recursive: true, force: true });
+  });
+
+  it("handles empty stories array gracefully without error", async () => {
+    const outDir = await fs.mkdtemp(path.join(os.tmpdir(), "empty-stories-"));
+    await writeIndividualStoryFiles({
+      outDir,
+      routeDir: "narratives",
+      stories: [],
+    });
+    await fs.rm(outDir, { recursive: true, force: true });
+  });
+
+  it("prevents path traversal outside outDir", async () => {
+    const outDir = await fs.mkdtemp(path.join(os.tmpdir(), "traversal-safe-"));
+    const outsideFile = path.resolve(outDir, "../escaped-story.md");
+
+    await writeIndividualStoryFiles({
+      outDir,
+      routeDir: "../",
+      stories: [
+        {
+          storyId: "escaped-story",
+          title: "Escaped Story",
+          cleanedBody: "Malicious content",
+        },
+      ],
+    });
+
+    let exists = true;
+    try {
+      await fs.access(outsideFile);
+    } catch {
+      exists = false;
+    }
+    assert.equal(exists, false);
+
+    await fs.rm(outDir, { recursive: true, force: true });
+  });
+});