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

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 () => {

package/api/discover/discover.type.d.mts

@@ -2,20 +2,40 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverListResponse = {
     type: "discover.list";
+    /**
+     * The integrations the project loads.
+     */
     data: DiscoverListEntry[];
     /**
-     * Present when the list is empty so
-     * callers can distinguish "no packages configured" from "configured but
-     * nothing discovered".
+     * Present when the list is empty, and
+     * whenever the project has a discover source.
+     */
+    meta?: DiscoverListMeta | undefined;
+};
+export type DiscoverListMeta = {
+    /**
+     * Present when `data` is empty, so callers can
+     * distinguish "no packages configured" from "configured but nothing
+     * discovered".
+     */
+    configured?: boolean | undefined;
+    /**
+     * What the project could add,
+     * one entry per integration, never an alias of a package it has.
      */
-    meta?: {
-        configured: boolean;
-    } | undefined;
+    available?: DiscoverAvailableEntry[] | undefined;
+    /**
+     * What each discover source did.
+     */
+    sources?: DiscoverSourceState[] | undefined;
 };
+/**
+ * An installed integration.
+ */
 export type DiscoverListEntry = {
     name: string;
     category: string;
@@ -23,34 +43,149 @@ export type DiscoverListEntry = {
     version?: string | undefined;
     description?: string | undefined;
     displayName?: string | undefined;
+    /**
+     * Template ids, when it adds any.
+     */
+    templates?: string[] | undefined;
+    /**
+     * Doc topic names, when it adds any.
+     */
+    docs?: string[] | undefined;
+    /**
+     * Theme slugs, when it adds any.
+     */
+    themes?: string[] | undefined;
+    /**
+     * `<version>/<id>`, when it adds any.
+     */
+    codemods?: string[] | undefined;
+    /**
+     * Agent guidance, when a source lists any.
+     */
+    agentDocs?: string[] | undefined;
+    /**
+     * The latest release a discover source knows.
+     */
+    latest?: string | undefined;
+};
+/**
+ * A package the project could add.
+ */
+export type DiscoverAvailableEntry = {
+    name: string;
+    /**
+     * Its latest release.
+     */
+    version?: string | undefined;
+    components: string[];
+    templates?: string[] | undefined;
+    docs?: string[] | undefined;
+    themes?: string[] | undefined;
+    codemods?: string[] | undefined;
+    agentDocs?: string[] | undefined;
+    description?: string | undefined;
+    /**
+     * The integration's other package names.
+     */
+    aliases?: string[] | undefined;
+    /**
+     * The discover source that lists it.
+     */
+    source: string;
+};
+export type DiscoverSourceState = {
+    name: string;
+    /**
+     * `astryx.config`, or the integration that exports it.
+     */
+    from: string;
+    /**
+     * `saved`: the live call
+     * failed and discover used the copy saved at `savedAt`.
+     */
+    status: "fresh" | "saved" | "failed";
+    generatedAt?: string | undefined;
+    complete?: boolean | undefined;
+    savedAt?: string | undefined;
+    error?: string | undefined;
 };
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverDetailResponse = {
     type: "discover.detail";
-    data: DiscoverListEntry;
+    /**
+     * `installed` says whether the project has the package;
+     * `installedVersion` is set when it has another version than the one shown.
+     * `install` is the package-manager command that adds a package the project
+     * does not have; discover prints it and never runs it. `installedAs` names
+     * the package the project has instead, when this one is an alias of it.
+     * `versions` (newest first) comes from a discover source.
+     */
+    data: DiscoverListEntry & {
+        installed: boolean;
+        installedVersion?: string;
+        aliases?: string[];
+        source?: string;
+        installedAs?: string;
+        install?: string;
+        versions?: import("../../authoring/discover/type").DiscoverVersion[];
+    };
 };
 /**
- * xds --json discover
+ * astryx --json discover
  */
 export type DiscoverDetailDocResponse = {
     type: "discover.detail.doc";
     data: import("@astryxdesign/cli/authoring").ComponentDoc;
 };
 /**
- * xds --json discover <searchterm> (multiple matches)
+ * astryx --json discover
+ */
+export type DiscoverItemResponse = {
+    type: "discover.item";
+    data: {
+        package: string;
+        version?: string;
+        kind: import("../../authoring/discover/type").DiscoverKind;
+        name: string;
+        title?: string;
+        summary?: string;
+        keywords?: string[];
+        installed: boolean;
+        installedAs?: string;
+        install?: string;
+        source?: string;
+    };
+};
+/**
+ * astryx --json discover <searchterm>
  */
 export type DiscoverSearchResponse = {
     type: "discover.search";
+    /**
+     *   `total` is set when `--limit` cut the list.
+     */
     data: {
         query: string;
         matches: DiscoverSearchEntry[];
+        total?: number;
     };
 };
 export type DiscoverSearchEntry = {
     package: string;
+    /**
+     * The item's name, for every kind; for a package
+     * match, the package name.
+     */
     component: string;
+    kind: import("../../authoring/discover/type").DiscoverKind | "package";
+    /**
+     * Whether the project has the package.
+     */
+    installed: boolean;
+    title?: string | undefined;
+    summary?: string | undefined;
 };
 /**
  * Options for `discover()`.
@@ -59,4 +194,8 @@ export type DiscoverOptions = {
     components?: boolean | undefined;
     lang?: string | undefined;
     zh?: boolean | undefined;
+    type?: import("@astryxdesign/cli/authoring").DiscoverKind | undefined;
+    installed?: boolean | undefined;
+    available?: boolean | undefined;
+    limit?: number | undefined;
 };

package/api/discover/discover.type.mjs

@@ -6,25 +6,38 @@
  *
  * Invocation                                      -> type discriminator
  * ------------------------------------------------------------------
- * xds --json discover                            -> discover.list
- * xds --json discover @scope/name                -> discover.detail
- * xds --json discover @scope/name/Component      -> discover.detail.doc
- * xds --json discover <searchterm> (1 match)     -> discover.detail.doc
- * xds --json discover <searchterm> (N matches)   -> discover.search
- * (not found)                                    -> CLIError
+ * astryx --json discover                          -> discover.list
+ * astryx --json discover @scope/name[@version]    -> discover.detail
+ * astryx --json discover @scope/name/Component    -> discover.detail.doc
+ * astryx --json discover @scope/name/<item>       -> discover.item
+ * astryx --json discover <searchterm>                -> discover.search
+ * (not found)                                     -> CLIError
+ *
+ * Fields added for discover sources are additive: every earlier field keeps
+ * its meaning.
  */
 
 /**
- * xds --json discover
+ * astryx --json discover
  * @typedef {object} DiscoverListResponse
  * @property {'discover.list'} type
- * @property {DiscoverListEntry[]} data
- * @property {{configured: boolean}} [meta] Present when the list is empty so
- *   callers can distinguish "no packages configured" from "configured but
- *   nothing discovered".
+ * @property {DiscoverListEntry[]} data The integrations the project loads.
+ * @property {DiscoverListMeta} [meta] Present when the list is empty, and
+ *   whenever the project has a discover source.
  */
 
 /**
+ * @typedef {object} DiscoverListMeta
+ * @property {boolean} [configured] Present when `data` is empty, so callers can
+ *   distinguish "no packages configured" from "configured but nothing
+ *   discovered".
+ * @property {DiscoverAvailableEntry[]} [available] What the project could add,
+ *   one entry per integration, never an alias of a package it has.
+ * @property {DiscoverSourceState[]} [sources] What each discover source did.
+ */
+
+/**
+ * An installed integration.
  * @typedef {object} DiscoverListEntry
  * @property {string} name
  * @property {string} category
@@ -32,33 +45,106 @@
  * @property {string} [version]
  * @property {string} [description]
  * @property {string} [displayName]
+ * @property {string[]} [templates] Template ids, when it adds any.
+ * @property {string[]} [docs] Doc topic names, when it adds any.
+ * @property {string[]} [themes] Theme slugs, when it adds any.
+ * @property {string[]} [codemods] `<version>/<id>`, when it adds any.
+ * @property {string[]} [agentDocs] Agent guidance, when a source lists any.
+ * @property {string} [latest] The latest release a discover source knows.
  */
 
 /**
- * xds --json discover @scope/name
+ * A package the project could add.
+ * @typedef {object} DiscoverAvailableEntry
+ * @property {string} name
+ * @property {string} [version] Its latest release.
+ * @property {string[]} components
+ * @property {string[]} [templates]
+ * @property {string[]} [docs]
+ * @property {string[]} [themes]
+ * @property {string[]} [codemods]
+ * @property {string[]} [agentDocs]
+ * @property {string} [description]
+ * @property {string[]} [aliases] The integration's other package names.
+ * @property {string} source The discover source that lists it.
+ */
+
+/**
+ * @typedef {object} DiscoverSourceState
+ * @property {string} name
+ * @property {string} from `astryx.config`, or the integration that exports it.
+ * @property {'fresh' | 'saved' | 'failed'} status `saved`: the live call
+ *   failed and discover used the copy saved at `savedAt`.
+ * @property {string} [generatedAt]
+ * @property {boolean} [complete]
+ * @property {string} [savedAt]
+ * @property {string} [error]
+ */
+
+/**
+ * astryx --json discover @scope/name[@version]
  * @typedef {object} DiscoverDetailResponse
  * @property {'discover.detail'} type
- * @property {DiscoverListEntry} data
+ * @property {DiscoverListEntry & {
+ *   installed: boolean,
+ *   installedVersion?: string,
+ *   aliases?: string[],
+ *   source?: string,
+ *   installedAs?: string,
+ *   install?: string,
+ *   versions?: import('../../authoring/discover/type').DiscoverVersion[],
+ * }} data `installed` says whether the project has the package;
+ *   `installedVersion` is set when it has another version than the one shown.
+ *   `install` is the package-manager command that adds a package the project
+ *   does not have; discover prints it and never runs it. `installedAs` names
+ *   the package the project has instead, when this one is an alias of it.
+ *   `versions` (newest first) comes from a discover source.
  */
 
 /**
- * xds --json discover @scope/name/Component
+ * astryx --json discover @scope/name/Component
  * @typedef {object} DiscoverDetailDocResponse
  * @property {'discover.detail.doc'} type
  * @property {import('@astryxdesign/cli/authoring').ComponentDoc} data
  */
 
 /**
- * xds --json discover <searchterm> (multiple matches)
+ * astryx --json discover @scope/name/<item>, for an item that is not an
+ * installed component.
+ * @typedef {object} DiscoverItemResponse
+ * @property {'discover.item'} type
+ * @property {{
+ *   package: string,
+ *   version?: string,
+ *   kind: import('../../authoring/discover/type').DiscoverKind,
+ *   name: string,
+ *   title?: string,
+ *   summary?: string,
+ *   keywords?: string[],
+ *   installed: boolean,
+ *   installedAs?: string,
+ *   install?: string,
+ *   source?: string,
+ * }} data
+ */
+
+/**
+ * astryx --json discover <searchterm>
  * @typedef {object} DiscoverSearchResponse
  * @property {'discover.search'} type
- * @property {{query: string, matches: DiscoverSearchEntry[]}} data
+ * @property {{query: string, matches: DiscoverSearchEntry[], total?: number}} data
+ *   `total` is set when `--limit` cut the list.
  */
 
 /**
  * @typedef {object} DiscoverSearchEntry
  * @property {string} package
- * @property {string} component
+ * @property {string} component The item's name, for every kind; for a package
+ *   match, the package name.
+ * @property {import('../../authoring/discover/type').DiscoverKind | 'package'} kind
+ * @property {boolean} installed Whether the project has the package.
+ * @property {string} [title]
+ * @property {string} [summary]
  */
 
 /**
@@ -67,6 +153,10 @@
  * @property {boolean} [components]
  * @property {string} [lang]
  * @property {boolean} [zh]
+ * @property {import('../../authoring/discover/type').DiscoverKind} [type]
+ * @property {boolean} [installed]
+ * @property {boolean} [available]
+ * @property {number} [limit]
  */
 
 export {};

package/api/discover/list/list.d.mts

@@ -2,14 +2,28 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * Build the discover.list response. An empty `packages` set produces the empty
- * envelope carrying `meta.configured`, so callers can distinguish "nothing
- * configured" from "configured but nothing discovered".
+ * Build the discover.list response. `data` lists installed integrations. An
+ * empty `data` carries `meta.configured`, so callers can distinguish "nothing
+ * configured" from "configured but nothing discovered". With discover sources,
+ * `meta.available` lists what the project could add and `meta.sources` reports
+ * what each source did.
  *
- * @param {import('../_package-scanner.mjs').ScannedPackage[]} packages
- * @param {{configured: boolean}} meta
+ * @param {Array<import('../_adapter.mjs').InstalledPackage & {latest?: string}>} packages
+ * @param {{
+ *   configured: boolean,
+ *   available?: Array<Record<string, unknown>>,
+ *   sources?: import('../_adapter.mjs').SourceState[],
+ *   type?: import('../../../authoring/discover/type').DiscoverKind,
+ *   only?: 'installed' | 'available',
+ * }} options
  * @returns {import('../discover.type.mjs').DiscoverListResponse}
  */
-export function list(packages: import("../_package-scanner.mjs").ScannedPackage[], { configured }: {
+export function list(packages: Array<import("../_adapter.mjs").InstalledPackage & {
+    latest?: string;
+}>, { configured, available, sources, type, only }: {
     configured: boolean;
+    available?: Array<Record<string, unknown>>;
+    sources?: import("../_adapter.mjs").SourceState[];
+    type?: import("../../../authoring/discover/type").DiscoverKind;
+    only?: "installed" | "available";
 }): import("../discover.type.mjs").DiscoverListResponse;

package/api/discover/list/list.mjs

@@ -1,26 +1,59 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file discover.list leaf — list the discovered external packages.
+ * @file discover.list leaf — the integrations the project has, and, when it has
+ * discover sources, the ones it could add.
  *
- * @position api/discover/list — pure projection of the packages resolved by
- *   ../_adapter into the discover.list envelope.
+ * @position api/discover/list — pure projection of the packages and catalog
+ *   resolved by ../_adapter into the discover.list envelope.
  */
 
 import {toEntry} from '../_adapter.mjs';
+import {hasKind} from '../_catalog-view.mjs';
 
 /**
- * Build the discover.list response. An empty `packages` set produces the empty
- * envelope carrying `meta.configured`, so callers can distinguish "nothing
- * configured" from "configured but nothing discovered".
+ * Build the discover.list response. `data` lists installed integrations. An
+ * empty `data` carries `meta.configured`, so callers can distinguish "nothing
+ * configured" from "configured but nothing discovered". With discover sources,
+ * `meta.available` lists what the project could add and `meta.sources` reports
+ * what each source did.
  *
- * @param {import('../_package-scanner.mjs').ScannedPackage[]} packages
- * @param {{configured: boolean}} meta
+ * @param {Array<import('../_adapter.mjs').InstalledPackage & {latest?: string}>} packages
+ * @param {{
+ *   configured: boolean,
+ *   available?: Array<Record<string, unknown>>,
+ *   sources?: import('../_adapter.mjs').SourceState[],
+ *   type?: import('../../../authoring/discover/type').DiscoverKind,
+ *   only?: 'installed' | 'available',
+ * }} options
  * @returns {import('../discover.type.mjs').DiscoverListResponse}
  */
-export function list(packages, {configured}) {
-  if (packages.length === 0) {
-    return {type: 'discover.list', data: [], meta: {configured}};
+export function list(packages, {configured, available, sources, type, only}) {
+  const keep = (/** @type {Record<string, unknown>} */ entry) =>
+    type == null || hasKind(entry, type);
+  const data =
+    only === 'available'
+      ? []
+      : packages
+          .map(toEntry)
+          .filter(entry =>
+            keep(/** @type {Record<string, unknown>} */ (entry)),
+          );
+
+  /** @type {Record<string, unknown>} */
+  const meta = {};
+  if (data.length === 0) meta.configured = configured;
+  if (sources !== undefined) {
+    meta.available = only === 'installed' ? [] : (available ?? []).filter(keep);
+    meta.sources = sources;
   }
-  return {type: 'discover.list', data: packages.map(toEntry)};
+  return Object.keys(meta).length > 0
+    ? {
+        type: 'discover.list',
+        data,
+        meta: /** @type {import('../discover.type.mjs').DiscoverListMeta} */ (
+          meta
+        ),
+      }
+    : {type: 'discover.list', data};
 }

package/api/discover/list/list.test.mjs

@@ -57,3 +57,49 @@ describe('discover.list leaf', () => {
     });
   });
 });
+
+describe('discover.list leaf with discover sources', () => {
+  const installed = [
+    pkg('@acme/widgets', ['Alpha'], {
+      version: '1.2.3',
+      latest: '1.3.0',
+      templates: ['pages/Home'],
+    }),
+  ];
+  const available = [
+    {name: '@acme/charts', version: '2.0.0', components: ['Chart'], source: 'Acme'},
+    {name: '@acme/themes', version: '1.0.0', components: [], themes: ['ocean'], source: 'Acme'},
+  ];
+  const sources = [{name: 'Acme', from: 'astryx.config', status: 'fresh'}];
+
+  it('lists what is installed in data and what could be added in meta', () => {
+    const res = list(installed, {configured: true, available, sources});
+    expect(res.data).toEqual([
+      {
+        name: '@acme/widgets',
+        category: '@acme/widgets',
+        components: ['Alpha'],
+        version: '1.2.3',
+        templates: ['pages/Home'],
+        latest: '1.3.0',
+      },
+    ]);
+    expect(res.meta).toEqual({available, sources});
+  });
+
+  it('keeps one side with only', () => {
+    expect(
+      list(installed, {configured: true, available, sources, only: 'installed'})
+        .meta?.available,
+    ).toEqual([]);
+    const res = list(installed, {configured: true, available, sources, only: 'available'});
+    expect(res.data).toEqual([]);
+    expect(res.meta).toEqual({configured: true, available, sources});
+  });
+
+  it('keeps only packages that add a kind with type', () => {
+    const res = list(installed, {configured: true, available, sources, type: 'theme'});
+    expect(res.data).toEqual([]);
+    expect(res.meta?.available?.map(e => e.name)).toEqual(['@acme/themes']);
+  });
+});

package/api/discover/search/search.d.mts

@@ -1,25 +1,27 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * @typedef {import('../_package-scanner.mjs').ScannedPackage} ScannedPackage
- */
 /**
  * Search all packages for `query` (a free-text term that never starts with
- * `@`). Resolves to a single component's docs when unambiguous, a search
- * response when several match, or throws AstryxError (ERR_NOT_FOUND) — with
- * fuzzy suggestions when any exist.
+ * `@`). Resolves to a search response when anything matches, even a single
+ * item or an exact component name, or throws AstryxError (ERR_NOT_FOUND) —
+ * with fuzzy suggestions when any exist.
  *
- * @param {ScannedPackage[]} packages
+ * @param {ScannedPackage[]} packages installed packages
  * @param {string} query
- * @param {{lang?: string | null, zh?: boolean}} opts
- * @returns {Promise<
- *   import('../discover.type.mjs').DiscoverDetailDocResponse |
- *   import('../discover.type.mjs').DiscoverSearchResponse
- * >}
+ * @param {{
+ *   items?: SearchItem[],
+ *   type?: import('../../../authoring/discover/type').DiscoverKind,
+ *   only?: 'installed' | 'available',
+ *   limit?: number,
+ * }} opts
+ * @returns {Promise<import('../discover.type.mjs').DiscoverSearchResponse>}
  */
-export function search(packages: ScannedPackage[], query: string, { lang, zh }: {
-    lang?: string | null;
-    zh?: boolean;
-}): Promise<import("../discover.type.mjs").DiscoverDetailDocResponse | import("../discover.type.mjs").DiscoverSearchResponse>;
+export function search(packages: ScannedPackage[], query: string, opts: {
+    items?: SearchItem[];
+    type?: import("../../../authoring/discover/type").DiscoverKind;
+    only?: "installed" | "available";
+    limit?: number;
+}): Promise<import("../discover.type.mjs").DiscoverSearchResponse>;
 export type ScannedPackage = import("../_package-scanner.mjs").ScannedPackage;
+export type SearchItem = import("../_catalog-view.mjs").SearchItem;