@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/api/discover/detail/detail.mjs

@@ -1,33 +1,87 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file discover.detail leaf — browse one external package (@scope/name).
+ * @file discover.detail leaf — one package: what it adds, and, when a discover
+ * source knows it, every version and the latest one.
  *
- * @position api/discover/detail — pure projection over the packages resolved by
- *   ../_adapter; throws AstryxError (ERR_UNKNOWN_PACKAGE) for an unknown scope.
+ * @position api/discover/detail — pure projection over the packages and catalog
+ *   entry resolved by ../_adapter; throws AstryxError (ERR_UNKNOWN_PACKAGE) for
+ *   a package neither the project nor any source knows.
  */
 
 import {toEntry} from '../_adapter.mjs';
+import {catalogEntry, defaultVersion} from '../_catalog-view.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 
 /**
- * Build the discover.detail response for a scoped package name. Throws
- * AstryxError (ERR_UNKNOWN_PACKAGE) — with the available packages as
- * suggestions — when no package matches.
+ * Build the discover.detail response for one package. The project's installed
+ * copy describes itself; any other version is described by its source. For a
+ * package the project does not have, `install` is the package-manager command
+ * that adds it — printed, never run.
  *
- * @param {import('../_package-scanner.mjs').ScannedPackage[]} packages
- * @param {string} query scoped package name, e.g. `@scope/name`
+ * @param {import('../_adapter.mjs').InstalledPackage[]} packages
+ * @param {string} name package name, e.g. `@scope/name`
+ * @param {{
+ *   catalog?: import('../_catalog-view.mjs').CatalogPackage,
+ *   version?: string,
+ *   add?: (name: string, version?: string) => string,
+ *   installedAs?: string,
+ * }} [options]
  * @returns {import('../discover.type.mjs').DiscoverDetailResponse}
  */
-export function detail(packages, query) {
-  const pkg = packages.find(p => p.name === query);
-  if (!pkg) {
+export function detail(packages, name, options = {}) {
+  const {catalog, version, add, installedAs} = options;
+  const pkg = packages.find(p => p.name === name);
+  if (!pkg && !catalog) {
     throw new AstryxError(
-      `Package "${query}" not found`,
+      `Package "${name}" not found`,
       packages.map(p => ({name: p.name, reason: 'available package'})),
       ERROR_CODES.ERR_UNKNOWN_PACKAGE,
     );
   }
-  return {type: 'discover.detail', data: toEntry(pkg)};
+
+  const known = new Set([
+    ...(catalog?.versions.map(v => v.version) ?? []),
+    ...(pkg?.version ? [pkg.version] : []),
+  ]);
+  if (version && !known.has(version)) {
+    const releases = catalog?.versions.filter(v => !v.prerelease) ?? [];
+    throw new AstryxError(
+      `Version "${version}" of ${name} not found`,
+      (releases.length > 0 ? releases.map(v => v.version) : [...known])
+        .slice(0, 5)
+        .map(v => ({name: `${name}@${v}`, reason: 'published version'})),
+      ERROR_CODES.ERR_NOT_FOUND,
+    );
+  }
+
+  const local = pkg != null && (!version || version === pkg.version);
+  /** @type {Record<string, unknown>} */
+  const data = local
+    ? {...toEntry(pkg), installed: true}
+    : {
+        ...catalogEntry(
+          /** @type {NonNullable<typeof catalog>} */ (catalog),
+          version ?? defaultVersion(/** @type {NonNullable<typeof catalog>} */ (catalog)),
+        ),
+        installed: pkg != null,
+        ...(pkg?.version ? {installedVersion: pkg.version} : {}),
+      };
+  if (catalog) {
+    if (catalog.latest) data.latest = catalog.latest;
+    if (catalog.aliases.length > 0) data.aliases = catalog.aliases;
+    data.source = catalog.source;
+  }
+  if (!pkg) {
+    if (installedAs) data.installedAs = installedAs;
+    else if (add) data.install = add(name, version);
+  }
+  if (catalog) data.versions = catalog.versions;
+  return {
+    type: 'discover.detail',
+    data: /** @type {import('../discover.type.mjs').DiscoverDetailResponse['data']} */ (
+      data
+    ),
+  };
 }

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

@@ -36,6 +36,7 @@ describe('discover.detail leaf', () => {
       category: '@acme/widgets',
       components: ['Alpha', 'Beta'],
       version: '1.2.3',
+      installed: true,
     });
   });
 
@@ -55,3 +56,87 @@ describe('discover.detail leaf', () => {
     ]);
   });
 });
+
+describe('discover.detail leaf with a discover source', () => {
+  /** @type {any} */
+  const catalog = {
+    package: '@acme/charts',
+    integration: 'acme-charts',
+    aliases: ['@acme/charts-legacy'],
+    latest: '2.0.0',
+    source: 'Acme',
+    versions: [
+      {version: '2.1.0-beta.1', publishedAt: '2026-09-30T00:00:00.000Z', prerelease: true, status: 'ok'},
+      {version: '2.0.0', publishedAt: '2026-09-20T00:00:00.000Z', prerelease: false, status: 'ok'},
+      {version: '1.0.0', publishedAt: null, prerelease: false, status: 'manifest_load_error'},
+    ],
+    contributions: [
+      {kind: 'component', name: 'Chart'},
+      {kind: 'template', name: 'pages/Report'},
+    ],
+  };
+  /** @param {string} name @param {string} [version] */
+  const add = (name, version) => `pnpm add ${version ? `${name}@${version}` : name}`;
+
+  it('describes a package the project does not have, with the command that adds it', () => {
+    expect(detail(PACKAGES, '@acme/charts', {catalog, add}).data).toEqual({
+      name: '@acme/charts',
+      category: '@acme/charts',
+      components: ['Chart'],
+      version: '2.0.0',
+      templates: ['pages/Report'],
+      installed: false,
+      latest: '2.0.0',
+      aliases: ['@acme/charts-legacy'],
+      source: 'Acme',
+      install: 'pnpm add @acme/charts',
+      versions: catalog.versions,
+    });
+  });
+
+  it('describes any version, prereleases included', () => {
+    const {data} = detail(PACKAGES, '@acme/charts', {catalog, add, version: '2.1.0-beta.1'});
+    expect(data.version).toBe('2.1.0-beta.1');
+    expect(data.install).toBe('pnpm add @acme/charts@2.1.0-beta.1');
+  });
+
+  it('refuses a version that was never published, and suggests releases', () => {
+    let err;
+    try {
+      detail(PACKAGES, '@acme/charts', {catalog, add, version: '3.0.0'});
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(AstryxError);
+    expect(err.code).toBe('ERR_NOT_FOUND');
+    expect(err.suggestions.map(s => s.name)).toEqual([
+      '@acme/charts@2.0.0',
+      '@acme/charts@1.0.0',
+    ]);
+  });
+
+  it('names the package the project has instead of offering an alias', () => {
+    const {data} = detail(PACKAGES, '@acme/charts', {
+      catalog,
+      add,
+      installedAs: '@acme/charts-legacy',
+    });
+    expect(data.installedAs).toBe('@acme/charts-legacy');
+    expect(data).not.toHaveProperty('install');
+  });
+
+  it("keeps describing the installed copy from the project, with the source's versions", () => {
+    const {data} = detail(PACKAGES, '@acme/widgets', {
+      catalog: {...catalog, package: '@acme/widgets', latest: '1.3.0'},
+      add,
+    });
+    expect(data).toMatchObject({
+      name: '@acme/widgets',
+      components: ['Alpha', 'Beta'],
+      version: '1.2.3',
+      installed: true,
+      latest: '1.3.0',
+    });
+    expect(data).not.toHaveProperty('install');
+  });
+});

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

@@ -11,23 +11,27 @@ export const doc = {
   type: 'function',
   kind: 'api',
   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: [
@@ -35,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:
-        'List components only. A CLI display flag consumed by the renderer; the programmatic response shape 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',
@@ -59,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: [
@@ -81,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',
@@ -99,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'],