@astryxdesign/cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # @xds/cli
 
+# 0.3.0
+
+#### Breaking Changes
+
+- CLI — authoring is consolidated into a single entrypoint, `@astryxdesign/cli/authoring`, that exposes only TYPES (the plain objects authors write) and PARSERS (the CLI's load-boundary validators). Zod is sealed inside each parser and never exported.
+- Remove long-deprecated compatibility APIs from core and CLI. Run `astryx upgrade` first to migrate the supported replacements for authoring imports, Dialog logical positions, Switch label spacing, and Table root props.
+
+#### New Features
+
+- CLI human (non-`--json`) output now renders through a small, documented formatter kit: consistent, plain-ASCII `key: value` records/sections that mirror `--json` and are greppable by field. Every command was migrated onto it (a lint rule keeps output funneled through the single `emit` sink), and `astryx --help` documents the output contract. `--json` output is unchanged. (#4686)
+- `defineTheme`: make `color.accent` optional (#2279)
+  A theme can now restyle the neutral ramp (`neutralStyle`, `contrast`) without adopting an accent. An accent-less config seeds the neutral palettes from the default accent's hue but leaves `--color-accent`, `--color-accent-muted` and `--color-on-accent` ungenerated, so they fall through to the token defaults — the same fall-through `expandColorScale` already applies to status, categorical and on-dark tokens. Configs that pass an accent are unchanged, token for token.
+
+#### Fixes
+
+- theme build: generated custom Button variants now type-check through the public `@astryxdesign/core/Button` subpath.
+- Remove the `@xds/theme-default` → `@astryxdesign/theme-neutral` collapse from the v0.1.0 upgrade codemods (module-specifiers, css-surfaces, and declare-module). `theme-default` was dropped at the v0.1.0 scope move, so no v0.1.x consumer imported it — the collapse was dead and could rewrite unrelated source (including `@xds/theme-default/theme.css` CSS imports) to a `@astryxdesign/theme-neutral` package the app never declared. The `@xds/theme-daily` → `theme-neutral` collapse (and its `defaultTheme` → `neutralTheme` export remap) is unchanged.
+- cli — confine user-controlled file paths, close DoS vectors, and repair paths broken by the authoring reorg (#4637)
+- cli hardening pass — validate inputs at the API layer, close path-safety gaps, and prevent agent-docs content loss. The API is a public surface (`@astryxdesign/cli/api`), so guards that lived only in the CLI wrapper are pushed into the API.
+  Path safety (the guard the write commands all depend on):
+- cli — rename the `search`/`build` verbose flag to `--verbose`, resync the bundled themes, and fix `unwrap-authoring-factories` edge cases (#4639)
+- `astryx doctor`'s peer-dependency check is now version-aware and names scoped packages correctly. Two problems are fixed: (1) the install hint was built with `name.split('@')[0]`, which for a scoped peer like `@stylexjs/stylex` returned an empty string, printing a bare `npm install ` with no package; and (2) the check only verified a peer was _present_, not that its installed version satisfied the declared range — so an out-of-range version (e.g. `@stylexjs/stylex@0.10.1` against a `^0.19.0` peer) was reported as satisfied. The check now flags out-of-range peers and its fix pins the required range, e.g. `npm install @stylexjs/stylex@^0.19.0`.
+- theme build: validate component override keys from documented theming targets so subtargets like Chat bubbles and SideNav items no longer warn as unknown.
+- `astryx theme build`: hyphenated component-override keys now resolve their built-in visual-prop values, and the `KNOWN_COMPONENTS` prop lists match what each component renders (#4109)
+  `loadKnownValues` mapped a theme key to its core component directory by stripping non-letters from only the directory name, so a hyphenated key (`text-input`, `dropdown-menu`, `app-shell`, ...) never matched its `TextInput`/`DropdownMenu`/`AppShell` dir and the built-in prop values were silently dropped. It now strips non-letters from both sides before comparing, so hyphenated keys resolve. The `KNOWN_COMPONENTS` visual-prop lists are also synced to each component's `theming.targets[].visualProps` (e.g. `text-input`/`date-input`/`number-input`/`time-input`: `size`, `status`; `side-nav`: `mode`; `aspect-ratio`: `shape`), correcting stale/empty entries.
+
+#### Documentation
+
+- Document the core codemod staging workflow and add release-time automation that promotes `transforms/next` codemods into the resolved release version folder.
+- Document the `@astryxdesign/core` StyleX peer dependency — add `@stylexjs/stylex` to the Getting Started / Quick Start install commands in both READMEs, and add an `astryx init` next-steps reminder to ensure the `@stylexjs/stylex` peer dependency is met, with a pointer to `astryx doctor`. StyleX is the styling runtime every component calls, and not all package managers auto-install peers.
+- Surface the React 19 peer-dependency requirement everywhere a user would look for it (root README, core README, docsite hero, and the CLI getting-started guide), and add a sync test that keeps those surfaces naming the same React major as the core peer range.
+
+#### Other Changes
+
+- **The `create*` factories are removed** (`createConfig`, `createIntegration`, `createComponentDoc`, `createFunctionDoc`, `createDoc`, `createPageTemplate`, `createBlockTemplate`, `createCodemod`, `createConfigCodemod`). Author a plain object and stamp its `type` directly (`{type: 'component', ...}`, `{type: 'page', ...}`, `{type: 'code', ...}`); config and integration manifests are plain objects with no discriminant.
+- **Import authoring types from `@astryxdesign/cli/authoring`** — the doc types `ComponentDoc`, `HookDoc`, `ReferenceDoc`, `TemplateDoc`, and the project-file types `AstryxConfig`, `AstryxIntegration`, `AstryxCodemod`. The old split surfaces (`@astryxdesign/cli/{config,doc,integration,template,codemod}` and the authoring exports of `@astryxdesign/core`) are superseded.
+- **Doc field types are renamed to explicit, domain-prefixed names** so the surface reads clearly: `PropDoc → ComponentPropDoc`, `ThemingTarget → ComponentThemingTarget`, `ComponentVar → ComponentThemingVar`, `DerivedVar → ComponentThemingDerivedVar`, `ElementDescriptor → ComponentSlotElement`, `GroupDoc → ComponentGroupDoc`, `TranslationDoc → ComponentTranslationDoc`, `ExampleDoc/AnatomyElement/BestPractice/PlaygroundConfig → Component*`, and `ContentBlock/TokenPreviewType → Reference*`. The authorable entry types (`ComponentDoc`/`HookDoc`/`ReferenceDoc`/`TemplateDoc`) are unchanged.
+- **`astryx upgrade` migrates you automatically.** Three codemods ship in this release: `unwrap-authoring-factories` rewrites every `create*` call to the plain stamped object, `migrate-authoring-imports` repoints the import specifiers to `@astryxdesign/cli/authoring`, and `rename-authoring-doctypes` applies the doc field-type renames (imports, type references, and JSDoc `@type` refs).
+- CLI — the public `@astryxdesign/cli/api` type surface is now generated from the runtime JSDoc, and the injectable logger is consolidated into one `Logger`.
+  Consumer-visible changes to `@astryxdesign/cli/api` (types only — runtime imports are unchanged):
+- **Precise return types.** `component`, `docs`, `blog`, `discover`, `build`, `swizzle`, `upgrade`, `init`, and `themeBuild` previously resolved to `Promise<any>`; they now return their precise `{ type, data }` response unions. Code that leaned on `any` may surface new (correct) type errors.
+- **Response types are now exported by name** — e.g. `ComponentDetailResponse`, `SearchResponse`, `UpgradeRunResponse` — alongside `themeAdd`/`themeList`/`listThemes` and a new shared `logger` value + `Logger` type.
+- **Breaking:** the per-command return-union aliases `ComponentResult`, `DiscoverResult`, `DocsResult`, `HookResult`, and `TemplateResult` are no longer exported. Use `Awaited<ReturnType<typeof component>>` (still works), or import the member response types directly.
+- `theme build --out`/`<file>`, the `validate-integration` manifest roots (`components`/`templates`/`codemods`), and `layout --file` are now confined with `assertWithin`. An escaping integration root reports a validation issue instead of importing and executing files outside the package; `layout --file` is also size-capped (5 MB) and rejects non-files, so a stream like `/dev/zero` can't exhaust memory.
+- Fuzzy-match (Levenshtein), the layout value parser, and the layout expander gained bounds — a very long search query, a deeply nested attribute value, and a huge repeat count (`Box*999999999`) can no longer spin the CPU, blow the stack, or exhaust the heap.
+- Docs topic lookup uses a null-prototype map so `__proto__`/`constructor` as a topic name can't bypass the unknown-topic guard. The shipped getting-started docs and the sandbox registry generator point at the current CLI source path again (both broke in the authoring reorg).
+- `assertWithin` now canonicalizes symlinks (realpath of the deepest existing ancestor) — a symlink inside the project root pointing outside no longer lets a write escape. Also rejects a NUL byte in the path. This closes the escape for every command that writes through the guard (swizzle/template/upgrade/theme/layout/agent-docs).
+- `search()`: non-positive/non-integer `limit`, empty query, unknown `--type` → `ERR_INVALID_ARGUMENT` (previously `limit: 0` returned the full unclamped set).
+- `swizzle()`: the component name is sanitized so `..`/separators can't escape the `--output` base.
+- `swizzle()` import rewriting: dynamic `import('../Sibling/…')` is now rewritten (was left pointing at a non-existent sibling in the output dir); a two-levels-up asset import (`../../locales/x.json`) maps to the exported subpath instead of the invalid `<pkg>/..`; and `../theme/tokens.stylex` keeps its full subpath (the StyleX compiler needs the dedicated `./theme/tokens.stylex` export — collapsing it to `<pkg>/theme` broke StyleX resolution). Component-local `.stylex` files that aren't subpath exports keep the working barrel collapse.
+- `template()` copy: refuses to clobber without `overwrite: true` (`ERR_FILE_EXISTS`); adds an `overwrite` option.
+- `upgrade()`: the `--path` scan dir is confined to cwd (`--apply` rewrites files in place).
+- `init()`: template scaffold refuses to clobber an existing `page.tsx` (`ERR_FILE_EXISTS`); an unknown `--agent` now throws `ERR_UNKNOWN_AGENT` (was silently ignored).
+- `layout`: rejects an unknown `--form` (`ERR_INVALID_OPTION`) and empty expression (`ERR_INVALID_ARGUMENT`).
+- `layout expand`: text payloads containing `<`, `>`, `{`, or `}` (e.g. `Text"5 < 3"`) are emitted as JSX string-expression children so the generated TSX is valid — previously they produced syntactically-broken output.
+- `layout expand`: a top-level repeat or group that expands to multiple sibling elements (`B"x"*3`, `(B"a" + B"b")`, an outline `repeat` block) is now wrapped in a fragment — previously the generated TSX had adjacent root elements with no parent and failed to compile (the wrapper decision counted AST roots instead of expanded elements).
+- `layout` (expand/check): an empty expression now surfaces `ERR_MISSING_ARGUMENT` and a missing `--file` surfaces `ERR_FILE_NOT_FOUND` (was a generic `ERR_UNKNOWN` / a raw `ENOENT` errno, with a stack leak in human mode).
+- `layout` parser: a pathologically deep compact expression (`V > …` nested past 512 levels) is rejected with a located `ERR_LAYOUT_PARSE` instead of blowing the call stack and surfacing a raw `RangeError` (→ `ERR_UNKNOWN`).
+- `layout check --form …` printers: a string containing a quote (e.g. a Button `label="Don't panic"`) now round-trips — the printer picks a delimiter the string doesn't contain instead of always single-quoting, so the emitted compact/outline surface re-parses (was producing an unparseable token).
+- `resolveTheme`: a non-string `astryx.theme` in package.json (number/array/object/boolean) degrades to null instead of crashing `astryx component` with a raw `TypeError` (parity with the empty-string / unknown-slug paths).
+- `jsonOut`: serializes the envelope BEFORE marking the emission handled, so if a command returns unserializable `data` (circular ref / BigInt — an author bug) the bin error boundary still emits a JSON error envelope instead of leaving a `--json` consumer with empty stdout.
+- package scanner: a dependency's `astryx.docs` that is a non-string (number/array) is skipped instead of crashing the whole scan with a raw `TypeError`, and a `docs` path that escapes its own package dir is skipped rather than surfacing foreign docs; a non-string package `name` is coerced to a string.
+- `component --package <pkg> --showcase`/`--blocks`: route to the right leaf instead of falling back to `component.detail`.
+- `discover`/`docs` leaves: empty query/section errors instead of matching everything via `.includes('')`.
+- `docs()`/`discover()`: a non-string `topic`/`section`/`query` now throws a stable coded error (`ERR_UNKNOWN_TOPIC` / `ERR_UNKNOWN_SECTION` / `ERR_INVALID_ARGUMENT`) instead of a raw `TypeError` the CLI downgraded to `ERR_UNKNOWN` (parity with the `component`/`hook` non-string guards).
+- `blog()` detail: a non-string slug throws `ERR_INVALID_ARGUMENT` (was a raw `TypeError` the CLI downgraded to `ERR_UNKNOWN`), and fails fast before any network fetch.
+- `hook()`/`component()` dispatchers: a non-string `name` or `category` throws a coded error (`ERR_UNKNOWN_HOOK` / `ERR_UNKNOWN_COMPONENT` / `ERR_UNKNOWN_CATEGORY`) instead of a raw `TypeError` with no `.code` from the leaf's `.toLowerCase()`/`.replace(...)`.
+- `theme add`: a write failure where an ancestor of the target dir is a file now surfaces `ERR_WRITE_FAILED` (the `mkdir` moved inside the write try/catch) instead of leaking a raw fs errno (`EEXIST`/`ENOTDIR`) + absolute path.
+- `validate-integration`: a path-unsafe `[package]` spec (`..`/absolute) is reported as an `invalid_package_spec` diagnostic instead of crashing with a raw stack (human) / generic `ERR_UNKNOWN` (`--json`).
+- `doctor`: no longer crashes (raw stack in human mode / `ERR_UNKNOWN` in `--json`) when multiple `astryx.config.*` files coexist — it reports a `config` FAIL. Version-alignment skips (info) instead of a spurious drift WARN with a `NaN.undefined.x` fix when either version isn't comparable semver (e.g. `workspace:*`).
+- `manifest`: subcommands are sorted by name (same stability guarantee the top-level command list makes), so reordering `.command()` calls can't silently change the agent-facing manifest.
+- `build`: the CLI wrapper now propagates the API's error `code` into the `--json` envelope (bogus `--type` / non-positive / non-integer `--limit` → `ERR_INVALID_ARGUMENT` instead of a generic `ERR_UNKNOWN`), and delegates `--limit` validation to the API (parity with `search`).
+- `layout check`: exits `1` in BOTH `--json` and human mode for an invalid (but parseable) layout — the exit code no longer depends on the output mode, so it works as a CI gate / agent check without parsing stdout.
+- `upgrade` config codemods: a `findConfigPath` throw (multiple `astryx.config.*` files) is surfaced as a structured per-codemod error instead of crashing the whole upgrade run — config codemods run before the strict loader, so this restores the per-codemod isolation every other failure path honors.
+- CLI dispatch: the belt-and-suspenders postAction "completed without emitting an envelope" error carries a `code` (`ERR_UNKNOWN`) so every error envelope is branchable on `code`.
+- `toErrorEnvelope`/`AstryxError`: attach `suggestions` only when it's a real array.
+- `injectXdsBlock`/`removeXdsBlock` no longer drop, duplicate, or orphan user content on malformed managed blocks (END-before-START, duplicate/nested blocks, or a start marker with no end). They locate a single well-formed block (END searched after START) and refuse to touch an ambiguous/half-written file instead of corrupting it.
+- The codemod source scan no longer follows symlinks (a symlinked file under the scanned path could rewrite its target OUTSIDE the project) and skips generated-output dirs (dist/build/out/.next/coverage) — codemods rewrite source, not artifacts or dependencies.
+- `resolvePackageDir` rejects an integration spec that isn't a bare package name (no `..`, no absolute, must stay in node_modules) — a config spec can no longer point the loader at an arbitrary module.
+- A broken integration manifest (throws on import or fails schema validation) no longer crashes `Project.load` (and thus every command). It's recorded and surfaced via `issues()`, restoring the documented skip+warn policy; other integrations still load.
+- The `--radius-*`, `--shadow-*`/`--elevation-*`, and `--color-*` token-migration codemods no longer rewrite a longer consumer-defined token that merely shares a prefix (e.g. `--radius-container-custom` → `--radius-3-custom`, `--radius-innermost` → `--radius-0most`, `var(--shadow-10)` → `--shadow-base0`, `--color-positive-custom` → `--color-success-custom`). The boundary lookahead was binding only to the last alternative in the pattern (and two codemods had no boundary at all); it now wraps the whole alternation, so only exact token names migrate.
+- `migrate-badge-children-to-label` no longer emits a duplicate `label` prop when the badge already has one (`<XDSBadge label="x">Active</XDSBadge>` produced an invalid `label="x" label="Active"`); it now skips a badge that already declares `label`.
+- `readDocMeta` no longer reads a `group:`/`hidden:` field nested inside a `propDescriptions` block (a docsZh/docsDense translation export) as the component's group — that leaked a translated prop description as a group key in the default English `component --list` (e.g. a Chinese string appeared as a group). The field regexes now match top-level fields only (<=2 spaces).
+- `astryx search`/`build` verbose output was unreachable: the boolean `--detail` flag collided with the root program's value-taking `--detail <level>`, so `search button --detail` errored `argument missing`. The boolean is now `--verbose` (the global `--detail <level>` is unchanged).
+- The themes bundled for `astryx theme add` had drifted from source — the `neutral` bundle was missing a WCAG AA light-mode `text-secondary` contrast fix and a StatusDot color block, so `astryx theme add neutral` scaffolded a theme below AA. All bundles are regenerated to match source, guarded by a new drift test.
+- The `unwrap-authoring-factories` upgrade codemod produced broken output for a shorthand `type` property (emitted `{'component'}`) and for no-argument factory calls (left a call referencing the just-removed import). Both now emit the correct plain object.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @AKnassa
+- @cixzhang
+- @ejhammond
+- @imdreamrunner
+- @jiunshinn
+- @joeyfarina
+- @josephfarina
+
+---
+
 # 0.2.0
 
 #### Breaking Changes
@@ -704,7 +805,7 @@ npx astryx upgrade --apply --to 0.0.6
 #### Features
 
 - **`astryx theme build`** — Renamed from `build-theme` to `theme build` (#570)
-- **`--lang` flag** — TranslationDoc support for i18n/compressed docs (#611)
+- **`--lang` flag** — ComponentTranslationDoc support for i18n/compressed docs (#611)
 - **`--zh` flag** — Chinese Simplified doc output (#567)
 
 #### Refactors

package/README.md

@@ -461,20 +461,15 @@ The CLI reads an optional `astryx.config.{ts,mjs,js}` from your project root
 CLI runs on defaults.
 
 ```typescript
-import {createConfig} from '@astryxdesign/core/config';
-
-export default createConfig({
+export default {
   integrations: ['@acme/astryx-widgets'],
   issuesUrl: 'https://github.com/your-org/your-repo/issues',
-});
+};
 ```
 
-`createConfig` is a type-preserving helper: it returns its argument unchanged
-and exists only to give the config file editor autocomplete and type-checking. A
-plain `export default {}` object works identically. It's exported from
-`@astryxdesign/core` (not the CLI) so your config file gets type feedback
-without depending on the CLI; the same helper is re-exported from
-`@astryxdesign/cli/config` for back-compat.
+There is no factory: write a plain object. For editor autocomplete and
+type-checking, annotate it with the `AstryxConfig` type exported from
+`@astryxdesign/cli/authoring`.
 
 | Field                         | Type                           | Purpose                                                                                         |
 | ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
@@ -487,6 +482,30 @@ The config is validated against a strict schema when the CLI loads it, so an
 unknown field is a hard error rather than a silent no-op. `astryx doctor`
 reports whether the config loads cleanly.
 
+## Core codemod authoring
+
+Core codemods live under `packages/cli/assets/codemods/transforms/`. Released
+codemods are grouped by the target package version (`v0.3.0`, `v0.3.1`, ...),
+which is the version that first contains the breaking change.
+
+Do not guess that version in ordinary feature PRs. Add new codemods to
+`packages/cli/assets/codemods/transforms/next/` instead:
+
+- put transform modules and tests in `transforms/next/`;
+- maintain `transforms/next/index.mjs` with the run order for the staged
+  transforms;
+- leave `transforms/next/README.md` in place; it documents the staging area and
+  is never promoted.
+
+During the Version Packages PR, `pnpm version-packages` runs
+`scripts/promote-codemod-next.mjs` after `changeset version`. The script copies
+all staged entries except the README into `transforms/v<new-core-version>/`,
+registers that version in `packages/cli/assets/codemods/registry.mjs`, and clears
+the promoted files from `next`.
+
+This mirrors Changesets: feature PRs stage migration work without knowing the
+future release number; the release PR assigns the exact version.
+
 ## Integrations
 
 An **integration** is any npm package that contributes its own components,
@@ -514,14 +533,12 @@ manifest points at where each kind of contribution lives; identity (name,
 version) comes from `package.json`, not the manifest.
 
 ```typescript
-import {createIntegration} from '@astryxdesign/core/authoring';
-
-export default createIntegration({
+export default {
   components: './components',
   templates: './templates',
   codemods: './codemods',
   issuesUrl: 'https://github.com/acme/widgets/issues',
-});
+};
 ```
 
 | Field        | Type     | Purpose                                                               |
@@ -531,10 +548,9 @@ export default createIntegration({
 | `codemods`   | `string` | Directory holding upgrade codemods run by `astryx upgrade`.           |
 | `issuesUrl`  | `string` | Where "report an issue" links for this package's contributions point. |
 
-Every field is optional; declare only the roots the package ships.
-`createIntegration` is a type-preserving helper (editor autocomplete and
-type-checking); it lives in `@astryxdesign/core/authoring` and is re-exported
-from `@astryxdesign/cli/integration` for back-compat.
+Every field is optional; declare only the roots the package ships. There is no
+factory: write a plain object, and annotate it with the `AstryxIntegration` type
+from `@astryxdesign/cli/authoring` for editor autocomplete and type-checking.
 
 ### How it works
 

package/api/blog/_adapter.d.mts

@@ -0,0 +1,21 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * 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('./blog.type.mjs').BlogListData>}
+ */
+export function loadFeed(): Promise<import("./blog.type.mjs").BlogListData>;
+/**
+ * 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 function fetchPostText(textUrl: string): Promise<string>;
+/**
+ * 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: string;

package/api/blog/_adapter.mjs

@@ -14,8 +14,8 @@
  */
 
 import {AstryxError} from '../error.mjs';
-import {ERROR_CODES} from '../../lib/error-codes.mjs';
-import {SITE_URL, SITE_ORIGIN} from '../../lib/site.mjs';
+import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {SITE_URL, SITE_ORIGIN} from './_site.mjs';
 
 /** Abort a feed/post fetch that hangs, and cap how much we'll read. */
 const FETCH_TIMEOUT_MS = 15000;
@@ -173,10 +173,10 @@ function slugFromLink(link) {
 
 /**
  * @param {string} xml
- * @returns {import('../../types/blog').BlogPost[]}
+ * @returns {import('./blog.type.mjs').BlogPost[]}
  */
 function parseFeed(xml) {
-  /** @type {import('../../types/blog').BlogPost[]} */
+  /** @type {import('./blog.type.mjs').BlogPost[]} */
   const items = [];
   const re = /<item>([\s\S]*?)<\/item>/g;
   let m;
@@ -200,7 +200,7 @@ function parseFeed(xml) {
 /**
  * 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>}
+ * @returns {Promise<import('./blog.type.mjs').BlogListData>}
  */
 export async function loadFeed() {
   const xml = await fetchText(FEED_URL);

package/api/blog/_adapter.test.mjs

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the blog adapter (api/blog/_adapter.mjs) — the shared network
+ * + RSS-parsing layer behind the blog leaves. `fetch` is stubbed so nothing
+ * hits the network. Locks the SSRF/origin guard, invalid-URL handling, and the
+ * garbage-feed degradation that the leaves depend on but never test directly.
+ */
+
+import {describe, it, expect, afterEach, vi} from 'vitest';
+import {loadFeed, fetchPostText, FEED_URL} from './_adapter.mjs';
+import {AstryxError} from '../error.mjs';
+import {SITE_URL} from './_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>Under the hood &amp; more</title>
+      <link>${SITE_URL}/blog/how-astryx-works</link>
+      <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/how-astryx-works.txt" />
+    </item>
+  </channel>
+</rss>`;
+
+/** 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};
+  });
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('blog adapter — loadFeed', () => {
+  it('parses posts and reports the canonical feed URL', async () => {
+    vi.stubGlobal('fetch', stubFetch({[FEED_URL]: {status: 200, body: FEED}}));
+    const {feedUrl, posts} = await loadFeed();
+    expect(feedUrl).toBe(FEED_URL);
+    expect(posts).toHaveLength(1);
+    expect(posts[0].slug).toBe('how-astryx-works');
+    // XML entities in the title are unescaped.
+    expect(posts[0].title).toBe('Under the hood & more');
+  });
+
+  it('returns an empty post list for non-RSS / garbage feed content', async () => {
+    vi.stubGlobal(
+      'fetch',
+      stubFetch({[FEED_URL]: {status: 200, body: '<html>not a feed</html>'}}),
+    );
+    const {feedUrl, posts} = await loadFeed();
+    expect(feedUrl).toBe(FEED_URL);
+    expect(posts).toEqual([]);
+  });
+
+  it('throws ERR_FETCH_FAILED when the feed request is non-200', async () => {
+    vi.stubGlobal('fetch', stubFetch({[FEED_URL]: {status: 500, body: 'boom'}}));
+    await expect(loadFeed()).rejects.toMatchObject({code: 'ERR_FETCH_FAILED'});
+  });
+});
+
+describe('blog adapter — fetchPostText SSRF/origin guard', () => {
+  it('rejects a plaintext URL on a non-canonical origin (SSRF)', async () => {
+    const spy = vi.fn(async () => ({ok: true, status: 200, text: async () => 'SECRETS'}));
+    vi.stubGlobal('fetch', spy);
+    await expect(
+      fetchPostText('http://169.254.169.254/latest/meta-data'),
+    ).rejects.toBeInstanceOf(AstryxError);
+    await expect(
+      fetchPostText('http://169.254.169.254/latest/meta-data'),
+    ).rejects.toMatchObject({code: 'ERR_FETCH_FAILED'});
+    // The internal host must never be fetched.
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('rejects an unparseable URL with ERR_FETCH_FAILED', async () => {
+    vi.stubGlobal('fetch', vi.fn());
+    await expect(fetchPostText('not a url')).rejects.toMatchObject({
+      code: 'ERR_FETCH_FAILED',
+    });
+  });
+
+  it('fetches a same-origin plaintext URL', async () => {
+    const url = `${SITE_URL}/blog/how-astryx-works.txt`;
+    vi.stubGlobal('fetch', stubFetch({[url]: {status: 200, body: '# body'}}));
+    await expect(fetchPostText(url)).resolves.toBe('# body');
+  });
+});

package/api/blog/_site.d.mts

@@ -0,0 +1,19 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file site.mjs — the canonical Astryx site origin for CLI code.
+ *
+ * The published Astryx site is the single source of truth for docs, the blog,
+ * and the MCP endpoint. Anything in the CLI that needs to reach the site reads
+ * this constant, so the origin is defined in exactly one place. It is
+ * intentionally not user-configurable: the CLI should never be pointed at an
+ * arbitrary host.
+ *
+ * (The docsite has its own SITE_URL in apps/docsite; the CLI is a separately
+ * published package and can't import from the app, so the origin is mirrored
+ * here for CLI use.)
+ */
+export const SITE_URL: "https://astryx.atmeta.com";
+/** The site's origin (scheme + host), used for same-origin checks. */
+export const SITE_ORIGIN: string;

package/api/blog/blog.d.mts

@@ -0,0 +1,15 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * 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<import('./blog.type.mjs').BlogListResponse | import('./blog.type.mjs').BlogDetailResponse>}
+ */
+export function blog(slug?: string): Promise<import("./blog.type.mjs").BlogListResponse | import("./blog.type.mjs").BlogDetailResponse>;
+import { list } from './list/list.mjs';
+import { detail } from './detail/detail.mjs';
+export { list, detail };

package/api/blog/blog.mjs

@@ -28,7 +28,7 @@ import {detail} from './detail/detail.mjs';
  * The feed is always the canonical site — there is no user-supplied URL.
  *
  * @param {string} [slug]
- * @returns {Promise<import('../../types/blog').BlogListResponse | import('../../types/blog').BlogDetailResponse>}
+ * @returns {Promise<import('./blog.type.mjs').BlogListResponse | import('./blog.type.mjs').BlogDetailResponse>}
  */
 export async function blog(slug) {
   return slug ? detail(slug) : list();

package/api/blog/blog.test.mjs

@@ -10,7 +10,7 @@
 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';
+import {SITE_URL} from './_site.mjs';
 
 const FEED = `<?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">

package/api/blog/blog.type.d.mts

@@ -0,0 +1,38 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * A single post as parsed from the canonical RSS feed.
+ */
+export type BlogPost = {
+    slug: string;
+    title: string;
+    description?: string | undefined;
+    date?: string | undefined;
+    type?: string | undefined;
+    authors?: string[] | undefined;
+    link?: string | undefined;
+    textUrl?: string | null | undefined;
+};
+export type BlogListData = {
+    feedUrl: string;
+    posts: BlogPost[];
+};
+export type BlogDetailData = BlogPost & {
+    feedUrl: string;
+    text: string;
+};
+/**
+ * `astryx --json blog` (no slug).
+ */
+export type BlogListResponse = {
+    type: "blog.list";
+    data: BlogListData;
+};
+/**
+ * `astryx --json blog <slug>`.
+ */
+export type BlogDetailResponse = {
+    type: "blog.detail";
+    data: BlogDetailData;
+};

package/api/blog/blog.type.mjs

@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated types for the `blog` command — the source of truth for its
+ * response/data shapes. The leaves' `@returns` reference these directly
+ * (functions own their types); the public `@astryxdesign/cli/api` surface
+ * re-exports them via types/blog.d.ts, so consumers see the same names.
+ *
+ * @position api — colocated typedefs for api/blog/{blog,list,detail,_adapter}
+ */
+
+/**
+ * A single post as parsed from the canonical RSS feed.
+ * @typedef {object} BlogPost
+ * @property {string} slug
+ * @property {string} title
+ * @property {string} [description]
+ * @property {string} [date]
+ * @property {string} [type]
+ * @property {string[]} [authors]
+ * @property {string} [link]
+ * @property {string | null} [textUrl]
+ */
+
+/**
+ * @typedef {object} BlogListData
+ * @property {string} feedUrl
+ * @property {BlogPost[]} posts
+ */
+
+/**
+ * @typedef {BlogPost & {feedUrl: string, text: string}} BlogDetailData
+ */
+
+/**
+ * `astryx --json blog` (no slug).
+ * @typedef {object} BlogListResponse
+ * @property {'blog.list'} type
+ * @property {BlogListData} data
+ */
+
+/**
+ * `astryx --json blog <slug>`.
+ * @typedef {object} BlogDetailResponse
+ * @property {'blog.detail'} type
+ * @property {BlogDetailData} data
+ */
+
+// Make this a module so the @typedefs above are importable as types via
+// `import('./blog.type.mjs').BlogPost` (and re-exportable from a .d.ts).
+export {};

package/api/blog/detail/detail.d.mts

@@ -0,0 +1,9 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Read one post identified by slug (case-insensitive) via its .txt alternate.
+ * @param {string} slug
+ * @returns {Promise<import('../blog.type.mjs').BlogDetailResponse>}
+ */
+export function detail(slug: string): Promise<import("../blog.type.mjs").BlogDetailResponse>;

package/api/blog/detail/detail.mjs

@@ -14,15 +14,27 @@
  */
 
 import {AstryxError} from '../../error.mjs';
-import {ERROR_CODES} from '../../../lib/error-codes.mjs';
+import {ERROR_CODES} from '../../../foundation/response/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>}
+ * @returns {Promise<import('../blog.type.mjs').BlogDetailResponse>}
  */
 export async function detail(slug) {
+  // Validate the slug type before any network work — the dispatcher routes
+  // any truthy value here, and a public API caller (`@astryxdesign/cli/api`)
+  // could pass a non-string. Without this guard `slug.toLowerCase()` throws a
+  // raw TypeError with no `.code`, which the CLI downgrades to ERR_UNKNOWN.
+  if (typeof slug !== 'string') {
+    throw new AstryxError(
+      `Invalid blog slug: ${String(slug)}`,
+      [],
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+
   const {feedUrl, posts} = await loadFeed();
 
   const normalized = slug.toLowerCase();

package/api/blog/detail/detail.test.mjs

@@ -10,7 +10,7 @@
 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';
+import {SITE_URL} from '../_site.mjs';
 
 const FEED = `<?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
@@ -67,6 +67,23 @@ describe('blog.detail leaf', () => {
     expect(res.data.slug).toBe('how-astryx-works');
   });
 
+  it('throws a coded error (not a raw TypeError) for a non-string slug', async () => {
+    // The dispatcher routes any truthy value into detail(); a public API
+    // caller could pass a non-string. It must surface a coded AstryxError,
+    // not a raw TypeError that the CLI downgrades to ERR_UNKNOWN — and it must
+    // fail fast, before any network fetch.
+    for (const bad of [null, 42, {}, [1]]) {
+      await expect(detail(/** @type {any} */ (bad))).rejects.toBeInstanceOf(
+        AstryxError,
+      );
+      await expect(detail(/** @type {any} */ (bad))).rejects.toMatchObject({
+        code: 'ERR_INVALID_ARGUMENT',
+      });
+    }
+    // No feed fetch should have happened for the invalid inputs.
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
   it('throws ERR_UNKNOWN_POST with suggestions for a bad slug', async () => {
     await expect(detail('does-not-exist')).rejects.toMatchObject({
       code: 'ERR_UNKNOWN_POST',

package/api/blog/list/list.d.mts

@@ -0,0 +1,8 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * List posts from the feed.
+ * @returns {Promise<import('../blog.type.mjs').BlogListResponse>}
+ */
+export function list(): Promise<import("../blog.type.mjs").BlogListResponse>;

package/api/blog/list/list.mjs

@@ -16,7 +16,7 @@ import {loadFeed} from '../_adapter.mjs';
 
 /**
  * List posts from the feed.
- * @returns {Promise<import('../../../types/blog').BlogListResponse>}
+ * @returns {Promise<import('../blog.type.mjs').BlogListResponse>}
  */
 export async function list() {
   const data = await loadFeed();

package/api/blog/list/list.test.mjs

@@ -8,7 +8,7 @@
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {list} from './list.mjs';
-import {SITE_URL} from '../../../lib/site.mjs';
+import {SITE_URL} from '../_site.mjs';
 
 const FEED = `<?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">

package/api/build/build.d.mts

@@ -0,0 +1,19 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The page-building assistant. No query → the playbook signal; a query → the
+ * grouped composition kit.
+ *
+ * @param {string} [query] what you're building (e.g. "analytics dashboard")
+ * @param {{cwd?: string, type?: import('../search/search.type.mjs').SearchDomain, limit?: number}} [options]
+ * @returns {Promise<import('./build.type.mjs').BuildHelpResponse | import('./build.type.mjs').BuildKitResponse>}
+ */
+export function build(query?: string, options?: {
+    cwd?: string;
+    type?: import("../search/search.type.mjs").SearchDomain;
+    limit?: number;
+}): Promise<import("./build.type.mjs").BuildHelpResponse | import("./build.type.mjs").BuildKitResponse>;
+import { buildHelp } from './help/help.mjs';
+import { buildKit } from './kit/kit.mjs';
+export { buildHelp, buildKit };