@astryxdesign/cli 0.6.4-canary.ed2e54e → 0.6.4

package/api/discover/discover.d.mts

@@ -3,13 +3,19 @@
 
 /**
  * @param {string} [query]
- * @param {import('./discover.type.mjs').DiscoverOptions} [options]
+ * @param {object} [options]
+ * @param {boolean} [options.components]
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
  * @returns {Promise<
  *   import('./discover.type.mjs').DiscoverListResponse |
  *   import('./discover.type.mjs').DiscoverDetailResponse |
  *   import('./discover.type.mjs').DiscoverDetailDocResponse |
- *   import('./discover.type.mjs').DiscoverItemResponse |
  *   import('./discover.type.mjs').DiscoverSearchResponse
  * >}
  */
-export function discover(query?: string, options?: import("./discover.type.mjs").DiscoverOptions): Promise<import("./discover.type.mjs").DiscoverListResponse | import("./discover.type.mjs").DiscoverDetailResponse | import("./discover.type.mjs").DiscoverDetailDocResponse | import("./discover.type.mjs").DiscoverItemResponse | import("./discover.type.mjs").DiscoverSearchResponse>;
+export function discover(query?: string, options?: {
+    components?: boolean | undefined;
+    lang?: string | undefined;
+    zh?: boolean | undefined;
+}): Promise<import("./discover.type.mjs").DiscoverListResponse | import("./discover.type.mjs").DiscoverDetailResponse | import("./discover.type.mjs").DiscoverDetailDocResponse | import("./discover.type.mjs").DiscoverSearchResponse>;

package/api/discover/discover.doc.mjs

@@ -13,25 +13,22 @@ export const doc = {
   name: 'discover',
   namespace: 'cli/api',
   displayName: 'discover()',
-  summary:
-    'Browse and search integrations: the ones a project has and, through discover sources, the ones it could add.',
+  summary: 'Browse and search components from configured external packages.',
   description:
-    'Lists the integrations a project loads and, when the project or an integration provides a discover source, ' +
-    'the packages it could add, with what each one adds per kind. An @scope/name query shows one package with every ' +
-    'version its source knows; @scope/name@version shows one version; @scope/name/Component returns an installed ' +
-    "component's validated doc, and any other item path returns that item. A free-text term searches every item and " +
-    'package. Discover only reads: it prints the command that adds a package and never runs it.',
+    'Explores components contributed by configured external packages and integrations ' +
+    'the ones that declare a components root. With no query it lists those packages; ' +
+    'an @scope/name query browses one package; @scope/name/Component (or a free-text ' +
+    "term that resolves to a single component) returns that component's validated doc; " +
+    'a free-text term with several matches returns the candidate list.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'discover(query?: string, options?: DiscoverOptions): Promise<DiscoverListResponse | DiscoverDetailResponse | DiscoverDetailDocResponse | DiscoverItemResponse | DiscoverSearchResponse>',
+    'discover(query?: string, options?: DiscoverOptions): Promise<DiscoverListResponse | DiscoverDetailResponse | DiscoverDetailDocResponse | DiscoverSearchResponse>',
   keywords: [
     'discover',
     'packages',
     'integrations',
     'external',
     'components',
-    'catalog',
-    'versions',
     'search',
   ],
   params: [
@@ -39,39 +36,13 @@ export const doc = {
       name: 'query',
       type: 'string',
       description:
-        'A package (@scope/name, optionally @version), an item path (@scope/name/<item>), or a free-text term. Omit to list packages.',
+        'An @scope/name package, an @scope/name/Component path, or a free-text term. Omit to list all configured packages.',
     },
     {
       name: 'options.components',
       type: 'boolean',
       description:
-        'In the CLI package list, print every component, and every other item, of each package instead of the first 10. A display flag for the CLI renderer; the programmatic response is unchanged.',
-    },
-    {
-      name: 'options.type',
-      type: "'component' | 'template' | 'doc' | 'theme' | 'codemod' | 'agent-doc'",
-      description:
-        'Only one kind: in the list, packages that add it; in a search, items of that kind.',
-    },
-    {
-      name: 'options.installed',
-      type: 'boolean',
-      description:
-        'Only what the project has. Cannot be set with options.available.',
-      default: 'false',
-    },
-    {
-      name: 'options.available',
-      type: 'boolean',
-      description:
-        'Only what the project could add. Cannot be set with options.installed.',
-      default: 'false',
-    },
-    {
-      name: 'options.limit',
-      type: 'number',
-      description: 'Max number of search results, a positive integer.',
-      default: '20',
+        'In the CLI package list, print every component of each package instead of the first 10. A display flag for the CLI renderer; the programmatic response is unchanged.',
     },
     {
       name: 'options.lang',
@@ -89,27 +60,21 @@ export const doc = {
     {
       type: 'discover.list',
       description:
-        'The installed integrations (name, category, components, version, and a list per other kind they add). With a discover source, meta.available lists what the project could add and meta.sources reports each source. When the list is empty it carries meta.configured.',
+        'The configured external packages (name, category, components, version, description). When empty it carries meta.configured to distinguish "nothing configured" from "configured but nothing discovered".',
     },
     {
       type: 'discover.detail',
-      description:
-        'One package: what the shown version adds, whether the project has it, its versions and latest release when a source knows them, and the command that adds it when the project does not have it.',
+      description: 'A single package entry, for an @scope/name query.',
     },
     {
       type: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one installed component, for an @scope/name/Component query.',
-    },
-    {
-      type: 'discover.item',
-      description:
-        'One item that is not an installed component: its kind, name, the package and version that add it, and whether the project has the package.',
+        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term that resolves to exactly one component.',
     },
     {
       type: 'discover.search',
       description:
-        'The query echoed back plus every matching item and package, each with its kind and whether the project has it, even when one name matches exactly or only one item matches; total is set when the limit cut the list.',
+        'The query echoed back plus the matching {package, component} pairs, when a free-text term matches several components.',
     },
   ],
   throws: [
@@ -117,21 +82,17 @@ export const doc = {
       code: 'ERR_INVALID_ARGUMENT',
       when: 'the query is a non-string value, or a free-text search is run with an empty query',
     },
-    {
-      code: 'ERR_INVALID_OPTION',
-      when: 'options.type is not a known kind, options.limit is not a positive integer, or options.installed and options.available are both set',
-    },
     {
       code: 'ERR_UNKNOWN_PACKAGE',
-      when: 'neither the project nor any discover source has the package',
+      when: 'the @scope/name package is not among the configured packages',
     },
     {
       code: 'ERR_UNKNOWN_COMPONENT',
-      when: 'the item is not in the named package',
+      when: 'the component is not found in the named @scope/name package',
     },
     {
       code: 'ERR_NOT_FOUND',
-      when: 'a free-text term matches nothing, or the requested version is not published',
+      when: 'a free-text term matches no component in any package',
     },
     {
       code: 'ERR_INVALID_DOC',
@@ -139,14 +100,10 @@ export const doc = {
     },
   ],
   examples: [
-    {label: 'List packages', code: 'const {data, meta} = await discover();'},
+    {label: 'List packages', code: 'const {data} = await discover();'},
     {label: 'Browse a package', code: "await discover('@acme/ui');"},
-    {label: 'One version', code: "await discover('@acme/ui@2.1.0');"},
     {label: 'Show a component doc', code: "await discover('@acme/ui/Button');"},
-    {
-      label: 'Search templates to add',
-      code: "await discover('dashboard', {type: 'template', available: true});",
-    },
+    {label: 'Free-text search', code: "await discover('button');"},
   ],
   command: 'discover',
   related: ['component', 'search', 'template'],

package/api/discover/discover.mjs

@@ -3,193 +3,55 @@
 /**
  * @file Programmatic API for the discover command — dispatcher + barrel.
  *
- * `discover()` browses the integrations a project has and, through discover
- * sources, the ones it could add. It only reads: the package manager installs.
- * Its job is to resolve the project and its sources (via ./_adapter) and route
- * to the leaf that owns each response shape:
+ * `discover()` keeps the exact same signature and response union it always had,
+ * so `api/index.mjs` and the CLI consumer are untouched. Its only job now is to
+ * discover the external packages (via ./_adapter) and route to the leaf that
+ * owns each response shape:
  *
- *   discover                         -> ./list/list.mjs        discover.list
- *   discover <package>[@<version>]   -> ./detail/detail.mjs    discover.detail
- *   discover <package>/<Component>   -> ./detail/doc/doc.mjs   discover.detail.doc
- *   discover <package>/<item>        -> ./detail/item/item.mjs discover.item
- *   discover <words>                 -> ./search/search.mjs    discover.search (always a list)
+ *   discover.list        -> ./list/list.mjs
+ *   discover.detail      -> ./detail/detail.mjs
+ *   discover.detail.doc  -> ./detail/doc/doc.mjs
+ *   discover.search      -> ./search/search.mjs
  *
- * Source results are additive: they ride in `meta.available`/`meta.sources`,
- * in extra fields, or as extra search matches, so every existing field keeps
- * its meaning.
- *
- * @position api/discover — thin router over ./_adapter, ./_catalog-view, and
- *   the discover leaves.
+ * @position api/discover — thin router over ./_adapter + the discover leaves.
  */
 
-import {
-  addCommand,
-  callSources,
-  declaredDependencies,
-  describeInstalled,
-  discoverPackages,
-  findComponent,
-  hasSources,
-} from './_adapter.mjs';
-import {
-  availableEntries,
-  catalogState,
-  searchItems,
-  withLatest,
-} from './_catalog-view.mjs';
+import {discoverPackages} from './_adapter.mjs';
 import {list} from './list/list.mjs';
 import {detail} from './detail/detail.mjs';
-import {doc, docFromResult} from './detail/doc/doc.mjs';
-import {item} from './detail/item/item.mjs';
+import {doc} from './detail/doc/doc.mjs';
 import {search} from './search/search.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
-import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
-import {DISCOVER_KINDS} from '../../authoring/discover/parse.mjs';
-
-const DEFAULT_LIMIT = 20;
-
-/** @type {import('./_adapter.mjs').CatalogResult} */
-const NO_CATALOG = {sources: [], packages: []};
-
-/**
- * Split a package-shaped query: `name`, `name@version`, or `name/item`, with an
- * optional `@scope/` prefix on the name.
- * @param {string} query
- * @returns {{scoped: boolean, name: string, version?: string, item?: string}}
- */
-function splitTarget(query) {
-  const scoped = query.startsWith('@');
-  const firstSlash = query.indexOf('/');
-  let head = query;
-  /** @type {string | undefined} */
-  let rest;
-  const split = scoped
-    ? firstSlash < 0
-      ? -1
-      : query.indexOf('/', firstSlash + 1)
-    : firstSlash;
-  if (split > 0) {
-    head = query.slice(0, split);
-    rest = query.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} : {}),
-  };
-}
-
-/**
- * @param {{type?: unknown, installed?: boolean, available?: boolean, limit?: unknown}} options
- */
-function checkOptions({type, installed, available, limit}) {
-  if (
-    type != null &&
-    !(/** @type {readonly unknown[]} */ (DISCOVER_KINDS).includes(type))
-  ) {
-    throw new AstryxError(
-      `Unknown --type "${String(type)}"`,
-      DISCOVER_KINDS.map(kind => ({name: kind, reason: 'item kind'})),
-      ERROR_CODES.ERR_INVALID_OPTION,
-    );
-  }
-  if (installed && available) {
-    throw new AstryxError(
-      '--installed and --available cannot be used together',
-      undefined,
-      ERROR_CODES.ERR_INVALID_OPTION,
-    );
-  }
-  if (
-    limit != null &&
-    !(typeof limit === 'number' && Number.isInteger(limit) && limit > 0)
-  ) {
-    throw new AstryxError(
-      `--limit must be a positive integer, not "${String(limit)}"`,
-      undefined,
-      ERROR_CODES.ERR_INVALID_OPTION,
-    );
-  }
-}
-
-/**
- * Items a source lists for a package that look like the one asked for: names
- * that contain it, else the closest few by spelling.
- * @param {import('../../authoring/discover/type.js').DiscoverPackage} entry
- * @param {string} wanted
- * @returns {Array<{name: string, reason: string}>}
- */
-function similarItems(entry, wanted) {
-  const lower = wanted.toLowerCase();
-  const names = [...new Set(entry.contributions.map(c => c.name))];
-  const hits = names.filter(name => name.toLowerCase().includes(lower));
-  const picked =
-    hits.length > 0
-      ? hits.slice(0, 5)
-      : names
-          .map(name => ({
-            name,
-            distance: levenshteinDistance(lower, name.toLowerCase()),
-          }))
-          .filter(m => m.distance <= 3)
-          .sort((a, b) => a.distance - b.distance)
-          .slice(0, 5)
-          .map(m => m.name);
-  return picked.map(name => ({
-    name: `${entry.package}/${name}`,
-    reason: 'similar name',
-  }));
-}
 
 /**
  * @param {string} [query]
- * @param {import('./discover.type.mjs').DiscoverOptions} [options]
+ * @param {object} [options]
+ * @param {boolean} [options.components]
+ * @param {string} [options.lang]
+ * @param {boolean} [options.zh]
  * @returns {Promise<
  *   import('./discover.type.mjs').DiscoverListResponse |
  *   import('./discover.type.mjs').DiscoverDetailResponse |
  *   import('./discover.type.mjs').DiscoverDetailDocResponse |
- *   import('./discover.type.mjs').DiscoverItemResponse |
  *   import('./discover.type.mjs').DiscoverSearchResponse
  * >}
  */
 export async function discover(query, options = {}) {
-  const {lang = null, zh = false, type, limit} = options;
-  checkOptions(options);
-  const only = options.installed
-    ? /** @type {const} */ ('installed')
-    : options.available
-      ? /** @type {const} */ ('available')
-      : undefined;
-
-  const {packages: scanned, configured, project} = await discoverPackages();
-  const withSources = hasSources(project);
-  const packages = await describeInstalled(project, scanned);
-  const declared = declaredDependencies(project);
-  const add = addCommand(project);
+  const {lang = null, zh = false} = options;
+  const {packages, configured} = await discoverPackages();
 
-  /** @param {{package?: string, version?: string}} [request] */
-  const catalogFor = async request =>
-    withSources ? await callSources(project, request) : NO_CATALOG;
+  // No discoverable packages — either nothing configured, or configured but
+  // empty. The list leaf owns the empty envelope + `configured` flag. This
+  // short-circuits before query parsing, exactly as the flat command did.
+  if (packages.length === 0) return list(packages, {configured});
 
-  // No query, or nothing to look through: the list.
-  if (!query || (packages.length === 0 && !withSources)) {
-    if (!withSources) return list(packages, {configured, type, only});
-    const catalog = await catalogFor();
-    return list(withLatest(packages, catalog), {
-      configured,
-      type,
-      only,
-      available: availableEntries(catalog, packages, declared),
-      sources: catalog.sources,
-    });
-  }
+  // No query: the full package list.
+  if (!query) return list(packages, {configured});
 
-  // A non-string (truthy) query would crash the parsing below with a raw
-  // TypeError (no ERR_* code → downgrades to ERR_UNKNOWN). The CLI only ever
-  // passes a string, but the public API must fail with a code.
+  // A non-string (truthy) query would crash `.startsWith`/`.indexOf` below
+  // with a raw TypeError (no ERR_* code → downgrades to ERR_UNKNOWN). The CLI
+  // only ever passes a string, but the public API must fail with a code.
   if (typeof query !== 'string') {
     throw new AstryxError(
       `Invalid query "${String(query)}"`,
@@ -198,63 +60,17 @@ export async function discover(query, options = {}) {
     );
   }
 
-  const target = splitTarget(query);
-  const installedNames = new Set(packages.map(p => p.name));
-
-  /**
-   * One package, one version, or one item, once `target.name` is known to be
-   * a package the project or a source has.
-   * @param {import('./_adapter.mjs').CatalogResult} catalog
-   */
-  const packageView = async catalog => {
-    const entry = catalog.packages.find(p => p.package === target.name);
-    const installedAs = entry
-      ? catalogState(entry, installedNames, declared).installedAs
-      : undefined;
-    const context = {catalog: entry, version: target.version, add, installedAs};
-    if (!target.item) return detail(packages, target.name, context);
-    const found = item(packages, target.name, target.item, context);
-    if (found) return found;
-    // Only an installed package has docs to fall back to. For one that is
-    // only in a source, the item is what is unknown, not the package.
-    if (entry && !packages.some(p => p.name === target.name)) {
-      throw new AstryxError(
-        `"${target.item}" not found in ${target.name}`,
-        similarItems(entry, target.item),
-        ERROR_CODES.ERR_UNKNOWN_COMPONENT,
-      );
+  // Scoped package query: @scope/name or @scope/name/Component
+  if (query.startsWith('@')) {
+    const slashIdx = query.indexOf('/', query.indexOf('/') + 1);
+    if (slashIdx > 0) {
+      const pkgName = query.slice(0, slashIdx);
+      const compName = query.slice(slashIdx + 1);
+      return await doc(packages, pkgName, compName, {lang, zh});
     }
-    return await doc(packages, target.name, target.item, {lang, zh});
-  };
-
-  // An installed component keeps resolving to its full doc, before any source
-  // is asked anything.
-  const installedPkg = packages.find(p => p.name === target.name);
-  if (installedPkg && target.item && !target.version) {
-    const resolved = findComponent([installedPkg], target.item);
-    if (resolved) return await docFromResult(resolved, {lang, zh});
-  }
-
-  if (target.scoped) {
-    return await packageView(
-      await catalogFor({package: target.name, version: target.version}),
-    );
-  }
-
-  const listing = await catalogFor();
-  const isPackage =
-    installedPkg != null ||
-    listing.packages.some(p => p.package === target.name);
-  if (isPackage && (target.version || target.item || target.name === query)) {
-    return await packageView(
-      await catalogFor({package: target.name, version: target.version}),
-    );
+    return detail(packages, query);
   }
 
-  return await search(packages, query, {
-    items: searchItems(packages, listing, declared),
-    type,
-    only,
-    limit: limit ?? DEFAULT_LIMIT,
-  });
+  // Free-text search across all packages.
+  return await search(packages, query, {lang, zh});
 }

package/api/discover/discover.test.mjs

@@ -68,19 +68,10 @@ describe('discover() dispatcher routing', () => {
   it('free-text query with multiple matches -> discover.search envelope', async () => {
     // 'a' is a substring of both Alpha and Beta (no exact match), so the search
     // leaf returns the multi-match discover.search envelope. Proves free-text
-    // routing reaches the search leaf and projects its envelope. Search also
-    // matches package names, so the package itself is listed after them.
+    // routing reaches the search leaf and projects its envelope.
     const r = await discover('a');
     expect(r.type).toBe('discover.search');
-    expect(
-      r.data.matches.filter(m => m.kind === 'component').map(m => m.component),
-    ).toEqual(['Alpha', 'Beta']);
-    expect(r.data.matches).toContainEqual({
-      package: '@acme/widgets',
-      component: '@acme/widgets',
-      kind: 'package',
-      installed: true,
-    });
+    expect(r.data.matches.map(m => m.component).sort()).toEqual(['Alpha', 'Beta']);
   });
 
   it('free-text query with no match still routes to the search leaf (coded not-found)', async () => {