@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/README.md

@@ -403,7 +403,8 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                                                                    |
 | `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                                                                                       |
 | `docs.detail`                     | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                                                                                 |
-| `docs.detail.section`             | A single ReferenceSection of a topic: the first whose title contains the section query.                                                                                                                                                                                                       |
+| `docs.index`                      | One topic's section index (--index): each section's key, title, and one-line summary.                                                                                                                                                                                                         |
+| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined.                                                                                                                                                                                                        |
 | `blog.list`                       | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                                                                      |
 | `blog.detail`                     | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                                                                     |
 | `discover.list`                   | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                            |

package/api/build/build.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json build (no query) — the "how to build a page" playbook signal.
+ * astryx --json build (no query) — the "how to build a page" playbook signal.
  */
 export type BuildHelpResponse = {
     type: "build.help";
@@ -11,7 +11,7 @@ export type BuildHelpResponse = {
     };
 };
 /**
- * xds --json build "<idea>" — the composition kit for what you're building.
+ * astryx --json build "<idea>" — the composition kit for what you're building.
  *
  * Entries are raw `SearchResultEntry` objects (no package-manager-prefixed
  * command strings — the CLI adds those); `frame`/`foundation` are static

package/api/build/build.type.mjs

@@ -7,7 +7,7 @@
  */
 
 /**
- * xds --json build (no query) — the "how to build a page" playbook signal.
+ * astryx --json build (no query) — the "how to build a page" playbook signal.
  *
  * @typedef {object} BuildHelpResponse
  * @property {'build.help'} type
@@ -16,7 +16,7 @@
  */
 
 /**
- * xds --json build "<idea>" — the composition kit for what you're building.
+ * astryx --json build "<idea>" — the composition kit for what you're building.
  *
  * Entries are raw `SearchResultEntry` objects (no package-manager-prefixed
  * command strings — the CLI adds those); `frame`/`foundation` are static

package/api/component/component.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json component [--list] [--category X] [--detail names|compact|full]
+ * astryx --json component [--list] [--category X] [--detail names|compact|full]
  *
  * The list view emits ONE `component.list` type across all three detail levels;
  * the depth is carried in `data.detail` and `data.components` holds the grouped
@@ -55,7 +55,7 @@ export type ComponentBriefEntry = {
     import: string;
 };
 /**
- * xds --json component <name>
+ * astryx --json component <name>
  */
 export type ComponentDetailResponse = {
     type: "component.detail";
@@ -81,14 +81,14 @@ export type ComponentOwnership = {
     sourceAvailable: boolean;
 };
 /**
- * xds --json component <name> --props
+ * astryx --json component <name> --props
  */
 export type ComponentDetailPropsResponse = {
     type: "component.detail.props";
     data: import("@astryxdesign/cli/authoring").ComponentPropDoc[];
 };
 /**
- * xds --json component <name> --source
+ * astryx --json component <name> --source
  */
 export type ComponentDetailSourceResponse = {
     type: "component.detail.source";
@@ -98,7 +98,7 @@ export type ComponentDetailSourceResponse = {
     };
 };
 /**
- * xds --json component <name> --showcase
+ * astryx --json component <name> --showcase
  */
 export type ComponentDetailShowcaseResponse = {
     type: "component.detail.showcase";
@@ -109,7 +109,7 @@ export type ComponentDetailShowcaseResponse = {
     };
 };
 /**
- * xds --json component <name> --blocks
+ * astryx --json component <name> --blocks
  */
 export type ComponentDetailBlocksResponse = {
     type: "component.detail.blocks";

package/api/component/component.type.mjs

@@ -3,7 +3,7 @@
 /**
  * @file Colocated types for the `component` command — source of truth for the
  * component command's JSON responses. These typedefs describe the `{type, data}`
- * envelopes emitted by `xds --json component` and returned by the `component()`
+ * envelopes emitted by `astryx --json component` and returned by the `component()`
  * API; the `types/component.d.ts` barrel re-exports them for consumers.
  *
  * Detail-level contract for list views (brief < compact < full):
@@ -11,23 +11,23 @@
  *   --detail compact  Names + 1-line description + import path.
  *   --detail full     Full ComponentDoc per entry (props, theming, examples, etc.).
  *
- * Invocation                                 -> type discriminator
+ * Invocation                                      -> type discriminator
  * ------------------------------------------------------------------
- * xds --json component                      -> component.list (data.detail='names')
- * xds --json component --list               -> component.list (data.detail='names')
- * xds --json component --category Form      -> component.list (filtered)
- * xds --json component --list --detail compact -> component.list (data.detail='compact')
- * xds --json component --list --detail full -> component.list (data.detail='full')
- * xds --json component Button               -> component.detail
- * xds --json component Button --props       -> component.detail.props
- * xds --json component Button --source      -> component.detail.source
- * xds --json component Button --showcase    -> component.detail.showcase
- * xds --json component Button --blocks      -> component.detail.blocks
- * (not found)                               -> CLIError
+ * astryx --json component                         -> component.list (data.detail='names')
+ * astryx --json component --list                  -> component.list (data.detail='names')
+ * astryx --json component --category Form         -> component.list (filtered)
+ * astryx --json component --list --detail compact -> component.list (data.detail='compact')
+ * astryx --json component --list --detail full    -> component.list (data.detail='full')
+ * astryx --json component Button                  -> component.detail
+ * astryx --json component Button --props          -> component.detail.props
+ * astryx --json component Button --source         -> component.detail.source
+ * astryx --json component Button --showcase       -> component.detail.showcase
+ * astryx --json component Button --blocks         -> component.detail.blocks
+ * (not found)                                     -> CLIError
  */
 
 /**
- * xds --json component [--list] [--category X] [--detail names|compact|full]
+ * astryx --json component [--list] [--category X] [--detail names|compact|full]
  *
  * The list view emits ONE `component.list` type across all three detail levels;
  * the depth is carried in `data.detail` and `data.components` holds the grouped
@@ -70,7 +70,7 @@
  */
 
 /**
- * xds --json component <name>
+ * astryx --json component <name>
  * @typedef {object} ComponentDetailResponse
  * @property {'component.detail'} type
  * @property {import('@astryxdesign/cli/authoring').ComponentDoc & ComponentOwnership} data
@@ -87,28 +87,28 @@
  */
 
 /**
- * xds --json component <name> --props
+ * astryx --json component <name> --props
  * @typedef {object} ComponentDetailPropsResponse
  * @property {'component.detail.props'} type
  * @property {import('@astryxdesign/cli/authoring').ComponentPropDoc[]} data
  */
 
 /**
- * xds --json component <name> --source
+ * astryx --json component <name> --source
  * @typedef {object} ComponentDetailSourceResponse
  * @property {'component.detail.source'} type
  * @property {{component: string; source: string}} data
  */
 
 /**
- * xds --json component <name> --showcase
+ * astryx --json component <name> --showcase
  * @typedef {object} ComponentDetailShowcaseResponse
  * @property {'component.detail.showcase'} type
  * @property {{component: string; aspectRatio: number; source: string}} data
  */
 
 /**
- * xds --json component <name> --blocks
+ * astryx --json component <name> --blocks
  * @typedef {object} ComponentDetailBlocksResponse
  * @property {'component.detail.blocks'} type
  * @property {{component: string; showcase: BlockEntry | null; examples: BlockEntry[]; related: BlockEntry[]}} data

package/api/discover/discover.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverListResponse = {
     type: "discover.list";
@@ -25,21 +25,21 @@ export type DiscoverListEntry = {
     displayName?: string | undefined;
 };
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverDetailResponse = {
     type: "discover.detail";
     data: DiscoverListEntry;
 };
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverDetailDocResponse = {
     type: "discover.detail.doc";
     data: import("@astryxdesign/cli/authoring").ComponentDoc;
 };
 /**
- * xds --json discover <searchterm> (multiple matches)
+ * astryx --json discover <searchterm> (multiple matches)
  */
 export type DiscoverSearchResponse = {
     type: "discover.search";

package/api/discover/discover.type.mjs

@@ -6,16 +6,16 @@
  *
  * Invocation                                      -> type discriminator
  * ------------------------------------------------------------------
- * xds --json discover                            -> discover.list
- * xds --json discover @scope/name                -> discover.detail
- * xds --json discover @scope/name/Component      -> discover.detail.doc
- * xds --json discover <searchterm> (1 match)     -> discover.detail.doc
- * xds --json discover <searchterm> (N matches)   -> discover.search
- * (not found)                                    -> CLIError
+ * astryx --json discover                          -> discover.list
+ * astryx --json discover @scope/name              -> discover.detail
+ * astryx --json discover @scope/name/Component    -> discover.detail.doc
+ * astryx --json discover <searchterm> (1 match)   -> discover.detail.doc
+ * astryx --json discover <searchterm> (N matches) -> discover.search
+ * (not found)                                     -> CLIError
  */
 
 /**
- * xds --json discover
+ * astryx --json discover
  * @typedef {object} DiscoverListResponse
  * @property {'discover.list'} type
  * @property {DiscoverListEntry[]} data
@@ -35,21 +35,21 @@
  */
 
 /**
- * xds --json discover @scope/name
+ * astryx --json discover @scope/name
  * @typedef {object} DiscoverDetailResponse
  * @property {'discover.detail'} type
  * @property {DiscoverListEntry} data
  */
 
 /**
- * xds --json discover @scope/name/Component
+ * astryx --json discover @scope/name/Component
  * @typedef {object} DiscoverDetailDocResponse
  * @property {'discover.detail.doc'} type
  * @property {import('@astryxdesign/cli/authoring').ComponentDoc} data
  */
 
 /**
- * xds --json discover <searchterm> (multiple matches)
+ * astryx --json discover <searchterm> (multiple matches)
  * @typedef {object} DiscoverSearchResponse
  * @property {'discover.search'} type
  * @property {{query: string, matches: DiscoverSearchEntry[]}} data

package/api/docs/_adapter.d.mts

@@ -16,34 +16,43 @@
  */
 export function loadDocsCatalog(cwd?: string): Promise<DocsCatalog>;
 /**
- * @param {string} docPath
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ * The overlay languages a topic ships for its own file or any extension.
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {string[]}
  */
-export function loadReferenceDocs(docPath: string, { lang }?: {
-    lang?: string | null;
-}): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
+export function overlayLanguages(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): string[];
 /**
- * Load one catalog entry: its own doc, plus any extension an integration
- * merged onto it, in configuration order.
- *
- * A localization overlay applies to each file before the extensions are
- * merged, so an extension written in the base language stays readable under
- * `--dense`/`--zh` (it replaces its own sections and leaves the rest
- * translated) rather than being dropped.
- *
+ * One topic, lowered for `lang`: overlaid, extensions merged, keys stamped.
+ * Memoized per catalog, so a read that references a topic twice loads it once.
+ * Every read of the catalog shares the memoized node, so it is frozen; the
+ * lenses hand readers copies.
+ * @param {DocsCatalog} catalog
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
+ */
+export function lowerTopic(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
+/**
+ * How a token reference finds its target: the topic it names in `catalog`,
+ * lowered for the same language.
+ * @param {DocsCatalog} catalog
+ * @param {string | null} lang
+ * @returns {(topic: string) => Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode | null>}
+ */
+export function referenceTargets(catalog: DocsCatalog, lang: string | null): (topic: string) => Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode | null>;
+/**
+ * One topic, compiled for `lang`: lowered, then every token reference linked.
+ * @param {DocsCatalog} catalog
  * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
  */
-export function loadTopicDoc(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, { lang }?: {
-    lang?: string | null;
-}): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
+export function compileTopic(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
 /**
  * Resolve `topic` against the project's catalog (throwing `ERR_UNKNOWN_TOPIC`
- * when unmatched), and load it with any --dense/--zh overlay and any
- * integration extension applied. Shared by the detail and section leaves so
- * topic normalization and unknown-topic handling live in exactly one place.
+ * when unmatched) and lower it with any --dense/--zh overlay and any
+ * integration extension applied. Shared by the leaves so topic normalization
+ * and unknown-topic handling live in exactly one place.
  *
  * @param {string} topic
  * @param {object} [options]
@@ -53,7 +62,8 @@ export function loadTopicDoc(entry: import("../../foundation/discovery/docs-disc
  * @param {string} [options.cwd]
  * @returns {Promise<{
  *   catalog: DocsCatalog,
- *   docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
+ *   node: import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode,
+ *   lang: string | null,
  * }>}
  */
 export function resolveTopicDocs(topic: string, options?: {
@@ -63,6 +73,9 @@ export function resolveTopicDocs(topic: string, options?: {
     cwd?: string | undefined;
 }): Promise<{
     catalog: DocsCatalog;
-    docsData: import("./docs.type.mjs").DocsDetailResponse["data"];
+    node: import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode;
+    lang: string | null;
 }>;
+/** The localized overlays a docs read can apply. */
+export const OVERLAY_LANGUAGES: string[];
 import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';