Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

refactor(cli): split blog into api/blog leaf shape (#4479)

Joey56d77afe036c
diff --git a/.changeset/cli-blog-leaves.md b/.changeset/cli-blog-leaves.md
new file mode 100644
index 0000000000..ec2be7d7ab
--- /dev/null
+++ b/.changeset/cli-blog-leaves.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[refactor] CLI: blog reorganized into api/blog leaf shape — list/detail leaves projecting a shared RSS adapter (`_adapter.mjs` owns all network fetch + feed parsing), with `blog.mjs` kept as a dispatcher+barrel so the same `blog` export, the CLI wrapper, api/index.mjs, and the --json/human output stay byte-identical.
+@josephfarina
diff --git a/packages/cli/api/blog/_adapter.mjs b/packages/cli/api/blog/_adapter.mjs
new file mode 100644
index 0000000000..e73e835fc2
--- /dev/null
+++ b/packages/cli/api/blog/_adapter.mjs
@@ -0,0 +1,219 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared adapter for the blog leaves — the ONLY place that touches the
+ * network or parses the RSS feed. Both leaves (blog.list, blog.detail) read the
+ * blog through here: listing parses the feed; reading a post fetches the
+ * plaintext (.txt) alternate the feed advertises for each item. Nothing here
+ * touches the blog's source files — the CLI is just a consumer of the public
+ * feed, so the blog's structure can change freely without touching the CLI.
+ *
+ * @input none (the feed origin is fixed) / a post's plaintext URL
+ * @output parsed feed ({feedUrl, posts}) / a post's plaintext body
+ * @position api — shared adapter for api/blog/{list,detail}; no envelope shaping here
+ */
+
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {SITE_URL, SITE_ORIGIN} from '../../lib/site.mjs';
+
+/** Abort a feed/post fetch that hangs, and cap how much we'll read. */
+const FETCH_TIMEOUT_MS = 15000;
+const MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a blog feed is never larger.
+
+/**
+ * Canonical RSS feed URL. The feed is always the canonical site — there is no
+ * user-supplied URL — so both leaves can hit it directly.
+ */
+export const FEED_URL = new URL('/rss.xml', SITE_URL).toString();
+
+/**
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+async function fetchText(url) {
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+ let res;
+ try {
+ res = await fetch(url, {
+ signal: controller.signal,
+ redirect: 'follow',
+ });
+ } catch (e) {
+ clearTimeout(timer);
+ const reason =
+ e instanceof Error
+ ? e.name === 'AbortError'
+ ? 'timed out'
+ : e.message
+ : String(e);
+ throw new AstryxError(
+ `Could not reach ${url}: ${reason}`,
+ [],
+ ERROR_CODES.ERR_FETCH_FAILED,
+ );
+ }
+ clearTimeout(timer);
+ if (!res.ok) {
+ throw new AstryxError(
+ `Request to ${url} failed with ${res.status}`,
+ [],
+ ERROR_CODES.ERR_FETCH_FAILED,
+ );
+ }
+ const body = await res.text();
+ if (body.length > MAX_BYTES) {
+ throw new AstryxError(
+ `Response from ${url} exceeded ${MAX_BYTES} bytes`,
+ [],
+ ERROR_CODES.ERR_FETCH_FAILED,
+ );
+ }
+ return body;
+}
+
+/**
+ * Defense in depth: a post's plaintext URL comes from feed content. Require it
+ * to live on the canonical origin so even a tampered feed can't redirect the
+ * CLI to another host.
+ * @param {string} target
+ */
+function assertCanonicalOrigin(target) {
+ let targetOrigin;
+ try {
+ targetOrigin = new URL(target).origin;
+ } catch {
+ throw new AstryxError(
+ `Post has an invalid plaintext URL: "${target}"`,
+ [],
+ ERROR_CODES.ERR_FETCH_FAILED,
+ );
+ }
+ if (targetOrigin !== SITE_ORIGIN) {
+ throw new AstryxError(
+ `Refusing to fetch post text from a non-canonical origin (${targetOrigin})`,
+ [],
+ ERROR_CODES.ERR_FETCH_FAILED,
+ );
+ }
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function unescapeXml(value) {
+ return value
+ .replace(/&lt;/g, '<')
+ .replace(/&gt;/g, '>')
+ .replace(/&quot;/g, '"')
+ .replace(/&apos;/g, "'")
+ .replace(/&amp;/g, '&');
+}
+
+/**
+ * @param {string} item
+ * @param {string} name
+ * @returns {string}
+ */
+function tag(item, name) {
+ const m = item.match(new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`));
+ return m ? unescapeXml(m[1].trim()) : '';
+}
+
+/**
+ * @param {string} item
+ * @param {string} name
+ * @returns {string[]}
+ */
+function tagAll(item, name) {
+ /** @type {string[]} */
+ const out = [];
+ const re = new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`, 'g');
+ let m;
+ while ((m = re.exec(item))) out.push(unescapeXml(m[1].trim()));
+ return out;
+}
+
+/**
+ * Extract the plaintext alternate href from an <item>.
+ * @param {string} item
+ * @returns {string | null}
+ */
+function textHref(item) {
+ // Match the atom:link alternate regardless of attribute order/quoting; then
+ // confirm it's the text/plain alternate before trusting the href.
+ const re = /<atom:link\b[^>]*?\/?>/g;
+ let m;
+ while ((m = re.exec(item))) {
+ const el = m[0];
+ if (/rel\s*=\s*["']alternate["']/.test(el) &&
+ /type\s*=\s*["']text\/plain["']/.test(el)) {
+ const href = el.match(/href\s*=\s*["']([^"']+)["']/);
+ if (href) return unescapeXml(href[1]);
+ }
+ }
+ return null;
+}
+
+/**
+ * Derive a slug from a post link (last path segment).
+ * @param {string} link
+ * @returns {string}
+ */
+function slugFromLink(link) {
+ try {
+ const path = new URL(link).pathname.replace(/\/$/, '');
+ return path.slice(path.lastIndexOf('/') + 1);
+ } catch {
+ return link;
+ }
+}
+
+/**
+ * @param {string} xml
+ * @returns {import('../../types/blog').BlogPost[]}
+ */
+function parseFeed(xml) {
+ /** @type {import('../../types/blog').BlogPost[]} */
+ const items = [];
+ const re = /<item>([\s\S]*?)<\/item>/g;
+ let m;
+ while ((m = re.exec(xml))) {
+ const raw = m[1];
+ const link = tag(raw, 'link');
+ items.push({
+ slug: slugFromLink(link),
+ title: tag(raw, 'title'),
+ description: tag(raw, 'description'),
+ date: tag(raw, 'pubDate'),
+ type: tag(raw, 'category'),
+ authors: tagAll(raw, 'author'),
+ link,
+ textUrl: textHref(raw),
+ });
+ }
+ return items;
+}
+
+/**
+ * Fetch the canonical feed and parse it into posts. Shared by both leaves; the
+ * envelope's `feedUrl` lets a caller hit the RSS feed directly.
+ * @returns {Promise<import('../../types/blog').BlogListData>}
+ */
+export async function loadFeed() {
+ const xml = await fetchText(FEED_URL);
+ return {feedUrl: FEED_URL, posts: parseFeed(xml)};
+}
+
+/**
+ * Fetch a post's plaintext (.txt) alternate, refusing any non-canonical origin
+ * so even a tampered feed can't redirect the CLI to another host.
+ * @param {string} textUrl
+ * @returns {Promise<string>}
+ */
+export async function fetchPostText(textUrl) {
+ assertCanonicalOrigin(textUrl);
+ return fetchText(textUrl);
+}
diff --git a/packages/cli/api/blog/blog.mjs b/packages/cli/api/blog/blog.mjs
index d3b1cbf09c..5450e58c10 100644
--- a/packages/cli/api/blog/blog.mjs
+++ b/packages/cli/api/blog/blog.mjs
@@ -1,192 +1,26 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file Programmatic API for the blog command.
+ * @file Programmatic API for the blog command — dispatcher + barrel.
*
* The blog is read the same way any feed reader reads it: over the published
- * RSS feed. Listing parses the feed; reading a post fetches the plaintext
- * (.txt) alternate the feed advertises for each item. Nothing here touches the
- * blog's source files — the CLI is just a consumer of the public feed, so the
- * blog's structure can change freely without touching the CLI.
- */
-
-import {AstryxError} from '../error.mjs';
-import {ERROR_CODES} from '../../lib/error-codes.mjs';
-import {SITE_URL, SITE_ORIGIN} from '../../lib/site.mjs';
-
-/** Abort a feed/post fetch that hangs, and cap how much we'll read. */
-const FETCH_TIMEOUT_MS = 15000;
-const MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a blog feed is never larger.
-
-const FEED_URL = new URL('/rss.xml', SITE_URL).toString();
-
-/**
- * @param {string} url
- * @returns {Promise<string>}
- */
-async function fetchText(url) {
- const controller = new AbortController();
- const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
- let res;
- try {
- res = await fetch(url, {
- signal: controller.signal,
- redirect: 'follow',
- });
- } catch (e) {
- clearTimeout(timer);
- const reason =
- e instanceof Error
- ? e.name === 'AbortError'
- ? 'timed out'
- : e.message
- : String(e);
- throw new AstryxError(
- `Could not reach ${url}: ${reason}`,
- [],
- ERROR_CODES.ERR_FETCH_FAILED,
- );
- }
- clearTimeout(timer);
- if (!res.ok) {
- throw new AstryxError(
- `Request to ${url} failed with ${res.status}`,
- [],
- ERROR_CODES.ERR_FETCH_FAILED,
- );
- }
- const body = await res.text();
- if (body.length > MAX_BYTES) {
- throw new AstryxError(
- `Response from ${url} exceeded ${MAX_BYTES} bytes`,
- [],
- ERROR_CODES.ERR_FETCH_FAILED,
- );
- }
- return body;
-}
-
-/**
- * Defense in depth: a post's plaintext URL comes from feed content. Require it
- * to live on the canonical origin so even a tampered feed can't redirect the
- * CLI to another host.
- * @param {string} target
- */
-function assertCanonicalOrigin(target) {
- let targetOrigin;
- try {
- targetOrigin = new URL(target).origin;
- } catch {
- throw new AstryxError(
- `Post has an invalid plaintext URL: "${target}"`,
- [],
- ERROR_CODES.ERR_FETCH_FAILED,
- );
- }
- if (targetOrigin !== SITE_ORIGIN) {
- throw new AstryxError(
- `Refusing to fetch post text from a non-canonical origin (${targetOrigin})`,
- [],
- ERROR_CODES.ERR_FETCH_FAILED,
- );
- }
-}
-
-/**
- * @param {string} value
- * @returns {string}
- */
-function unescapeXml(value) {
- return value
- .replace(/&lt;/g, '<')
- .replace(/&gt;/g, '>')
- .replace(/&quot;/g, '"')
- .replace(/&apos;/g, "'")
- .replace(/&amp;/g, '&');
-}
-
-/**
- * @param {string} item
- * @param {string} name
- * @returns {string}
- */
-function tag(item, name) {
- const m = item.match(new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`));
- return m ? unescapeXml(m[1].trim()) : '';
-}
-
-/**
- * @param {string} item
- * @param {string} name
- * @returns {string[]}
- */
-function tagAll(item, name) {
- /** @type {string[]} */
- const out = [];
- const re = new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`, 'g');
- let m;
- while ((m = re.exec(item))) out.push(unescapeXml(m[1].trim()));
- return out;
-}
-
-/**
- * Extract the plaintext alternate href from an <item>.
- * @param {string} item
- * @returns {string | null}
- */
-function textHref(item) {
- // Match the atom:link alternate regardless of attribute order/quoting; then
- // confirm it's the text/plain alternate before trusting the href.
- const re = /<atom:link\b[^>]*?\/?>/g;
- let m;
- while ((m = re.exec(item))) {
- const el = m[0];
- if (/rel\s*=\s*["']alternate["']/.test(el) &&
- /type\s*=\s*["']text\/plain["']/.test(el)) {
- const href = el.match(/href\s*=\s*["']([^"']+)["']/);
- if (href) return unescapeXml(href[1]);
- }
- }
- return null;
-}
-
-/**
- * Derive a slug from a post link (last path segment).
- * @param {string} link
- * @returns {string}
+ * RSS feed. `blog()` dispatches to two leaves — list (no slug) and detail
+ * (a slug) — that share one adapter for the network fetch + RSS parse
+ * (./_adapter.mjs). Nothing here touches the blog's source files; the CLI is
+ * just a consumer of the public feed, so the blog's structure can change
+ * freely without touching the CLI.
+ *
+ * The barrel re-exports the leaf functions (`list` / `detail`) so callers can
+ * reach a single leaf directly; `blog` stays exported unchanged so
+ * api/index.mjs and the CLI wrapper need no edits.
+ *
+ * @input optional slug
+ * @output blog.list | blog.detail envelope
+ * @position api — dispatcher over api/blog/{list,detail}; command wrapper in commands/blog.mjs
*/
-function slugFromLink(link) {
- try {
- const path = new URL(link).pathname.replace(/\/$/, '');
- return path.slice(path.lastIndexOf('/') + 1);
- } catch {
- return link;
- }
-}
-/**
- * @param {string} xml
- */
-function parseFeed(xml) {
- const items = [];
- const re = /<item>([\s\S]*?)<\/item>/g;
- let m;
- while ((m = re.exec(xml))) {
- const raw = m[1];
- const link = tag(raw, 'link');
- items.push({
- slug: slugFromLink(link),
- title: tag(raw, 'title'),
- description: tag(raw, 'description'),
- date: tag(raw, 'pubDate'),
- type: tag(raw, 'category'),
- authors: tagAll(raw, 'author'),
- link,
- textUrl: textHref(raw),
- });
- }
- return items;
-}
+import {list} from './list/list.mjs';
+import {detail} from './detail/detail.mjs';
/**
* List posts (from the feed), or read one post (via its .txt alternate).
@@ -197,32 +31,7 @@ function parseFeed(xml) {
* @returns {Promise<import('../../types/blog').BlogListResponse | import('../../types/blog').BlogDetailResponse>}
*/
export async function blog(slug) {
- const xml = await fetchText(FEED_URL);
- const posts = parseFeed(xml);
-
- if (!slug) {
- return {type: 'blog.list', data: {feedUrl: FEED_URL, posts}};
- }
-
- const normalized = slug.toLowerCase();
- const post = posts.find(p => p.slug.toLowerCase() === normalized);
- if (!post) {
- throw new AstryxError(
- `No blog post with slug "${slug}"`,
- posts.map(p => ({name: p.slug, reason: 'available post'})),
- ERROR_CODES.ERR_UNKNOWN_POST,
- );
- }
-
- if (!post.textUrl) {
- throw new AstryxError(
- `Post "${slug}" has no plaintext alternate in the feed`,
- [],
- ERROR_CODES.ERR_FETCH_FAILED,
- );
- }
-
- assertCanonicalOrigin(post.textUrl);
- const text = await fetchText(post.textUrl);
- return {type: 'blog.detail', data: {...post, feedUrl: FEED_URL, text}};
+ return slug ? detail(slug) : list();
}
+
+export {list, detail};
diff --git a/packages/cli/api/blog/detail/detail.mjs b/packages/cli/api/blog/detail/detail.mjs
new file mode 100644
index 0000000000..f88797d51d
--- /dev/null
+++ b/packages/cli/api/blog/detail/detail.mjs
@@ -0,0 +1,48 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file blog.detail leaf — read one post via its plaintext (.txt) alternate.
+ *
+ * A projection over the shared adapter: it loads the parsed feed, selects the
+ * post by slug (case-insensitive), then reads that post's plaintext body. All
+ * network fetch + RSS parsing live in ../_adapter.mjs. The envelope carries
+ * `feedUrl` so a caller can hit the RSS feed directly.
+ *
+ * @input slug (post identifier derived from the feed link)
+ * @output {type:'blog.detail', data:{...post, feedUrl, text}} envelope
+ * @position api — leaf under api/blog; dispatched by ../blog.mjs
+ */
+
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../lib/error-codes.mjs';
+import {loadFeed, fetchPostText} from '../_adapter.mjs';
+
+/**
+ * Read one post identified by slug (case-insensitive) via its .txt alternate.
+ * @param {string} slug
+ * @returns {Promise<import('../../../types/blog').BlogDetailResponse>}
+ */
+export async function detail(slug) {
+ const {feedUrl, posts} = await loadFeed();
+
+ const normalized = slug.toLowerCase();
+ const post = posts.find(p => p.slug.toLowerCase() === normalized);
+ if (!post) {
+ throw new AstryxError(
+ `No blog post with slug "${slug}"`,
+ posts.map(p => ({name: p.slug, reason: 'available post'})),
+ ERROR_CODES.ERR_UNKNOWN_POST,
+ );
+ }
+
+ if (!post.textUrl) {
+ throw new AstryxError(
+ `Post "${slug}" has no plaintext alternate in the feed`,
+ [],
+ ERROR_CODES.ERR_FETCH_FAILED,
+ );
+ }
+
+ const text = await fetchPostText(post.textUrl);
+ return {type: 'blog.detail', data: {...post, feedUrl, text}};
+}
diff --git a/packages/cli/api/blog/detail/detail.test.mjs b/packages/cli/api/blog/detail/detail.test.mjs
new file mode 100644
index 0000000000..eb4529a03a
--- /dev/null
+++ b/packages/cli/api/blog/detail/detail.test.mjs
@@ -0,0 +1,101 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the blog.detail leaf — selects a post by slug from the
+ * canonical feed, then reads its plaintext (.txt) alternate. `fetch` is stubbed
+ * so the test never hits the network. The feed origin is fixed (not
+ * user-configurable), so the URLs are asserted directly.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {detail} from './detail.mjs';
+import {AstryxError} from '../../error.mjs';
+import {SITE_URL} from '../../../lib/site.mjs';
+
+const FEED = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+ <channel>
+ <title>Astryx Blog</title>
+ <link>${SITE_URL}/blog</link>
+ <item>
+ <title>How Astryx works</title>
+ <link>${SITE_URL}/blog/how-astryx-works</link>
+ <description>Under the hood &amp; more</description>
+ <category>engineering</category>
+ <author>cvkxx</author>
+ <pubDate>Mon, 29 Jun 2026 00:00:00 GMT</pubDate>
+ <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/how-astryx-works.txt" />
+ </item>
+ </channel>
+</rss>`;
+
+const POST_TEXT = '# How Astryx works\n\nThe body of the post.';
+const FEED_URL = `${SITE_URL}/rss.xml`;
+const TXT_URL = `${SITE_URL}/blog/how-astryx-works.txt`;
+
+/** Build a fetch stub from a url→{status,body} map. */
+function stubFetch(routes) {
+ return vi.fn(async url => {
+ const r = routes[String(url)];
+ if (!r) return {ok: false, status: 404, text: async () => 'not found'};
+ return {ok: r.status < 400, status: r.status, text: async () => r.body};
+ });
+}
+
+beforeEach(() => {
+ vi.stubGlobal('fetch', stubFetch({
+ [FEED_URL]: {status: 200, body: FEED},
+ [TXT_URL]: {status: 200, body: POST_TEXT},
+ }));
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+describe('blog.detail leaf', () => {
+ it('reads a post via its plaintext alternate', async () => {
+ const res = await detail('how-astryx-works');
+ expect(res.type).toBe('blog.detail');
+ expect(res.data.text).toBe(POST_TEXT);
+ expect(res.data.feedUrl).toBe(FEED_URL);
+ expect(fetch).toHaveBeenCalledWith(TXT_URL, expect.any(Object));
+ });
+
+ it('is case-insensitive on the slug', async () => {
+ const res = await detail('How-Astryx-Works');
+ expect(res.data.slug).toBe('how-astryx-works');
+ });
+
+ it('throws ERR_UNKNOWN_POST with suggestions for a bad slug', async () => {
+ await expect(detail('does-not-exist')).rejects.toMatchObject({
+ code: 'ERR_UNKNOWN_POST',
+ });
+ try {
+ await detail('does-not-exist');
+ } catch (e) {
+ expect(e).toBeInstanceOf(AstryxError);
+ expect(Array.isArray(e.suggestions)).toBe(true);
+ expect(e.suggestions.length).toBeGreaterThan(0);
+ }
+ });
+
+ it('refuses a post whose plaintext URL is on a different origin (SSRF guard)', async () => {
+ const evilFeed = FEED.replace(
+ `${SITE_URL}/blog/how-astryx-works.txt`,
+ 'http://169.254.169.254/latest/meta-data',
+ );
+ vi.stubGlobal('fetch', stubFetch({
+ [FEED_URL]: {status: 200, body: evilFeed},
+ 'http://169.254.169.254/latest/meta-data': {status: 200, body: 'SECRETS'},
+ }));
+ await expect(detail('how-astryx-works')).rejects.toMatchObject({
+ code: 'ERR_FETCH_FAILED',
+ });
+ // The internal host must never be fetched.
+ expect(fetch).not.toHaveBeenCalledWith(
+ 'http://169.254.169.254/latest/meta-data',
+ expect.anything(),
+ );
+ });
+});
diff --git a/packages/cli/api/blog/list/list.mjs b/packages/cli/api/blog/list/list.mjs
new file mode 100644
index 0000000000..39048f872b
--- /dev/null
+++ b/packages/cli/api/blog/list/list.mjs
@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file blog.list leaf — list posts parsed from the canonical RSS feed.
+ *
+ * A pure projection over the shared adapter: all network fetch + RSS parsing
+ * live in ../_adapter.mjs. The envelope carries `feedUrl` so a caller can hit
+ * the RSS feed directly.
+ *
+ * @input none (the feed origin is fixed — there is no user-supplied URL)
+ * @output {type:'blog.list', data:{feedUrl, posts}} envelope
+ * @position api — leaf under api/blog; dispatched by ../blog.mjs
+ */
+
+import {loadFeed} from '../_adapter.mjs';
+
+/**
+ * List posts from the feed.
+ * @returns {Promise<import('../../../types/blog').BlogListResponse>}
+ */
+export async function list() {
+ const data = await loadFeed();
+ return {type: 'blog.list', data};
+}
diff --git a/packages/cli/api/blog/list/list.test.mjs b/packages/cli/api/blog/list/list.test.mjs
new file mode 100644
index 0000000000..f48bc57062
--- /dev/null
+++ b/packages/cli/api/blog/list/list.test.mjs
@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the blog.list leaf — parses the canonical RSS feed into a
+ * post list. `fetch` is stubbed so the test never hits the network. The feed
+ * origin is fixed (not user-configurable), so the URLs are asserted directly.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {list} from './list.mjs';
+import {SITE_URL} from '../../../lib/site.mjs';
+
+const FEED = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+ <channel>
+ <title>Astryx Blog</title>
+ <link>${SITE_URL}/blog</link>
+ <item>
+ <title>How Astryx works</title>
+ <link>${SITE_URL}/blog/how-astryx-works</link>
+ <description>Under the hood &amp; more</description>
+ <category>engineering</category>
+ <author>cvkxx</author>
+ <author>cixzhang</author>
+ <pubDate>Mon, 29 Jun 2026 00:00:00 GMT</pubDate>
+ <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/how-astryx-works.txt" />
+ </item>
+ <item>
+ <title>Introducing Astryx</title>
+ <link>${SITE_URL}/blog/introducing-astryx</link>
+ <description>The launch</description>
+ <category>update</category>
+ <author>cvkxx</author>
+ <pubDate>Thu, 18 Jun 2026 00:00:00 GMT</pubDate>
+ <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/introducing-astryx.txt" />
+ </item>
+ </channel>
+</rss>`;
+
+const FEED_URL = `${SITE_URL}/rss.xml`;
+const TXT_URL = `${SITE_URL}/blog/how-astryx-works.txt`;
+
+/** Build a fetch stub from a url→{status,body} map. */
+function stubFetch(routes) {
+ return vi.fn(async url => {
+ const r = routes[String(url)];
+ if (!r) return {ok: false, status: 404, text: async () => 'not found'};
+ return {ok: r.status < 400, status: r.status, text: async () => r.body};
+ });
+}
+
+beforeEach(() => {
+ vi.stubGlobal('fetch', stubFetch({[FEED_URL]: {status: 200, body: FEED}}));
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+describe('blog.list leaf', () => {
+ it('lists posts parsed from the canonical feed', async () => {
+ const res = await list();
+ expect(res.type).toBe('blog.list');
+ expect(res.data.feedUrl).toBe(FEED_URL);
+ expect(res.data.posts.map(p => p.slug)).toEqual([
+ 'how-astryx-works',
+ 'introducing-astryx',
+ ]);
+ expect(res.data.posts[0].authors).toEqual(['cvkxx', 'cixzhang']);
+ expect(res.data.posts[0].textUrl).toBe(TXT_URL);
+ // Entity decoding works (&amp; -> &).
+ expect(res.data.posts[0].description).toBe('Under the hood & more');
+ // The list never fetches post bodies.
+ expect(res.data.posts[0].text).toBeUndefined();
+ });
+
+ it('always reads from the canonical feed URL', async () => {
+ await list();
+ expect(fetch).toHaveBeenCalledWith(FEED_URL, expect.any(Object));
+ });
+});