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

package/api/component/_adapter.d.mts

@@ -68,6 +68,16 @@ export function requireCoreDir(cwd: string): string;
  * @returns {Promise<import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]>}
  */
 export function loadIntegrationsSafely(cwd: string): Promise<import("../../foundation/integrations/integrations.mjs").LoadedIntegration[]>;
+/**
+ * Read the exact installed version available to a package-qualified component
+ * selector. Legacy docs packages do not expose a reliable version here, so a
+ * version-qualified lookup never falls through to them.
+ * @param {string} coreDir
+ * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
+ * @param {string} packageName
+ * @returns {string|null}
+ */
+export function installedComponentPackageVersion(coreDir: string, loadedIntegrations: import("../../foundation/integrations/integrations.mjs").LoadedIntegration[], packageName: string): string | null;
 /**
  * Build the set of OWNER packages that provide a component with this name
  * across core + every loaded integration. This is what lets the CLI
@@ -180,6 +190,20 @@ export function scopeSubComponent(docs: LoadedComponentDoc, dirName: string, cor
     matchingComponent: any;
 } | null;
 export { CORE_PACKAGE };
+/**
+ * Internal ambiguity marker. Single-component callers still receive the same
+ * AstryxError code, message, and suggestions; batch callers can additionally
+ * project every installed candidate without parsing prose.
+ */
+export class ComponentAmbiguityError extends AstryxError {
+    /**
+     * @param {ComponentOwner[]} owners
+     * @param {string} dirName
+     */
+    constructor(owners: ComponentOwner[], dirName: string);
+    /** @type {import('./component.type.mjs').ComponentBatchCandidate[]} */
+    candidates: import("./component.type.mjs").ComponentBatchCandidate[];
+}
 /**
  * A loaded component doc. The shared validated loader accepts stamped and legacy
  * component docs; this loose view captures the fields the API reads across both.
@@ -258,3 +282,4 @@ export type ResolvedUnscopedDoc = {
     resolvedSourcePath: string | null;
 };
 import { CORE_PACKAGE } from '../../foundation/discovery/component-discovery.mjs';
+import { AstryxError } from '../error.mjs';

package/api/component/_adapter.mjs

@@ -18,6 +18,8 @@
  * deduped, so each leaf stays a thin projection.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {
   findCoreDir,
@@ -146,6 +148,34 @@ function findLoadedIntegration(loadedIntegrations, packageName) {
   return loadedIntegrations.find(i => i.name === packageName) ?? null;
 }
 
+/**
+ * Read the exact installed version available to a package-qualified component
+ * selector. Legacy docs packages do not expose a reliable version here, so a
+ * version-qualified lookup never falls through to them.
+ * @param {string} coreDir
+ * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
+ * @param {string} packageName
+ * @returns {string|null}
+ */
+export function installedComponentPackageVersion(
+  coreDir,
+  loadedIntegrations,
+  packageName,
+) {
+  if (packageName === CORE_PACKAGE) {
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(coreDir, 'package.json'), 'utf8'),
+      );
+      return typeof pkg.version === 'string' ? pkg.version : null;
+    } catch {
+      return null;
+    }
+  }
+  const integration = findLoadedIntegration(loadedIntegrations, packageName);
+  return typeof integration?.version === 'string' ? integration.version : null;
+}
+
 /**
  * Resolve an external package by name from the discovered externals list.
  * @param {string} packageName - e.g. '@acme/xds-widgets'
@@ -244,6 +274,34 @@ export function classifyScope(
   return {kind: 'legacy', ext};
 }
 
+/**
+ * Internal ambiguity marker. Single-component callers still receive the same
+ * AstryxError code, message, and suggestions; batch callers can additionally
+ * project every installed candidate without parsing prose.
+ */
+export class ComponentAmbiguityError extends AstryxError {
+  /** @type {import('./component.type.mjs').ComponentBatchCandidate[]} */
+  candidates;
+
+  /**
+   * @param {ComponentOwner[]} owners
+   * @param {string} dirName
+   */
+  constructor(owners, dirName) {
+    super(
+      `Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
+      owners.map(o => ({name: o.package, reason: 'provides this component'})),
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+    this.candidates = owners.map(owner => ({
+      package: owner.package,
+      component: dirName,
+      kind: 'component',
+      installed: true,
+    }));
+  }
+}
+
 /**
  * Refuse to guess when the name is owned by MORE THAN ONE package (core and/or
  * integrations) and the caller did not scope with --package. Legacy
@@ -254,11 +312,7 @@ export function classifyScope(
  */
 export function assertUnambiguousOwners(owners, dirName) {
   if (owners.length > 1) {
-    throw new AstryxError(
-      `Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
-      owners.map(o => ({name: o.package, reason: 'provides this component'})),
-      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
-    );
+    throw new ComponentAmbiguityError(owners, dirName);
   }
 }
 

package/api/component/component.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * @param {string} [name]
+ * @param {string|string[]} [name]
  * @param {object} [options]
  * @param {string} [options.cwd]
  * @param {boolean} [options.list]
@@ -18,6 +18,7 @@
  * @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
@@ -25,7 +26,7 @@
  *   | import('./component.type.mjs').ComponentDetailBlocksResponse
  * )>}
  */
-export function component(name?: string, options?: {
+export function component(name?: string | string[], options?: {
     cwd?: string | undefined;
     list?: boolean | undefined;
     category?: string | undefined;
@@ -38,4 +39,6 @@ export function component(name?: string, options?: {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
-}): Promise<(import("./component.type.mjs").ComponentListResponse | import("./component.type.mjs").ComponentDetailResponse | import("./component.type.mjs").ComponentDetailPropsResponse | import("./component.type.mjs").ComponentDetailSourceResponse | import("./component.type.mjs").ComponentDetailShowcaseResponse | import("./component.type.mjs").ComponentDetailBlocksResponse)>;
+}): 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 | import("./component.type.mjs").ComponentDetailShowcaseResponse | import("./component.type.mjs").ComponentDetailBlocksResponse)>;
+/** Maximum selectors accepted before any component resolution starts. */
+export const COMPONENT_BATCH_SELECTOR_LIMIT: 100;

package/api/component/component.doc.mjs

@@ -15,16 +15,16 @@ export const doc = {
   namespace: 'cli/api',
   displayName: 'component()',
   summary:
-    'Resolve a component by name, or list the catalog, with optional focused slices (props, source, showcase, blocks).',
+    'Resolve one or several components by name, or list the catalog, with optional focused slices (props, source, showcase, blocks).',
   description:
-    'Routes on its arguments: a name resolves that component across core and ' +
-    'integration packages and returns its authored ComponentDoc plus ownership ' +
-    'metadata; no name (or `list`/`category`) returns the catalog grouped by ' +
-    'category. Boolean flags narrow a single component to just its props, ' +
-    'source, showcase, or example blocks.',
+    'Routes on its arguments: one string resolves that component across core and ' +
+    'integration packages; an array returns one ordered result row per selector at ' +
+    'every array length; and no name returns the catalog grouped by category. ' +
+    'Boolean flags narrow each resolved component to just its props, source, ' +
+    'showcase, or example blocks.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'component(name?: string, options?: ComponentOptions): Promise<ComponentListResponse | ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse>',
+    'component(name?: string | string[], options?: ComponentOptions): Promise<ComponentListResponse | ComponentBatchResponse | ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse>',
   keywords: [
     'component',
     'components',
@@ -37,9 +37,9 @@ export const doc = {
   params: [
     {
       name: 'name',
-      type: 'string',
+      type: 'string | string[]',
       description:
-        "Component name to resolve (e.g. 'Button'). Omit to list the catalog.",
+        "Pass one selector string for the existing single-result response, or an array of at most 100 selectors for an ordered component.batch response. The limit counts duplicates in every projection mode. An array always requests a batch, including [] and ['Button']. Use 'Button', 'widgets/Button', '@acme/widgets/Button', or '@acme/widgets@1.2.3/Button'. A version applies to the package and must match the installed version. Omit the argument to list the catalog.",
     },
     {
       name: 'options.cwd',
@@ -112,6 +112,11 @@ export const doc = {
       description:
         "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
     },
+    {
+      type: 'component.batch',
+      description:
+        'An explicit selector array returns one ordered receipt at every array length: count and one results row per selector, including duplicates. ComponentBatchResponse specializes the shared BatchResponse and BatchRow types. Each row carries selector and status (found, not_found, ambiguous, or error); found rows carry the single-selector result, ambiguous rows carry installed candidates ({package, component, kind, installed}), and failed rows carry code, error, and optional suggestions.',
+    },
     {
       type: 'component.detail',
       description:
@@ -137,6 +142,10 @@ export const doc = {
     },
   ],
   throws: [
+    {
+      code: 'ERR_INVALID_ARGUMENT',
+      when: 'a selector array has more than 100 entries, a package-shaped selector has no component item, or its package conflicts with options.package',
+    },
     {
       code: 'ERR_INVALID_DETAIL',
       when: "options.detail is not 'full', 'compact', or 'brief'",
@@ -159,7 +168,7 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_PACKAGE',
-      when: 'options.package names a legacy external package that cannot be found',
+      when: 'options.package names a legacy external package that cannot be found, or a package-qualified selector requests a version that is not installed',
     },
     {
       code: 'ERR_NO_DOC',
@@ -179,6 +188,10 @@ export const doc = {
       label: 'Look up a component',
       code: "const r = await component('Button');",
     },
+    {
+      label: 'Look up several components',
+      code: "await component(['Button', 'Badge']);",
+    },
     {label: 'Props only', code: "await component('Button', {props: true});"},
     {
       label: 'Browse a category',

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