@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/api/discover/detail/item/item.d.mts

@@ -0,0 +1,26 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Find one item of a package: an installed package's own templates, docs,
+ * themes, and codemods first, then what a discover source lists for the
+ * package. Returns null when neither has it, so the caller can report the
+ * component lookup's own error.
+ *
+ * @param {import('../../_adapter.mjs').InstalledPackage[]} packages
+ * @param {string} packageName
+ * @param {string} itemName
+ * @param {{
+ *   catalog?: import('../../_catalog-view.mjs').CatalogPackage,
+ *   version?: string,
+ *   add?: (name: string, version?: string) => string,
+ *   installedAs?: string,
+ * }} [options]
+ * @returns {import('../../discover.type.mjs').DiscoverItemResponse | null}
+ */
+export function item(packages: import("../../_adapter.mjs").InstalledPackage[], packageName: string, itemName: string, options?: {
+    catalog?: import("../../_catalog-view.mjs").CatalogPackage;
+    version?: string;
+    add?: (name: string, version?: string) => string;
+    installedAs?: string;
+}): import("../../discover.type.mjs").DiscoverItemResponse | null;

package/api/discover/detail/item/item.mjs

@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file discover.item leaf — one item a package adds, when it is not an
+ * installed component (those keep resolving to their full doc through
+ * ../doc).
+ *
+ * @position api/discover/detail/item — pure projection over the packages and
+ *   catalog entry resolved by ../../_adapter.
+ */
+
+import {KIND_FIELDS} from '../../_adapter.mjs';
+import {defaultVersion} from '../../_catalog-view.mjs';
+
+/**
+ * Find one item of a package: an installed package's own templates, docs,
+ * themes, and codemods first, then what a discover source lists for the
+ * package. Returns null when neither has it, so the caller can report the
+ * component lookup's own error.
+ *
+ * @param {import('../../_adapter.mjs').InstalledPackage[]} packages
+ * @param {string} packageName
+ * @param {string} itemName
+ * @param {{
+ *   catalog?: import('../../_catalog-view.mjs').CatalogPackage,
+ *   version?: string,
+ *   add?: (name: string, version?: string) => string,
+ *   installedAs?: string,
+ * }} [options]
+ * @returns {import('../../discover.type.mjs').DiscoverItemResponse | null}
+ */
+export function item(packages, packageName, itemName, options = {}) {
+  const {catalog, version, add, installedAs} = options;
+  const pkg = packages.find(p => p.name === packageName);
+  if (pkg && (!version || version === pkg.version)) {
+    for (const [kind, field] of KIND_FIELDS) {
+      if (kind === 'component') continue;
+      const names = /** @type {Record<string, unknown>} */ (pkg)[field];
+      if (Array.isArray(names) && names.includes(itemName)) {
+        return {
+          type: 'discover.item',
+          data: {
+            package: packageName,
+            ...(pkg.version ? {version: pkg.version} : {}),
+            kind,
+            name: itemName,
+            installed: true,
+          },
+        };
+      }
+    }
+  }
+
+  const lower = itemName.toLowerCase();
+  const found =
+    catalog?.contributions.find(c => c.name === itemName) ??
+    catalog?.contributions.find(c => c.name.toLowerCase() === lower);
+  if (!catalog || !found) return null;
+  const shown = version ?? defaultVersion(catalog);
+  return {
+    type: 'discover.item',
+    data: {
+      package: packageName,
+      ...(shown ? {version: shown} : {}),
+      kind: found.kind,
+      name: found.name,
+      ...(found.title ? {title: found.title} : {}),
+      ...(found.summary ? {summary: found.summary} : {}),
+      ...(found.keywords ? {keywords: found.keywords} : {}),
+      installed: pkg != null,
+      ...(pkg == null && installedAs ? {installedAs} : {}),
+      ...(pkg == null && !installedAs && add
+        ? {install: add(packageName, version)}
+        : {}),
+      source: catalog.source,
+    },
+  };
+}

package/api/discover/detail/item/item.test.mjs

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the discover.item leaf, a pure projection over installed
+ * packages and a source's catalog entry.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {item} from './item.mjs';
+
+/** @type {any[]} */
+const PACKAGES = [
+  {
+    name: '@acme/widgets',
+    category: '@acme/widgets',
+    version: '1.2.3',
+    components: ['Alpha'],
+    templates: ['pages/Home'],
+    docs: ['guide'],
+  },
+];
+
+/** @type {any} */
+const CATALOG = {
+  package: '@acme/charts',
+  integration: 'acme-charts',
+  aliases: [],
+  latest: '2.0.0',
+  source: 'Acme',
+  versions: [],
+  contributions: [{kind: 'template', name: 'pages/Report', title: 'Report page'}],
+};
+
+/** @param {string} name @param {string} [version] */
+const add = (name, version) => `pnpm add ${version ? `${name}@${version}` : name}`;
+
+describe('discover.item leaf', () => {
+  it("finds an installed package's own template, doc, theme, or codemod", () => {
+    expect(item(PACKAGES, '@acme/widgets', 'pages/Home')).toEqual({
+      type: 'discover.item',
+      data: {
+        package: '@acme/widgets',
+        version: '1.2.3',
+        kind: 'template',
+        name: 'pages/Home',
+        installed: true,
+      },
+    });
+  });
+
+  it('finds an item a source lists, with the command that adds its package', () => {
+    expect(
+      item(PACKAGES, '@acme/charts', 'pages/report', {catalog: CATALOG, add}),
+    ).toEqual({
+      type: 'discover.item',
+      data: {
+        package: '@acme/charts',
+        version: '2.0.0',
+        kind: 'template',
+        name: 'pages/Report',
+        title: 'Report page',
+        installed: false,
+        install: 'pnpm add @acme/charts',
+        source: 'Acme',
+      },
+    });
+  });
+
+  it('returns null when neither the project nor a source has it', () => {
+    expect(item(PACKAGES, '@acme/widgets', 'Nope')).toBeNull();
+    expect(item(PACKAGES, '@acme/charts', 'Nope', {catalog: CATALOG})).toBeNull();
+  });
+});

package/api/discover/discover.d.mts

@@ -3,19 +3,13 @@
 
 /**
  * @param {string} [query]
- * @param {object} [options]
- * @param {boolean} [options.components]
- * @param {string} [options.lang]
- * @param {boolean} [options.zh]
+ * @param {import('./discover.type.mjs').DiscoverOptions} [options]
  * @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?: {
-    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>;
+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>;

package/api/discover/discover.doc.mjs

@@ -13,22 +13,25 @@ export const doc = {
   name: 'discover',
   namespace: 'cli/api',
   displayName: 'discover()',
-  summary: 'Browse and search components from configured external packages.',
+  summary:
+    'Browse and search integrations: the ones a project has and, through discover sources, the ones it could add.',
   description:
-    '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.',
+    '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.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'discover(query?: string, options?: DiscoverOptions): Promise<DiscoverListResponse | DiscoverDetailResponse | DiscoverDetailDocResponse | DiscoverSearchResponse>',
+    'discover(query?: string, options?: DiscoverOptions): Promise<DiscoverListResponse | DiscoverDetailResponse | DiscoverDetailDocResponse | DiscoverItemResponse | DiscoverSearchResponse>',
   keywords: [
     'discover',
     'packages',
     'integrations',
     'external',
     'components',
+    'catalog',
+    'versions',
     'search',
   ],
   params: [
@@ -36,13 +39,39 @@ export const doc = {
       name: 'query',
       type: 'string',
       description:
-        'An @scope/name package, an @scope/name/Component path, or a free-text term. Omit to list all configured packages.',
+        'A package (@scope/name, optionally @version), an item path (@scope/name/<item>), or a free-text term. Omit to list packages.',
     },
     {
       name: 'options.components',
       type: 'boolean',
       description:
-        '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.',
+        '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',
     },
     {
       name: 'options.lang',
@@ -60,21 +89,27 @@ export const doc = {
     {
       type: 'discover.list',
       description:
-        'The configured external packages (name, category, components, version, description). When empty it carries meta.configured to distinguish "nothing configured" from "configured but nothing discovered".',
+        '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.',
     },
     {
       type: 'discover.detail',
-      description: 'A single package entry, for an @scope/name query.',
+      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.',
     },
     {
       type: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term that resolves to exactly one component.',
+        '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.',
     },
     {
       type: 'discover.search',
       description:
-        'The query echoed back plus the matching {package, component} pairs, when a free-text term matches several components.',
+        '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.',
     },
   ],
   throws: [
@@ -82,17 +117,21 @@ 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: 'the @scope/name package is not among the configured packages',
+      when: 'neither the project nor any discover source has the package',
     },
     {
       code: 'ERR_UNKNOWN_COMPONENT',
-      when: 'the component is not found in the named @scope/name package',
+      when: 'the item is not in the named package',
     },
     {
       code: 'ERR_NOT_FOUND',
-      when: 'a free-text term matches no component in any package',
+      when: 'a free-text term matches nothing, or the requested version is not published',
     },
     {
       code: 'ERR_INVALID_DOC',
@@ -100,10 +139,14 @@ export const doc = {
     },
   ],
   examples: [
-    {label: 'List packages', code: 'const {data} = await discover();'},
+    {label: 'List packages', code: 'const {data, meta} = 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: 'Free-text search', code: "await discover('button');"},
+    {
+      label: 'Search templates to add',
+      code: "await discover('dashboard', {type: 'template', available: true});",
+    },
   ],
   command: 'discover',
   related: ['component', 'search', 'template'],

package/api/discover/discover.mjs

@@ -3,55 +3,193 @@
 /**
  * @file Programmatic API for the discover command — dispatcher + barrel.
  *
- * `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()` 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.list        -> ./list/list.mjs
- *   discover.detail      -> ./detail/detail.mjs
- *   discover.detail.doc  -> ./detail/doc/doc.mjs
- *   discover.search      -> ./search/search.mjs
+ *   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)
  *
- * @position api/discover — thin router over ./_adapter + the discover leaves.
+ * 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.
  */
 
-import {discoverPackages} from './_adapter.mjs';
+import {
+  addCommand,
+  callSources,
+  declaredDependencies,
+  describeInstalled,
+  discoverPackages,
+  findComponent,
+  hasSources,
+} from './_adapter.mjs';
+import {
+  availableEntries,
+  catalogState,
+  searchItems,
+  withLatest,
+} from './_catalog-view.mjs';
 import {list} from './list/list.mjs';
 import {detail} from './detail/detail.mjs';
-import {doc} from './detail/doc/doc.mjs';
+import {doc, docFromResult} from './detail/doc/doc.mjs';
+import {item} from './detail/item/item.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 {object} [options]
- * @param {boolean} [options.components]
- * @param {string} [options.lang]
- * @param {boolean} [options.zh]
+ * @param {import('./discover.type.mjs').DiscoverOptions} [options]
  * @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} = options;
-  const {packages, configured} = await discoverPackages();
+  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);
 
-  // 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});
+  /** @param {{package?: string, version?: string}} [request] */
+  const catalogFor = async request =>
+    withSources ? await callSources(project, request) : NO_CATALOG;
 
-  // No query: the full package list.
-  if (!query) 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,
+    });
+  }
 
-  // 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.
+  // 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.
   if (typeof query !== 'string') {
     throw new AstryxError(
       `Invalid query "${String(query)}"`,
@@ -60,17 +198,63 @@ export async function discover(query, options = {}) {
     );
   }
 
-  // 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});
+  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,
+      );
     }
-    return detail(packages, query);
+    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}),
+    );
   }
 
-  // Free-text search across all packages.
-  return await search(packages, query, {lang, zh});
+  return await search(packages, query, {
+    items: searchItems(packages, listing, declared),
+    type,
+    only,
+    limit: limit ?? DEFAULT_LIMIT,
+  });
 }

package/api/discover/discover.test.mjs

@@ -68,10 +68,19 @@ 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.
+    // routing reaches the search leaf and projects its envelope. Search also
+    // matches package names, so the package itself is listed after them.
     const r = await discover('a');
     expect(r.type).toBe('discover.search');
-    expect(r.data.matches.map(m => m.component).sort()).toEqual(['Alpha', 'Beta']);
+    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,
+    });
   });
 
   it('free-text query with no match still routes to the search leaf (coded not-found)', async () => {