@astryxdesign/cli 0.6.4-canary.ed2e54e → 0.6.4

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 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.
+ * 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.
  *
  * Every leaf is also re-exported for direct scripting use.
  */
@@ -26,8 +26,6 @@ import {
   resolveUnscopedDoc,
   loadComponentDoc,
   scopeSubComponent,
-  ComponentAmbiguityError,
-  installedComponentPackageVersion,
 } from './_adapter.mjs';
 import {componentList} from './list/list.mjs';
 import {componentDetail} from './detail/detail.mjs';
@@ -36,199 +34,13 @@ 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 {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 {string} [name]
  * @param {object} [options]
  * @param {string} [options.cwd]
  * @param {boolean} [options.list]
@@ -244,7 +56,6 @@ async function componentBatch(selectors, options, coreDir) {
  * @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
@@ -268,16 +79,11 @@ 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).
-  // 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);
+  // Keeping this in sync with the CLI is what the API↔CLI parity test checks.
+  const isListView = list || category != null || !name;
   const detail = detailOption ?? (isListView ? 'brief' : 'full');
 
   // Same accepted values and codes as the CLI's --detail and --lang, checked
@@ -297,14 +103,6 @@ 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
@@ -318,46 +116,11 @@ 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 || noName) {
+  if (category || list || !name) {
     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(
@@ -423,10 +186,7 @@ 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,31 +28,6 @@ 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,9 +18,6 @@
  * 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
@@ -52,47 +49,6 @@
  * )} 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,78 +12,20 @@
  * configured" (`false`) from "configured but nothing discovered" (`true`),
  * which the list leaf surfaces as `meta`.
  *
- * @returns {Promise<{packages: ScannedPackage[], configured: boolean, project: Project}>}
+ * @returns {Promise<{packages: ScannedPackage[], configured: boolean}>}
  */
 export function discoverPackages(): Promise<{
     packages: ScannedPackage[];
     configured: boolean;
-    project: Project;
 }>;
 /**
- * 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
+ * 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
  * @returns {import('./discover.type.mjs').DiscoverListEntry}
  */
-export function toEntry(pkg: InstalledPackage & {
-    latest?: string;
-}): import("./discover.type.mjs").DiscoverListEntry;
+export function toEntry(pkg: ScannedPackage): import("./discover.type.mjs").DiscoverListEntry;
 /**
  * Locate a component's doc file within the given packages (case-insensitive).
  * @param {ScannedPackage[]} packages
@@ -104,56 +46,7 @@ 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}.
@@ -163,4 +56,3 @@ export type ComponentResolution = {
     docPath: string;
     componentName: string;
 };
-import { Project } from '../../foundation/config/project.mjs';