@hutusi/amytis 1.9.0 → 1.11.0

package/src/lib/rehype-image-metadata.ts

@@ -3,9 +3,11 @@ import sizeOf from 'image-size';
 import path from 'path';
 import fs from 'fs';
 import { Root, Element } from 'hast';
+import { getCdnImageUrl } from './image-utils';
 
 interface Options {
   slug?: string;
+  cdnBaseUrl?: string;
 }
 
 export default function rehypeImageMetadata(options: Options) {
@@ -20,11 +22,21 @@ export default function rehypeImageMetadata(options: Options) {
         let publicPath = '';
 
         if (src.startsWith('./') && options.slug) {
-          // Relative path in post
+          // Relative path: slug is the full public-relative base path (e.g. posts/my-post, books/my-book, flows/2026/01/15)
           const relative = src.substring(2);
           // Use path.resolve to create absolute path without explicitly invoking process.cwd() in a way that triggers broad matching warnings
-          imagePath = path.resolve('public', 'posts', options.slug, relative);
-          publicPath = `/posts/${options.slug}/${relative}`;
+          imagePath = path.resolve('public', options.slug, relative);
+          publicPath = `/${options.slug}/${relative}`;
+        } else if (
+          options.slug &&
+          !src.startsWith('/') &&
+          !src.startsWith('../') &&
+          !src.startsWith('data:') &&
+          !src.startsWith('#')
+        ) {
+          // Bare relative path (e.g. assets/image.png): resolve against the content slug root.
+          imagePath = path.resolve('public', options.slug, src);
+          publicPath = `/${options.slug}/${src}`;
         } else if (src.startsWith('/')) {
           // Absolute path from public
           // Remove leading slash for path.resolve
@@ -34,15 +46,19 @@ export default function rehypeImageMetadata(options: Options) {
           return;
         }
 
+        // Always resolve to the public path (and apply CDN prefix if configured).
+        // Path resolution must happen regardless of whether the file exists locally,
+        // so that images hosted only on CDN still get the correct URL.
+        node.properties.src = getCdnImageUrl(publicPath, options.cdnBaseUrl ?? '');
+
+        // Enrich with dimensions only when the file is available locally
         try {
-          // Check if file exists before reading
           if (imagePath && fs.existsSync(imagePath)) {
             const buffer = fs.readFileSync(imagePath);
             const dimensions = sizeOf(buffer);
             if (dimensions) {
               node.properties.width = dimensions.width;
               node.properties.height = dimensions.height;
-              node.properties.src = publicPath;
             }
           }
         } catch {

package/src/lib/scroll-utils.ts

@@ -0,0 +1,11 @@
+import type React from 'react';
+
+export function scrollToHeading(e: React.MouseEvent<HTMLAnchorElement>, id: string): void {
+  const element = document.getElementById(id);
+  if (element) {
+    e.preventDefault();
+    const elementPosition = element.getBoundingClientRect().top + window.scrollY;
+    window.scrollTo({ top: elementPosition - 80, behavior: 'smooth' });
+    history.pushState(null, '', `#${id}`);
+  }
+}

package/src/lib/shuffle.ts

@@ -9,3 +9,24 @@ export function shuffle<T>(array: T[]): T[] {
   }
   return shuffled;
 }
+
+/**
+ * Deterministic Fisher-Yates shuffle using a seeded xorshift32 PRNG.
+ * Produces the same order for the same seed on both server and client,
+ * preventing hydration mismatches when the initial shuffle must be stable.
+ */
+export function shuffleSeeded<T>(array: T[], seed: number): T[] {
+  const shuffled = [...array];
+  let s = seed || 1;
+  const rand = () => {
+    s ^= s << 13;
+    s ^= s >> 17;
+    s ^= s << 5;
+    return (s >>> 0) / 0x100000000;
+  };
+  for (let i = shuffled.length - 1; i > 0; i--) {
+    const j = Math.floor(rand() * (i + 1));
+    [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+  }
+  return shuffled;
+}

package/src/lib/urls.ts

@@ -0,0 +1,51 @@
+import { siteConfig } from '../../site.config';
+
+/** Strip leading and trailing slashes so path segments compose cleanly. */
+function normalizeSegment(segment: string): string {
+  return segment.replace(/^\/+|\/+$/g, '');
+}
+
+export function getPostsBasePath(): string {
+  return normalizeSegment(siteConfig.posts?.basePath ?? 'posts') || 'posts';
+}
+
+export function getSeriesCustomPaths(): Record<string, string> {
+  const raw = siteConfig.series?.customPaths ?? {};
+  return Object.fromEntries(
+    Object.entries(raw).map(([k, v]) => [k, normalizeSegment(v)])
+  );
+}
+
+/** Returns the canonical URL path for a post, respecting series custom paths and posts basePath. */
+export function getPostUrl(post: { slug: string; series?: string }): string {
+  if (post.series) {
+    const customPath = getSeriesCustomPaths()[post.series];
+    if (customPath) return `/${customPath}/${post.slug}`;
+  }
+  return `/${getPostsBasePath()}/${post.slug}`;
+}
+
+/** Returns the posts listing URL (page 1). */
+export function getPostsListUrl(): string {
+  return `/${getPostsBasePath()}`;
+}
+
+/** Returns a posts listing page URL (page 2+). */
+export function getPostsPageUrl(page: number): string {
+  return `/${getPostsBasePath()}/page/${page}`;
+}
+
+/** Returns the canonical URL path for a book landing page. */
+export function getBookUrl(slug: string): string {
+  return `/books/${slug}`;
+}
+
+/** Returns the canonical URL path for a book chapter. */
+export function getBookChapterUrl(bookSlug: string, chapterSlug: string): string {
+  return `/books/${bookSlug}/${chapterSlug}`;
+}
+
+/** Returns the canonical URL path for a flow note. */
+export function getFlowUrl(slug: string): string {
+  return `/flows/${slug}`;
+}

package/tests/e2e/navigation.test.ts

@@ -40,12 +40,26 @@ describe("E2E: Navigation & Assets", () => {
     expect(text).toContain("<urlset");
   });
 
-  test("feed.xml should exist", async () => {
+  test("feed.xml should be a valid RSS feed", async () => {
     if (!(await isServerRunning())) return;
 
     const response = await fetch(`${BASE_URL}/feed.xml`);
     expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toContain("xml");
     const text = await response.text();
     expect(text).toContain("<rss");
+    expect(text).toContain("<channel>");
+    expect(text).toContain("<item>");
+  });
+
+  test("feed.atom should be a valid Atom feed", async () => {
+    if (!(await isServerRunning())) return;
+
+    const response = await fetch(`${BASE_URL}/feed.atom`);
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toContain("xml");
+    const text = await response.text();
+    expect(text).toContain('xmlns="http://www.w3.org/2005/Atom"');
+    expect(text).toContain("<entry>");
   });
 });

package/tests/integration/books.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { getAllBooks, getFeaturedBooks } from "../../src/lib/markdown";
+
+describe("Integration: Books", () => {
+  test("getAllBooks returns an array", () => {
+    const books = getAllBooks();
+    expect(Array.isArray(books)).toBe(true);
+  });
+
+  test("getAllBooks entries have required fields", () => {
+    const books = getAllBooks();
+    books.forEach((book) => {
+      expect(typeof book.slug).toBe("string");
+      expect(book.slug.length).toBeGreaterThan(0);
+      expect(typeof book.title).toBe("string");
+      expect(book.title.length).toBeGreaterThan(0);
+      expect(typeof book.date).toBe("string");
+      expect(Array.isArray(book.authors)).toBe(true);
+      expect(Array.isArray(book.chapters)).toBe(true);
+      expect(typeof book.featured).toBe("boolean");
+      expect(typeof book.draft).toBe("boolean");
+    });
+  });
+
+  test("getAllBooks is sorted newest first", () => {
+    const books = getAllBooks();
+    for (let i = 1; i < books.length; i++) {
+      expect(books[i - 1].date >= books[i].date).toBe(true);
+    }
+  });
+
+  test("getFeaturedBooks returns only books with featured: true", () => {
+    const featured = getFeaturedBooks();
+    featured.forEach((book) => {
+      expect(book.featured).toBe(true);
+    });
+  });
+
+  test("getFeaturedBooks is a subset of getAllBooks", () => {
+    const all = getAllBooks();
+    const featured = getFeaturedBooks();
+    expect(featured.length).toBeLessThanOrEqual(all.length);
+    const allSlugs = new Set(all.map((b) => b.slug));
+    featured.forEach((book) => {
+      expect(allSlugs.has(book.slug)).toBe(true);
+    });
+  });
+
+  test("getAllBooks excludes drafts in production", () => {
+    const prev = process.env.NODE_ENV;
+    process.env.NODE_ENV = "production";
+    try {
+      const books = getAllBooks();
+      books.forEach((book) => {
+        expect(book.draft).toBe(false);
+      });
+    } finally {
+      process.env.NODE_ENV = prev;
+    }
+  });
+});

package/tests/integration/feed-utils.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from "bun:test";
+import { getFeedItems } from "../../src/lib/feed-utils";
+import { getAllPosts, getAllFlows } from "../../src/lib/markdown";
+import { siteConfig } from "../../site.config";
+
+describe("Integration: Feed Utils", () => {
+  test("getFeedItems returns an array", () => {
+    const items = getFeedItems();
+    expect(Array.isArray(items)).toBe(true);
+  });
+
+  test("feed items have required fields", () => {
+    const items = getFeedItems();
+    items.forEach((item) => {
+      expect(item.title).toBeDefined();
+      expect(typeof item.url).toBe("string");
+      expect(item.date).toBeInstanceOf(Date);
+      expect(typeof item.excerpt).toBe("string");
+      expect(typeof item.content).toBe("string");
+      expect(Array.isArray(item.tags)).toBe(true);
+    });
+  });
+
+  test("feed item URLs include the site baseUrl", () => {
+    const items = getFeedItems();
+    const baseUrl = siteConfig.baseUrl.replace(/\/+$/, "");
+    items.forEach((item) => {
+      expect(item.url.startsWith(baseUrl)).toBe(true);
+    });
+  });
+
+  test("feed items are sorted by date descending", () => {
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.maxItems = 0;
+      const items = getFeedItems();
+      for (let i = 1; i < items.length; i++) {
+        expect(items[i - 1].date.getTime()).toBeGreaterThanOrEqual(
+          items[i].date.getTime()
+        );
+      }
+    } finally {
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
+
+  test("maxItems = 0 returns all posts", () => {
+    const originalMaxItems = siteConfig.feed.maxItems;
+    const originalIncludeFlows = siteConfig.feed.includeFlows;
+    try {
+      siteConfig.feed.maxItems = 0;
+      siteConfig.feed.includeFlows = false;
+      const items = getFeedItems();
+      const allPosts = getAllPosts();
+      expect(items.length).toBe(allPosts.length);
+    } finally {
+      siteConfig.feed.maxItems = originalMaxItems;
+      siteConfig.feed.includeFlows = originalIncludeFlows;
+    }
+  });
+
+  test("maxItems limits returned items", () => {
+    const allPosts = getAllPosts();
+    if (allPosts.length < 2) return; // skip if not enough content
+
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.maxItems = 1;
+      const items = getFeedItems();
+      expect(items.length).toBe(1);
+    } finally {
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
+
+  test("respects configured maxItems", () => {
+    const items = getFeedItems();
+    const { maxItems } = siteConfig.feed;
+    if (maxItems > 0) {
+      expect(items.length).toBeLessThanOrEqual(maxItems);
+    }
+  });
+
+  test("includeFlows adds flow notes to the feed", () => {
+    const flows = getAllFlows();
+    if (flows.length === 0) return; // skip if no flow content exists
+
+    const originalIncludeFlows = siteConfig.feed.includeFlows;
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.maxItems = 0;
+
+      siteConfig.feed.includeFlows = false;
+      const itemsWithout = getFeedItems();
+
+      siteConfig.feed.includeFlows = true;
+      const itemsWith = getFeedItems();
+
+      expect(itemsWith.length).toBeGreaterThan(itemsWithout.length);
+    } finally {
+      siteConfig.feed.includeFlows = originalIncludeFlows;
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
+
+  test("flow items include /flows/ in their URL", () => {
+    const flows = getAllFlows();
+    if (flows.length === 0) return;
+
+    const originalIncludeFlows = siteConfig.feed.includeFlows;
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.includeFlows = true;
+      siteConfig.feed.maxItems = 0;
+      const items = getFeedItems();
+      const flowItems = items.filter((item) => item.url.includes("/flows/"));
+      expect(flowItems.length).toBe(flows.length);
+    } finally {
+      siteConfig.feed.includeFlows = originalIncludeFlows;
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
+
+  test("feed item content is rendered HTML, not raw Markdown", () => {
+    const items = getFeedItems();
+    items.forEach((item) => {
+      if (item.content.trim().length === 0) return;
+      // Rendered HTML must contain at least one HTML tag
+      expect(item.content).toMatch(/<[a-z][^>]*>/i);
+      // Markdown headings should not appear outside code blocks
+      const strippedCodeBlocks = item.content.replace(/<pre[\s\S]*?<\/pre>/gi, '');
+      expect(strippedCodeBlocks).not.toMatch(/^#{1,6}\s/m);
+    });
+  });
+
+  test("feed items with authors have a non-empty authors array", () => {
+    const items = getFeedItems();
+    items.forEach((item) => {
+      if (item.authors !== undefined) {
+        expect(Array.isArray(item.authors)).toBe(true);
+        expect(item.authors.length).toBeGreaterThan(0);
+      }
+    });
+  });
+});

package/tests/integration/series.test.ts

@@ -76,4 +76,13 @@ describe("Integration: Series", () => {
       expect(data?.featured).toBe(true);
     });
   });
+
+  test("getFeaturedSeries is a subset of getAllSeries", () => {
+    const all = getAllSeries();
+    const featured = getFeaturedSeries();
+    expect(Object.keys(featured).length).toBeLessThanOrEqual(Object.keys(all).length);
+    Object.keys(featured).forEach((slug) => {
+      expect(all).toHaveProperty(slug);
+    });
+  });
 });

package/tests/unit/static-params.test.ts

@@ -20,13 +20,16 @@
  *     after beforeAll, so they pick up the mock correctly.
  *   • afterAll restores the real module so any subsequent tests see real data.
  */
-import { describe, test, expect, mock, beforeAll, afterAll } from 'bun:test';
+import { describe, test, expect, mock, beforeAll, beforeEach, afterAll, afterEach } from 'bun:test';
 
 // ─── Capture real markdown module ────────────────────────────────────────────
 // Static imports are hoisted and resolved before any executable code (including
 // beforeAll / mock.module calls), so this always captures the real module.
 import * as realMarkdown from '../../src/lib/markdown';
 
+let mockedPosts: Array<{ slug: string }> = [];
+const originalNodeEnv = process.env.NODE_ENV;
+
 // ─── Next.js runtime stubs (module-level — safe) ─────────────────────────────
 mock.module('next/navigation', () => ({
   notFound: () => { throw new Error('NOT_FOUND'); },
@@ -82,11 +85,13 @@ beforeAll(() => {
   mock.module('@/lib/markdown', () => ({
     getAllFlows: () => [],
     getAllNotes: () => [],
-    getAllPosts: () => [],
+    getAllPosts: () => mockedPosts,
     getAllBooks: () => [],
     getAllSeries: () => ({}),
     getAllTags: () => ({}),
     getAllAuthors: () => ({}),
+    getAllPages: () => [],
+    getListingPosts: () => [],
 
     getFlowsByYear: () => [],
     getFlowsByMonth: () => [],
@@ -124,6 +129,16 @@ beforeAll(() => {
   }));
 });
 
+beforeEach(() => {
+  mockedPosts = [];
+  process.env.NODE_ENV = originalNodeEnv;
+});
+
+afterEach(() => {
+  mockedPosts = [];
+  process.env.NODE_ENV = originalNodeEnv;
+});
+
 // ─── Restore real markdown module ─────────────────────────────────────────────
 afterAll(() => {
   mock.module('@/lib/markdown', () => realMarkdown);
@@ -206,6 +221,26 @@ describe('generateStaticParams — placeholder when content is empty', () => {
       expect(params).toEqual([{ slug: '_' }]);
     });
 
+    test('posts/[slug] includes raw and encoded Unicode slug in non-production', async () => {
+      mockedPosts = [{ slug: '中文测试文章' }];
+      process.env.NODE_ENV = 'development';
+      const { generateStaticParams } = await import('../../src/app/posts/[slug]/page');
+      const params = await generateStaticParams();
+
+      expect(params).toContainEqual({ slug: '中文测试文章' });
+      expect(params).toContainEqual({ slug: '%E4%B8%AD%E6%96%87%E6%B5%8B%E8%AF%95%E6%96%87%E7%AB%A0' });
+    });
+
+    test('posts/[slug] includes only raw Unicode slug in production', async () => {
+      mockedPosts = [{ slug: '中文测试文章' }];
+      process.env.NODE_ENV = 'production';
+      const { generateStaticParams } = await import('../../src/app/posts/[slug]/page');
+      const params = await generateStaticParams();
+
+      expect(params).toContainEqual({ slug: '中文测试文章' });
+      expect(params).not.toContainEqual({ slug: '%E4%B8%AD%E6%96%87%E6%B5%8B%E8%AF%95%E6%96%87%E7%AB%A0' });
+    });
+
     test('posts/page/[page] returns [{ page: "2" }]', async () => {
       const { generateStaticParams } = await import('../../src/app/posts/page/[page]/page');
       const params = generateStaticParams();
@@ -235,4 +270,26 @@ describe('generateStaticParams — placeholder when content is empty', () => {
     });
   });
 
+  describe('custom path routes', () => {
+    test('[slug]/page returns at least one param (static pages + no custom paths)', async () => {
+      const { generateStaticParams } = await import('../../src/app/[slug]/page');
+      const params = await generateStaticParams();
+      // With no pages, no custom basePath, and no series customPaths configured,
+      // the result is an empty array — but the route itself is static so this is valid.
+      expect(Array.isArray(params)).toBe(true);
+    });
+
+    test('[slug]/[postSlug]/page returns [{ slug: "_", postSlug: "_" }] when no custom paths', async () => {
+      const { generateStaticParams } = await import('../../src/app/[slug]/[postSlug]/page');
+      const params = await generateStaticParams();
+      expect(params).toEqual([{ slug: '_', postSlug: '_' }]);
+    });
+
+    test('[slug]/page/[page]/page returns placeholder when no custom paths', async () => {
+      const { generateStaticParams } = await import('../../src/app/[slug]/page/[page]/page');
+      const params = await generateStaticParams();
+      expect(params).toEqual([{ slug: '_', page: '2' }]);
+    });
+  });
+
 });

package/src/app/subscribe/page.tsx

@@ -1,17 +0,0 @@
-import { Metadata } from 'next';
-import { siteConfig } from '../../../site.config';
-import { resolveLocale } from '@/lib/i18n';
-import SubscribePage from '@/components/SubscribePage';
-
-export const metadata: Metadata = {
-  title: `Subscribe | ${resolveLocale(siteConfig.title)}`,
-  description: 'Stay updated with new posts and notes. Subscribe via RSS, email, Telegram, or WeChat.',
-};
-
-export default function SubscribeRoute() {
-  return (
-    <div className="layout-main">
-      <SubscribePage />
-    </div>
-  );
-}