@astryxdesign/cli 0.1.2-canary.043f3fd → 0.1.2-canary.04e71b2

package/CHANGELOG.md

@@ -110,7 +110,6 @@ Thanks to everyone who contributed to this release:
 Thanks to everyone who contributed to this release:
 
 - @ejhammond
-- @joeyfarina
 - @josephfarina
 - @nynexman4464
 

package/README.md

@@ -62,8 +62,7 @@ Options:
 | `upgrade`     | Run codemods to migrate between versions                                                             |
 | `theme build` | Compile a defineTheme file to production CSS and JS                                                  |
 | `discover`    | Discover external packages and components                                                            |
-| `gap-report`  | Report a gap when a component doesn't meet your needs                                                |
-| `doctor`      | Diagnose your XDS setup and report problems with fixes (CI-friendly via exit code)                   |
+| `doctor`      | Diagnose your Astryx setup and report problems with fixes (CI-friendly via exit code)                |
 
 ### Global options
 
@@ -161,7 +160,6 @@ if (isError(result)) {
 | `ERR_INVALID_VERSION`    | A `--from`/`--to` value was not a valid semver string.                                 |
 | `ERR_DEP_MISSING`        | A required external dependency (e.g. jscodeshift) is missing.                          |
 | `ERR_GH_CLI`             | GitHub CLI (`gh`) is not installed or not authenticated.                               |
-| `ERR_GAP_REPORT_FAILED`  | Filing a gap report failed (disabled, or the integration errored).                     |
 
 ## Capability manifest (agent discovery)
 
@@ -172,7 +170,7 @@ discriminators each command can emit. Think of it as an OpenAPI spec for the CLI
 
 ```bash
 astryx manifest --json        # dedicated surface — type: "manifest"
-xds --json                 # bare invocation — embeds the same payload under data.manifest
+astryx --json                 # bare invocation — embeds the same payload under data.manifest
 ```
 
 Shape:
@@ -182,7 +180,7 @@ Shape:
   "apiVersion": 1,
   "type": "manifest",
   "data": {
-    "name": "xds",
+    "name": "astryx",
     "version": "0.0.14",
     "description": "Design system CLI — components, themes, and tooling",
     "globalOptions": [
@@ -249,14 +247,14 @@ the `JSON_SUPPORTED` allowlist and a small declarative `RESPONSE_TYPES` map in
 `src/lib/manifest.mjs`, guarded by a drift test (`manifest.test.mjs`) so adding a
 command without describing it fails CI.
 
-**Backwards-compat:** the bare `xds --json` envelope keeps `type: "help"` and its
+**Backwards-compat:** the bare `astryx --json` envelope keeps `type: "help"` and its
 original shallow fields (`name`, `version`, `commands` as a `string[]` of names,
 `jsonSupported`); the full structured manifest is additive under `data.manifest`.
 For the standalone manifest envelope (`type: "manifest"`), use `astryx manifest --json`.
 
 ## Programmatic API
 
-The same logic that powers `xds --json` is available as importable, type-safe functions:
+The same logic that powers `astryx --json` is available as importable, type-safe functions:
 
 ```typescript
 import {
@@ -269,20 +267,20 @@ import {
   AstryxError,
 } from '@astryxdesign/cli/api';
 
-// Same result as: xds --json component Button
+// Same result as: astryx --json component Button
 const btn = await component('Button');
 btn.type; // 'component.detail'
 btn.data.name; // 'Button' (typed as ComponentDoc)
 
-// Same result as: xds --json component --list
+// Same result as: astryx --json component --list
 const list = await component(undefined, {list: true});
 list.data; // Record<string, string[]>
 
-// Same result as: xds --json docs principles
+// Same result as: astryx --json docs principles
 const principles = await docs('principles');
-principles.data.title; // 'XDS Principles'
+principles.data.title; // 'Principles'
 
-// Same result as: xds --json hook useMediaQuery
+// Same result as: astryx --json hook useMediaQuery
 const useMediaQuery = await hook('useMediaQuery');
 useMediaQuery.data.params; // typed as HookParamDoc[]
 
@@ -296,7 +294,7 @@ try {
 }
 ```
 
-The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that `@astryxdesign/cli/api` and `xds --json` always return identical data.
+The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that `@astryxdesign/cli/api` and `astryx --json` always return identical data.
 
 ### Consumer utilities
 
@@ -326,43 +324,41 @@ detail.data.name; // already narrowed
 
 Every response has a `type` string that uniquely identifies it:
 
-| Command                                        | Type                        | Response                          |
-| ---------------------------------------------- | --------------------------- | --------------------------------- |
-| `xds --json component [--list]`                | `component.list`            | `ComponentListResponse`           |
-| `xds --json component --list --detail compact` | `component.brief`           | `ComponentBriefResponse`          |
-| `xds --json component --list --detail full`    | `component.full`            | `ComponentFullResponse`           |
-| `xds --json component <name>`                  | `component.detail`          | `ComponentDetailResponse`         |
-| `xds --json component <name> --props`          | `component.detail.props`    | `ComponentDetailPropsResponse`    |
-| `xds --json component <name> --source`         | `component.detail.source`   | `ComponentDetailSourceResponse`   |
-| `xds --json component <name> --showcase`       | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |
-| `xds --json component <name> --blocks`         | `component.detail.blocks`   | `ComponentDetailBlocksResponse`   |
-| `xds --json discover`                          | `discover.list`             | `DiscoverListResponse`            |
-| `xds --json discover @scope/name`              | `discover.detail`           | `DiscoverDetailResponse`          |
-| `xds --json discover @scope/name/Comp`         | `discover.detail.doc`       | `DiscoverDetailDocResponse`       |
-| `xds --json discover <search>`                 | `discover.search`           | `DiscoverSearchResponse`          |
-| `xds --json docs`                              | `docs.list`                 | `DocsListResponse`                |
-| `xds --json docs <topic>`                      | `docs.detail`               | `DocsDetailResponse`              |
-| `xds --json docs <topic> <section>`            | `docs.detail.section`       | `DocsDetailSectionResponse`       |
-| `xds --json template [--list]`                 | `template.list`             | `TemplateListResponse`            |
-| `xds --json template <name>`                   | `template.show`             | `TemplateShowResponse`            |
-| `xds --json template <name> --skeleton`        | `template.skeleton`         | `TemplateSkeletonResponse`        |
-| `xds --json template <name> [path]`            | `template.copy`             | `TemplateCopyResponse`            |
-| `xds --json hook [--list]`                     | `hook.list`                 | `HookListResponse`                |
-| `xds --json hook --list --detail compact`      | `hook.brief`                | `HookBriefResponse`               |
-| `xds --json hook --list --detail full`         | `hook.full`                 | `HookFullResponse`                |
-| `xds --json hook <name>`                       | `hook.detail`               | `HookDetailResponse`              |
-| `xds --json hook <name> --params`              | `hook.detail.params`        | `HookDetailParamsResponse`        |
-| `xds --json search <query>`                    | `search`                    | `SearchResponse`                  |
-| `xds --json swizzle [--list]`                  | `swizzle.list`              | `SwizzleListResponse`             |
-| `xds --json swizzle <component>`               | `swizzle.copy`              | `SwizzleCopyResponse`             |
-| `xds --json theme build <file>`                | `theme.build`               | `ThemeBuildResponse`              |
-| `xds --json upgrade --list`                    | `upgrade.list`              | `UpgradeListResponse`             |
-| `xds --json upgrade [--apply]`                 | `upgrade.run`               | `UpgradeRunResponse`              |
-| `xds --json gap-report --list-categories`      | `gap-report.categories`     | `GapReportCategoriesResponse`     |
-| `xds --json gap-report --component X ...`      | `gap-report.file`           | `GapReportFileResponse`           |
-| `xds --json doctor`                            | `doctor`                    | `DoctorResponse`                  |
-| any error                                      | —                           | `CLIError`                        |
-| unsupported command                            | —                           | `CLIUnsupportedError`             |
+| Command                                           | Type                        | Response                          |
+| ------------------------------------------------- | --------------------------- | --------------------------------- |
+| `astryx --json component [--list]`                | `component.list`            | `ComponentListResponse`           |
+| `astryx --json component --list --detail compact` | `component.brief`           | `ComponentBriefResponse`          |
+| `astryx --json component --list --detail full`    | `component.full`            | `ComponentFullResponse`           |
+| `astryx --json component <name>`                  | `component.detail`          | `ComponentDetailResponse`         |
+| `astryx --json component <name> --props`          | `component.detail.props`    | `ComponentDetailPropsResponse`    |
+| `astryx --json component <name> --source`         | `component.detail.source`   | `ComponentDetailSourceResponse`   |
+| `astryx --json component <name> --showcase`       | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |
+| `astryx --json component <name> --blocks`         | `component.detail.blocks`   | `ComponentDetailBlocksResponse`   |
+| `astryx --json discover`                          | `discover.list`             | `DiscoverListResponse`            |
+| `astryx --json discover @scope/name`              | `discover.detail`           | `DiscoverDetailResponse`          |
+| `astryx --json discover @scope/name/Comp`         | `discover.detail.doc`       | `DiscoverDetailDocResponse`       |
+| `astryx --json discover <search>`                 | `discover.search`           | `DiscoverSearchResponse`          |
+| `astryx --json docs`                              | `docs.list`                 | `DocsListResponse`                |
+| `astryx --json docs <topic>`                      | `docs.detail`               | `DocsDetailResponse`              |
+| `astryx --json docs <topic> <section>`            | `docs.detail.section`       | `DocsDetailSectionResponse`       |
+| `astryx --json template [--list]`                 | `template.list`             | `TemplateListResponse`            |
+| `astryx --json template <name>`                   | `template.show`             | `TemplateShowResponse`            |
+| `astryx --json template <name> --skeleton`        | `template.skeleton`         | `TemplateSkeletonResponse`        |
+| `astryx --json template <name> [path]`            | `template.copy`             | `TemplateCopyResponse`            |
+| `astryx --json hook [--list]`                     | `hook.list`                 | `HookListResponse`                |
+| `astryx --json hook --list --detail compact`      | `hook.brief`                | `HookBriefResponse`               |
+| `astryx --json hook --list --detail full`         | `hook.full`                 | `HookFullResponse`                |
+| `astryx --json hook <name>`                       | `hook.detail`               | `HookDetailResponse`              |
+| `astryx --json hook <name> --params`              | `hook.detail.params`        | `HookDetailParamsResponse`        |
+| `astryx --json search <query>`                    | `search`                    | `SearchResponse`                  |
+| `astryx --json swizzle [--list]`                  | `swizzle.list`              | `SwizzleListResponse`             |
+| `astryx --json swizzle <component>`               | `swizzle.copy`              | `SwizzleCopyResponse`             |
+| `astryx --json theme build <file>`                | `theme.build`               | `ThemeBuildResponse`              |
+| `astryx --json upgrade --list`                    | `upgrade.list`              | `UpgradeListResponse`             |
+| `astryx --json upgrade [--apply]`                 | `upgrade.run`               | `UpgradeRunResponse`              |
+| `astryx --json doctor`                            | `doctor`                    | `DoctorResponse`                  |
+| any error                                         | —                           | `CLIError`                        |
+| unsupported command                               | —                           | `CLIUnsupportedError`             |
 
 ## Doctor
 
@@ -383,7 +379,7 @@ astryx doctor — diagnosing your setup
       @astryxdesign/core v0.0.14 is in step with @astryxdesign/cli v0.0.14.
   ⚠ Theme packages
       No @astryxdesign/theme-* packages are installed.
-      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.
+      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.
   ℹ astryx.config.mjs
       No astryx.config.mjs found — using defaults.
   ℹ AI agent docs
@@ -408,7 +404,7 @@ No failures — but review the ⚠ warnings above when you can.
 | Version alignment            | pass / warn / info   | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli`   |
 | Theme packages               | pass / warn          | An `@astryxdesign/theme-*` package is installed and a theme is wired |
 | astryx.config.mjs            | pass / fail / info   | Config (if present) loads cleanly with a valid shape                 |
-| AI agent docs                | pass / warn / info   | Agent docs exist and contain the XDS section markers                 |
+| AI agent docs                | pass / warn / info   | Agent docs exist and contain the Astryx section markers              |
 | Peer dependencies            | pass / warn / info   | `@astryxdesign/core`'s peer deps (react, …) are installed            |
 | Package manager              | info                 | Reports the detected package manager                                 |
 
@@ -434,8 +430,6 @@ export default {
   templates: {
     get: async id => fetchTemplateFromAPI(id),
   },
-  gapReport: {
-    url: 'https://your-api.com/gaps',
-  },
+  issuesUrl: 'https://github.com/your-org/your-repo/issues',
 };
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.2-canary.043f3fd",
+  "version": "0.1.2-canary.04e71b2",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,9 +75,9 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.043f3fd",
-    "@astryxdesign/lab": "0.1.2-canary.043f3fd",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.043f3fd",
+    "@astryxdesign/core": "0.1.2-canary.04e71b2",
+    "@astryxdesign/lab": "0.1.2-canary.04e71b2",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.04e71b2",
     "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -92,9 +92,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.043f3fd",
-    "@astryxdesign/lab": "0.1.2-canary.043f3fd",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.043f3fd",
+    "@astryxdesign/core": "0.1.2-canary.04e71b2",
+    "@astryxdesign/lab": "0.1.2-canary.04e71b2",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.04e71b2",
     "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {

package/src/api/blog.mjs

@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Programmatic API for the blog command.
+ *
+ * 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();
+
+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.name === 'AbortError' ? 'timed out' : e.message;
+    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.
+ */
+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,
+    );
+  }
+}
+
+function unescapeXml(value) {
+  return value
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+function tag(item, name) {
+  const m = item.match(new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`));
+  return m ? unescapeXml(m[1].trim()) : '';
+}
+
+function tagAll(item, name) {
+  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>. */
+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). */
+function slugFromLink(link) {
+  try {
+    const path = new URL(link).pathname.replace(/\/$/, '');
+    return path.slice(path.lastIndexOf('/') + 1);
+  } catch {
+    return link;
+  }
+}
+
+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;
+}
+
+/**
+ * List posts (from the feed), or read one post (via its .txt alternate).
+ * Both envelopes carry `feedUrl` so a caller can hit the RSS feed directly.
+ * The feed is always the canonical site — there is no user-supplied URL.
+ *
+ * @param {string} [slug]
+ * @returns {Promise<{type: string, data: unknown}>}
+ */
+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}};
+}

package/src/api/blog.test.mjs

@@ -0,0 +1,144 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the blog API — reads the blog over the canonical RSS feed
+ * and fetches each post's plaintext (.txt) alternate. `fetch` is stubbed so
+ * the tests never hit the network. The feed origin is fixed (not
+ * user-configurable), so the tests assert the canonical URLs directly.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {blog} from './blog.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>
+      <guid isPermaLink="true">${SITE_URL}/blog/how-astryx-works</guid>
+      <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>
+      <guid isPermaLink="true">${SITE_URL}/blog/introducing-astryx</guid>
+      <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 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, opts) => {
+    const u = String(url);
+    const r = routes[u];
+    if (!r) return {ok: false, status: 404, text: async () => 'not found'};
+    if (r.throw) throw r.throw;
+    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},
+    [`${SITE_URL}/blog/introducing-astryx.txt`]: {status: 200, body: 'launch body'},
+  }));
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('blog API', () => {
+  it('lists posts parsed from the canonical feed', async () => {
+    const res = await blog();
+    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('reads a post via its plaintext alternate', async () => {
+    const res = await blog('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 blog('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(blog('does-not-exist')).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_POST',
+    });
+    try {
+      await blog('does-not-exist');
+    } catch (e) {
+      expect(e).toBeInstanceOf(AstryxError);
+      expect(Array.isArray(e.suggestions)).toBe(true);
+      expect(e.suggestions.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('throws ERR_FETCH_FAILED when the feed request fails', async () => {
+    vi.stubGlobal('fetch', stubFetch({
+      [FEED_URL]: {status: 500, body: 'boom'},
+    }));
+    await expect(blog()).rejects.toMatchObject({code: 'ERR_FETCH_FAILED'});
+  });
+
+  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(blog('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(),
+    );
+  });
+
+  it('always reads from the canonical feed URL', async () => {
+    await blog();
+    expect(fetch).toHaveBeenCalledWith(FEED_URL, expect.any(Object));
+  });
+});

package/src/api/doctor.mjs

@@ -240,7 +240,7 @@ export function checkThemes(ctx) {
       label: 'Theme packages',
       status: 'warn',
       message: 'No @astryxdesign/theme-* packages are installed.',
-      fix: 'Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.',
+      fix: 'Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.',
     };
   }
 
@@ -354,7 +354,7 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'warn',
       message: `Agent docs present (${present.join(', ')}) but no Astryx section markers found.`,
-      fix: 'Add the XDS section to your agent docs with `astryx init --features agents`.',
+      fix: 'Add the Astryx section to your agent docs with `astryx init --features agents`.',
     };
   }
 
@@ -362,7 +362,7 @@ export function checkAgentDocs(ctx) {
     id: 'agent-docs',
     label: 'AI agent docs',
     status: 'pass',
-    message: `XDS agent docs section present in ${withMarkers.join(', ')}.`,
+    message: `Astryx agent docs section present in ${withMarkers.join(', ')}.`,
   };
 }
 

package/src/api/index.mjs

@@ -21,6 +21,7 @@
 
 export {component} from './component.mjs';
 export {docs} from './docs.mjs';
+export {blog} from './blog.mjs';
 export {discover} from './discover.mjs';
 export {template} from './template.mjs';
 export {themeAdd, listThemes} from './theme-add.mjs';