@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

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,26 @@
  *   --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')
+ * component([])                                  -> component.batch (data.count=0)
+ * component(['Button'])                          -> component.batch (data.count=1)
+ * astryx --json component Button Badge            -> component.batch
+ * 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
@@ -49,16 +52,58 @@
  * )} ComponentListData
  */
 
+/**
+ * `component(string[])` always returns this type, including empty and one-item
+ * arrays. The CLI returns it for two or more positional selectors.
+ * @typedef {import('../../foundation/response/batch.type.mjs').BatchResponse<
+ *   'component.batch',
+ *   ComponentSingleResponse,
+ *   ComponentBatchCandidate
+ * >} ComponentBatchResponse
+ */
+
+/**
+ * One installed component that makes an unqualified selector ambiguous.
+ * Keys match a component row in `discover.search` so a caller does not learn a
+ * second candidate shape.
+ * @typedef {object} ComponentBatchCandidate
+ * @property {string} package
+ * @property {string} component
+ * @property {'component'} kind
+ * @property {true} installed
+ */
+
+/**
+ * The response a successful single selector would have returned.
+ * @typedef {(
+ *   | ComponentDetailResponse
+ *   | ComponentDetailPropsResponse
+ *   | ComponentDetailSourceResponse
+ *   | ComponentDetailShowcaseResponse
+ *   | ComponentDetailBlocksResponse
+ * )} ComponentSingleResponse
+ */
+
+/**
+ * One row per requested selector, in argument order. Duplicate selectors keep
+ * duplicate rows.
+ * @typedef {import('../../foundation/response/batch.type.mjs').BatchRow<
+ *   ComponentSingleResponse,
+ *   ComponentBatchCandidate
+ * >} ComponentBatchResult
+ */
+
 /**
  * A single entry in a `component.list` group at `detail: 'names'`. Pre-1.0 the
  * list moved from bare strings to package-qualified objects so consumers can
- * disambiguate ownership (core vs. an integration package). Integration entries
- * carry `import` — the package-authored specifier; core entries omit it (the
- * specifier is derived from the component name by the renderer).
+ * disambiguate ownership (core vs. an integration package). Integration and
+ * legacy `astryx.docs` package entries carry `import` — the same specifier their
+ * `component.detail` reports; core entries omit it (the specifier is derived
+ * from the component name by the renderer).
  * @typedef {object} ComponentListEntry
  * @property {string} name
  * @property {string} package - Owner package, e.g. '@astryxdesign/core' or '@acme/astryx-meta'.
- * @property {string} [import] - Import specifier; present for integration components, absent for core.
+ * @property {string} [import] - Import specifier; present for integration and legacy package components, absent for core.
  */
 
 /**
@@ -70,10 +115,17 @@
  */
 
 /**
- * xds --json component <name>
+ * astryx --json component <name>
  * @typedef {object} ComponentDetailResponse
  * @property {'component.detail'} type
- * @property {import('@astryxdesign/cli/authoring').ComponentDoc & ComponentOwnership} data
+ * @property {import('@astryxdesign/cli/authoring').ComponentDoc & ComponentOwnership & ComponentDetailScope} data
+ */
+
+/**
+ * Present only when the requested name is a sub-component documented inside a
+ * parent's doc (e.g. `HStack` in the `Stack` doc); the payload is scoped to it.
+ * @typedef {object} ComponentDetailScope
+ * @property {string} [parentDoc] - Name of the parent doc the payload was scoped from, e.g. 'Stack'.
  */
 
 /**
@@ -87,28 +139,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/component/detail/blocks/blocks.d.mts

@@ -6,6 +6,7 @@
  * envelope, splitting them into the hero showcase, component-specific examples,
  * and broader related blocks.
  * @param {string} componentName
+ * @param {string} cwd - project to discover blocks from; never the process cwd
  * @returns {Promise<import('../../component.type.mjs').ComponentDetailBlocksResponse>}
  */
-export function componentDetailBlocks(componentName: string): Promise<import("../../component.type.mjs").ComponentDetailBlocksResponse>;
+export function componentDetailBlocks(componentName: string, cwd: string): Promise<import("../../component.type.mjs").ComponentDetailBlocksResponse>;

package/api/component/detail/blocks/blocks.mjs

@@ -3,7 +3,7 @@
 /**
  * @file `component.detail.blocks` leaf — a component's example/related blocks.
  *
- * @input  a component name
+ * @input  a component name + the project cwd
  * @output the `component.detail.blocks` envelope (showcase, examples, related)
  * @position api/component/detail/blocks (projection leaf; routed by component.mjs)
  */
@@ -16,10 +16,11 @@ import {findRelatedBlocks} from '../../../template/template.mjs';
  * envelope, splitting them into the hero showcase, component-specific examples,
  * and broader related blocks.
  * @param {string} componentName
+ * @param {string} cwd - project to discover blocks from; never the process cwd
  * @returns {Promise<import('../../component.type.mjs').ComponentDetailBlocksResponse>}
  */
-export async function componentDetailBlocks(componentName) {
-  const allBlocks = await findRelatedBlocks(componentName);
+export async function componentDetailBlocks(componentName, cwd) {
+  const allBlocks = await findRelatedBlocks(componentName, cwd);
   const toEntry = (/** @type {any} */ b) => ({
     name: b.dirName,
     displayName: b.name,

package/api/component/list/list.d.mts

@@ -1,11 +1,6 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * @typedef {import('../component.type.mjs').ComponentListResponse} ComponentListResponse
- * @typedef {import('../component.type.mjs').ComponentListEntry} ComponentListEntry
- * @typedef {import('../component.type.mjs').ComponentBriefEntry} ComponentBriefEntry
- */
 /**
  * Build the `component.list` envelope. The list taxonomy is collapsed: all
  * three detail levels emit ONE `component.list` type; the depth rides in

package/api/component/list/list.mjs

@@ -15,15 +15,16 @@ import {
   CORE_PACKAGE,
   discoverComponents,
   discoverExternalComponentsGrouped,
-  discoverIntegrationComponents,
+  discoverValidIntegrationComponents,
   findComponentReadme,
+  findExternalComponentDoc,
   resolveImportPath,
   resolveIntegrationImportPath,
 } from '../../../foundation/discovery/component-discovery.mjs';
 import {discoverExternalPackages} from '../../../foundation/fs/paths.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
-import {loadComponentDoc, loadIntegrationsSafely} from '../_adapter.mjs';
+import {loadComponentDoc, loadIntegrationsSafely, withOwnership} from '../_adapter.mjs';
 
 /**
  * @typedef {import('../component.type.mjs').ComponentListResponse} ComponentListResponse
@@ -31,6 +32,29 @@ import {loadComponentDoc, loadIntegrationsSafely} from '../_adapter.mjs';
  * @typedef {import('../component.type.mjs').ComponentBriefEntry} ComponentBriefEntry
  */
 
+/**
+ * The import a legacy `pkg.astryx.docs` component's detail reports, derived the
+ * same way (`withOwnership`) so list and detail agree.
+ * @param {{name: string, docsDir: string}} ext
+ * @param {string} name
+ * @param {string} coreDir
+ * @param {{zh: boolean, lang: string|null}} docOpts
+ * @returns {Promise<string>}
+ */
+async function legacyImport(ext, name, coreDir, docOpts) {
+  const docPath = findExternalComponentDoc(ext.docsDir, name);
+  /** @type {import('../_adapter.mjs').LoadedComponentDoc} */
+  let docs = {};
+  if (docPath && docPath.endsWith('.doc.mjs')) {
+    try {
+      docs = await loadComponentDoc(docPath, docOpts);
+    } catch {
+      // Keep list resilient; validation owns malformed docs.
+    }
+  }
+  return withOwnership(docs, {package: ext.name, sourcePath: null}, name, coreDir).import;
+}
+
 /**
  * Build the `component.list` envelope. The list taxonomy is collapsed: all
  * three detail levels emit ONE `component.list` type; the depth rides in
@@ -204,7 +228,8 @@ export async function componentList(
   const seenIntegration = new Set();
   for (const integration of loadedIntegrations) {
     seenIntegration.add(integration.name);
-    const owned = discoverIntegrationComponents(integration);
+    const {components: owned} =
+      await discoverValidIntegrationComponents(integration);
     // Group integration components by their doc `group`, falling back to the
     // package name. Keys are package-qualified so they never collide with
     // core groups or each other.
@@ -267,20 +292,24 @@ export async function componentList(
       k => grouped[k].length > 1 || grouped[k][0] !== k,
     );
 
-    if (hasGroups) {
-      for (const [group, members] of Object.entries(grouped)) {
-        listData[`${group} (${ext.name})`] = members.map(n => ({
+    /** @param {string[]} names */
+    const entriesFor = names =>
+      Promise.all(
+        names.map(async n => ({
           name: n,
           package: ext.name,
-        }));
+          import: await legacyImport(ext, n, coreDir, {zh, lang}),
+        })),
+      );
+
+    if (hasGroups) {
+      for (const [group, members] of Object.entries(grouped)) {
+        listData[`${group} (${ext.name})`] = await entriesFor(members);
       }
     } else {
       const allComps = Object.values(grouped).flat().sort();
       if (allComps.length > 0) {
-        listData[`${ext.category} (${ext.name})`] = allComps.map(n => ({
-          name: n,
-          package: ext.name,
-        }));
+        listData[`${ext.category} (${ext.name})`] = await entriesFor(allComps);
       }
     }
   }

package/api/discover/_adapter.d.mts

@@ -12,20 +12,78 @@
  * configured" (`false`) from "configured but nothing discovered" (`true`),
  * which the list leaf surfaces as `meta`.
  *
- * @returns {Promise<{packages: ScannedPackage[], configured: boolean}>}
+ * @returns {Promise<{packages: ScannedPackage[], configured: boolean, project: Project}>}
  */
 export function discoverPackages(): Promise<{
     packages: ScannedPackage[];
     configured: boolean;
+    project: Project;
 }>;
 /**
- * Project a scanned package into the discover list/detail entry shape. Shared
- * by the list and detail leaves so the entry keys (and their order) stay in one
- * place.
- * @param {ScannedPackage} pkg
+ * Every integration the project loads, with what it adds. An integration with
+ * no components root is included with `components: []`; one that failed to
+ * load is left out (the integration-issues nudge and Doctor report it).
+ *
+ * @param {Project | undefined} project
+ * @param {ScannedPackage[]} scanned the packages {@link discoverPackages} found
+ * @returns {Promise<InstalledPackage[]>}
+ */
+export function describeInstalled(project: Project | undefined, scanned: ScannedPackage[]): Promise<InstalledPackage[]>;
+/**
+ * Whether the project has any discover source: its own `discover` config field,
+ * or an integration's `discover` named export (valid or not).
+ * @param {Project | undefined} project
+ * @returns {boolean}
+ */
+export function hasSources(project: Project | undefined): boolean;
+/**
+ * Package names the project's package.json declares in any dependency field.
+ * @param {Project | undefined} project
+ * @returns {Set<string>}
+ */
+export function declaredDependencies(project: Project | undefined): Set<string>;
+/**
+ * The command that adds a package with the project's package manager. Discover
+ * only prints it; it never runs it.
+ * @param {Project | undefined} project
+ * @returns {(name: string, version?: string) => string}
+ */
+export function addCommand(project: Project | undefined): (name: string, version?: string) => string;
+/**
+ * The per-user cache directory the saved copies live in, never inside a
+ * project. Standard platform locations only.
+ * @returns {string}
+ */
+export function defaultCacheDir(): string;
+/**
+ * Call every discover source — the project's `discover` first, then each
+ * integration's in load order — once per distinct function. A source that
+ * throws, times out, or returns an invalid catalog falls back to its saved copy;
+ * with none, it is reported and adds nothing. The others always count.
+ *
+ * @param {Project | undefined} project
+ * @param {{package?: string, version?: string}} [request] ask for one package,
+ *   and optionally one version's contributions
+ * @param {{cacheDir?: string, timeoutMs?: number}} [options]
+ * @returns {Promise<CatalogResult>}
+ */
+export function callSources(project: Project | undefined, request?: {
+    package?: string;
+    version?: string;
+}, options?: {
+    cacheDir?: string;
+    timeoutMs?: number;
+}): Promise<CatalogResult>;
+/**
+ * Project a scanned or installed package into the discover list/detail entry
+ * shape. Shared by the list and detail leaves so the entry keys (and their
+ * order) stay in one place. A kind list appears only when it is not empty.
+ * @param {InstalledPackage & {latest?: string}} pkg
  * @returns {import('./discover.type.mjs').DiscoverListEntry}
  */
-export function toEntry(pkg: ScannedPackage): import("./discover.type.mjs").DiscoverListEntry;
+export function toEntry(pkg: InstalledPackage & {
+    latest?: string;
+}): import("./discover.type.mjs").DiscoverListEntry;
 /**
  * Locate a component's doc file within the given packages (case-insensitive).
  * @param {ScannedPackage[]} packages
@@ -46,7 +104,56 @@ export function loadValidatedDoc(result: ComponentResolution, { lang, zh }: {
     lang?: string | null;
     zh?: boolean;
 }): Promise<import("./discover.type.mjs").DiscoverDetailDocResponse["data"]>;
+/** The list and detail entry fields for each item kind, in display order. */
+export const KIND_FIELDS: readonly [readonly ["component", "components"], readonly ["template", "templates"], readonly ["doc", "docs"], readonly ["theme", "themes"], readonly ["codemod", "codemods"], readonly ["agent-doc", "agentDocs"]];
 export type ScannedPackage = import("./_package-scanner.mjs").ScannedPackage;
+export type DiscoverPackage = import("../../authoring/discover/type").DiscoverPackage;
+export type DiscoverSource = import("../../authoring/discover/type").DiscoverSource;
+/**
+ * An installed integration with what it adds, per kind. `components` is the
+ * scanned component list the discover leaves have always used.
+ */
+export type InstalledPackage = ScannedPackage & {
+    templates?: string[];
+    docs?: string[];
+    themes?: string[];
+    codemods?: string[];
+};
+/**
+ * What one source did on this run.
+ */
+export type SourceState = {
+    /**
+     * the source's own name, or where it came from when it
+     * gave none
+     */
+    name: string;
+    /**
+     * `astryx.config`, or the integration that exports it
+     */
+    from: string;
+    status: "fresh" | "saved" | "failed";
+    generatedAt?: string | undefined;
+    complete?: boolean | undefined;
+    /**
+     * when the saved copy in use was written
+     */
+    savedAt?: string | undefined;
+    /**
+     * why the live call failed
+     */
+    error?: string | undefined;
+};
+/**
+ * Everything every source returned, merged. When two sources list the same
+ * package, the earlier source's entry is kept.
+ */
+export type CatalogResult = {
+    sources: SourceState[];
+    packages: Array<DiscoverPackage & {
+        source: string;
+    }>;
+};
 /**
  * A located component doc within a scanned package — the shape returned by
  * {@link findComponent}, consumed by {@link loadValidatedDoc}.
@@ -56,3 +163,4 @@ export type ComponentResolution = {
     docPath: string;
     componentName: string;
 };
+import { Project } from '../../foundation/config/project.mjs';