@astryxdesign/cli 0.6.4 → 0.6.5-canary.00f1ed9

package/api/component/component.mjs

@@ -4,10 +4,10 @@
  * @file Programmatic API for the component command — DISPATCHER + BARREL.
  *
  * Returns the same typed envelope { type, data } that `astryx --json component`
- * outputs. `component(name, opts)` parses the (name, options) pair, resolves the
- * subject once via `_adapter`, and routes to the correct leaf
- * (list · detail · detail.props/source/showcase/blocks), returning that leaf's
- * envelope. The CLI command handler is a thin wrapper around this function.
+ * outputs. `component(name, opts)` parses one selector or an ordered selector
+ * list, resolves each subject through `_adapter`, and routes to the correct leaf
+ * (list · detail · detail.props/source/showcase/blocks). The CLI command handler
+ * is a thin wrapper around this function.
  *
  * Every leaf is also re-exported for direct scripting use.
  */
@@ -26,6 +26,8 @@ import {
   resolveUnscopedDoc,
   loadComponentDoc,
   scopeSubComponent,
+  ComponentAmbiguityError,
+  installedComponentPackageVersion,
 } from './_adapter.mjs';
 import {componentList} from './list/list.mjs';
 import {componentDetail} from './detail/detail.mjs';
@@ -34,13 +36,199 @@ import {componentDetailSource} from './detail/source/source.mjs';
 import {componentDetailShowcase} from './detail/showcase/showcase.mjs';
 import {componentDetailBlocks} from './detail/blocks/blocks.mjs';
 
+/** Maximum selectors accepted before any component resolution starts. */
+export const COMPONENT_BATCH_SELECTOR_LIMIT = 100;
+
 /** @type {ReadonlyArray<string>} */
 const DETAIL_LEVELS = ['full', 'compact', 'brief'];
 /** @type {ReadonlyArray<string>} */
 const LANGS = ['en', 'zh', 'dense'];
+/** @type {Set<string>} */
+const NOT_FOUND_CODES = new Set([
+  ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+  ERROR_CODES.ERR_UNKNOWN_PACKAGE,
+  ERROR_CODES.ERR_NOT_FOUND,
+]);
+
+/**
+ * Discover-compatible package target grammar. Versions belong to the package
+ * head, never the item after the package slash.
+ * @param {string} selector
+ * @returns {{scoped: boolean, name: string, version?: string, item?: string}}
+ */
+function splitSelector(selector) {
+  const scoped = selector.startsWith('@');
+  const firstSlash = selector.indexOf('/');
+  let head = selector;
+  /** @type {string | undefined} */
+  let rest;
+  const split = scoped
+    ? firstSlash < 0
+      ? -1
+      : selector.indexOf('/', firstSlash + 1)
+    : firstSlash;
+  if (split > 0) {
+    head = selector.slice(0, split);
+    rest = selector.slice(split + 1) || undefined;
+  }
+  const at = head.indexOf('@', 1);
+  return {
+    scoped,
+    name: at > 0 ? head.slice(0, at) : head,
+    ...(at > 0 && head.slice(at + 1) ? {version: head.slice(at + 1)} : {}),
+    ...(rest ? {item: rest} : {}),
+  };
+}
+
+/**
+ * Resolve one component selector into the existing single-component API inputs.
+ * @param {unknown} value
+ * @param {string|undefined} packageScope
+ * @returns {{selector: string, name: string, package?: string, version?: string}}
+ */
+function parseComponentSelector(value, packageScope) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new AstryxError(
+      `Invalid component selector "${String(value)}"`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  const target = splitSelector(value);
+  const packageShaped =
+    target.scoped || target.item != null || target.version != null;
+  if (!packageShaped) {
+    return {selector: value, name: target.name, package: packageScope};
+  }
+  if (!target.item) {
+    throw new AstryxError(
+      `Component selector "${value}" names a package but no component`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  if (packageScope && packageScope !== target.name) {
+    throw new AstryxError(
+      `Component selector "${value}" conflicts with --package "${packageScope}"`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  return {
+    selector: value,
+    name: target.item,
+    package: target.name,
+    ...(target.version ? {version: target.version} : {}),
+  };
+}
+
+/**
+ * A version-qualified selector never falls through to another installed
+ * version. Its structured suggestion points at the command that can discover
+ * the requested package release.
+ * @param {{package?: string, version?: string}} target
+ * @param {string} coreDir
+ * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
+ * @returns {void}
+ */
+function requireInstalledSelectorVersion(target, coreDir, loadedIntegrations) {
+  if (!target.version) return;
+  const packageName = /** @type {string} */ (target.package);
+  const installed = installedComponentPackageVersion(
+    coreDir,
+    loadedIntegrations,
+    packageName,
+  );
+  if (installed === target.version) return;
+  const exact = `${packageName}@${target.version}`;
+  throw new AstryxError(
+    `Package "${exact}" is not installed`,
+    [
+      {
+        name: `astryx discover ${exact}`,
+        reason: 'look up this package version',
+      },
+    ],
+    ERROR_CODES.ERR_UNKNOWN_PACKAGE,
+  );
+}
+
+/**
+ * Turn a single-lookup failure into one complete batch row.
+ * @param {string} selector
+ * @param {unknown} error
+ * @returns {import('./component.type.mjs').ComponentBatchResult}
+ */
+function batchFailure(selector, error) {
+  const err =
+    error instanceof AstryxError
+      ? error
+      : new AstryxError(
+          error instanceof Error ? error.message : String(error),
+          undefined,
+          ERROR_CODES.ERR_UNKNOWN,
+        );
+  if (err instanceof ComponentAmbiguityError) {
+    return {
+      selector,
+      status: 'ambiguous',
+      code: err.code,
+      error: err.message,
+      candidates: err.candidates,
+    };
+  }
+  return {
+    selector,
+    status: NOT_FOUND_CODES.has(err.code) ? 'not_found' : 'error',
+    code: err.code,
+    error: err.message,
+    ...(err.suggestions ? {suggestions: err.suggestions} : {}),
+  };
+}
 
 /**
- * @param {string} [name]
+ * @param {unknown[]} selectors
+ * @param {object} options
+ * @param {string} options.cwd
+ * @param {string} [options.package]
+ * @param {boolean} [options.props]
+ * @param {boolean} [options.source]
+ * @param {boolean} [options.showcase]
+ * @param {boolean} [options.blocks]
+ * @param {'full'|'compact'|'brief'} [options.detail]
+ * @param {string|null} [options.lang]
+ * @param {boolean} [options.zh]
+ * @param {boolean} [options.dense]
+ * @param {string} coreDir
+ * @returns {Promise<import('./component.type.mjs').ComponentBatchResponse>}
+ */
+async function componentBatch(selectors, options, coreDir) {
+  const loadedIntegrations = await loadIntegrationsSafely(options.cwd);
+  /** @type {import('./component.type.mjs').ComponentBatchResult[]} */
+  const results = [];
+  for (const value of selectors) {
+    const selector = typeof value === 'string' ? value : String(value);
+    try {
+      const target = parseComponentSelector(value, options.package);
+      requireInstalledSelectorVersion(target, coreDir, loadedIntegrations);
+      const result =
+        /** @type {import('./component.type.mjs').ComponentSingleResponse} */ (
+          await component(target.name, {
+            ...options,
+            lang: options.lang ?? undefined,
+            package: target.package,
+          })
+        );
+      results.push({selector, status: 'found', result});
+    } catch (error) {
+      results.push(batchFailure(selector, error));
+    }
+  }
+  return {type: 'component.batch', data: {count: results.length, results}};
+}
+
+/**
+ * @param {string|string[]} [name]
  * @param {object} [options]
  * @param {string} [options.cwd]
  * @param {boolean} [options.list]
@@ -56,6 +244,7 @@ const LANGS = ['en', 'zh', 'dense'];
  * @param {boolean} [options.dense]
  * @returns {Promise<(
  *   import('./component.type.mjs').ComponentListResponse
+ *   | import('./component.type.mjs').ComponentBatchResponse
  *   | import('./component.type.mjs').ComponentDetailResponse
  *   | import('./component.type.mjs').ComponentDetailPropsResponse
  *   | import('./component.type.mjs').ComponentDetailSourceResponse
@@ -79,11 +268,16 @@ export async function component(name, options = {}) {
     dense = false,
   } = options;
 
+  const selectorList = Array.isArray(name) ? name : null;
+  const noName = selectorList == null && !name;
+
   // Default detail level mirrors the CLI (see commands/component/index.mjs):
   // single-component views default to 'full', list-style views (--list,
   // --category, or no name) default to 'brief' (scannable name lists).
-  // Keeping this in sync with the CLI is what the API↔CLI parity test checks.
-  const isListView = list || category != null || !name;
+  // An explicit array remains a batch even when it is empty or a caller also
+  // passes a list-only option.
+  const isListView =
+    selectorList == null && (list || category != null || noName);
   const detail = detailOption ?? (isListView ? 'brief' : 'full');
 
   // Same accepted values and codes as the CLI's --detail and --lang, checked
@@ -103,6 +297,14 @@ export async function component(name, options = {}) {
     );
   }
 
+  if (selectorList && selectorList.length > COMPONENT_BATCH_SELECTOR_LIMIT) {
+    throw new AstryxError(
+      `Component batch accepts at most ${COMPONENT_BATCH_SELECTOR_LIMIT} selectors; received ${selectorList.length}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+
   const coreDir = requireCoreDir(cwd);
 
   // A public API caller could pass a non-string category; the list leaf does
@@ -116,11 +318,46 @@ export async function component(name, options = {}) {
     );
   }
 
+  // ── Explicit batch selector list ─────────────────────────────────
+  // Array shape owns cardinality even if a caller also supplies a list-only
+  // option. The aggregate limit above is checked before core or integrations
+  // are resolved, so an oversized request can never emit a partial receipt.
+  if (selectorList) {
+    return componentBatch(
+      selectorList,
+      {
+        cwd,
+        package: packageScope,
+        props,
+        source,
+        showcase,
+        blocks,
+        detail,
+        lang,
+        zh,
+        dense,
+      },
+      coreDir,
+    );
+  }
+
   // ── List mode ──────────────────────────────────────────────────
-  if (category || list || !name) {
+  if (category || list || noName) {
     return componentList(coreDir, {cwd, category, detail, zh, dense, lang});
   }
 
+  if (typeof name === 'string') {
+    const target = parseComponentSelector(name, packageScope);
+    if (target.version) {
+      const loadedIntegrations = await loadIntegrationsSafely(cwd);
+      requireInstalledSelectorVersion(target, coreDir, loadedIntegrations);
+    }
+    if (target.name !== name || target.package !== packageScope) {
+      return component(target.name, {...options, package: target.package});
+    }
+    name = target.name;
+  }
+
   // ── Single component ───────────────────────────────────────────
   if (typeof name !== 'string') {
     throw new AstryxError(
@@ -186,7 +423,10 @@ export async function component(name, options = {}) {
     if (extDocPath) {
       // Legacy packages ship docs, never source.
       if (source) {
-        return componentDetailSource(dirName, null, {name, notFoundInPackage: packageScope});
+        return componentDetailSource(dirName, null, {
+          name,
+          notFoundInPackage: packageScope,
+        });
       }
       if (blocks) {
         return componentDetailBlocks(dirName, cwd);

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

@@ -28,6 +28,31 @@ export type ComponentListData = ({
     detail: "full";
     components: Record<string, import("@astryxdesign/cli/authoring").ComponentDoc[]>;
 });
+/**
+ * `component(string[])` always returns this type, including empty and one-item
+ * arrays. The CLI returns it for two or more positional selectors.
+ */
+export type ComponentBatchResponse = import("../../foundation/response/batch.type.mjs").BatchResponse<"component.batch", ComponentSingleResponse, ComponentBatchCandidate>;
+/**
+ * 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.
+ */
+export type ComponentBatchCandidate = {
+    package: string;
+    component: string;
+    kind: "component";
+    installed: true;
+};
+/**
+ * The response a successful single selector would have returned.
+ */
+export type ComponentSingleResponse = (ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse);
+/**
+ * One row per requested selector, in argument order. Duplicate selectors keep
+ * duplicate rows.
+ */
+export type ComponentBatchResult = import("../../foundation/response/batch.type.mjs").BatchRow<ComponentSingleResponse, ComponentBatchCandidate>;
 /**
  * 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

package/api/component/component.type.mjs

@@ -18,6 +18,9 @@
  * 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
@@ -49,6 +52,47 @@
  * )} 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

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';