@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/api/discover/_catalog-view.d.mts

@@ -34,13 +34,17 @@ export function kindLists(contributions: CatalogPackage["contributions"]): Recor
  */
 export function hasKind(entry: Record<string, unknown>, kind: DiscoverKind): boolean;
 /**
- * Where a catalog package stands against the project.
+ * Where a catalog package stands against the project. An entry the official
+ * list supplied is checked against the project's own package.json
+ * (`officialDeclared`); any other entry against the folder discover runs in
+ * (`declared`).
  * @param {CatalogPackage} pkg
  * @param {Set<string>} installedNames
  * @param {Set<string>} declared
+ * @param {Set<string>} [officialDeclared]
  * @returns {{state: 'installed' | 'declared' | 'alias' | 'available', installedAs?: string}}
  */
-export function catalogState(pkg: CatalogPackage, installedNames: Set<string>, declared: Set<string>): {
+export function catalogState(pkg: CatalogPackage, installedNames: Set<string>, declared: Set<string>, officialDeclared?: Set<string>): {
     state: "installed" | "declared" | "alias" | "available";
     installedAs?: string;
 };
@@ -64,12 +68,18 @@ export function catalogEntry(pkg: CatalogPackage, version: string | undefined):
 };
 /**
  * What the project could add: every catalog package it does not have, once per
- * integration (the first name a source lists), never an alias of one it has.
+ * integration (the first name a source lists), never an alias of one it has,
+ * each with the command that adds it when `install` is given.
  * @param {CatalogResult} catalog
  * @param {InstalledPackage[]} installed
  * @param {Set<string>} declared
+ * @param {{officialDeclared?: Set<string>, install?: (pkg: CatalogPackage) => string}} [options]
  */
-export function availableEntries(catalog: CatalogResult, installed: InstalledPackage[], declared: Set<string>): {
+export function availableEntries(catalog: CatalogResult, installed: InstalledPackage[], declared: Set<string>, { officialDeclared, install }?: {
+    officialDeclared?: Set<string>;
+    install?: (pkg: CatalogPackage) => string;
+}): {
+    install?: string | undefined;
     source: string;
     aliases?: string[] | undefined;
     description?: string | undefined;
@@ -93,9 +103,10 @@ export function withLatest(installed: InstalledPackage[], catalog: CatalogResult
  * @param {InstalledPackage[]} installed
  * @param {CatalogResult} catalog
  * @param {Set<string>} declared
+ * @param {Set<string>} [officialDeclared]
  * @returns {SearchItem[]}
  */
-export function searchItems(installed: InstalledPackage[], catalog: CatalogResult, declared: Set<string>): SearchItem[];
+export function searchItems(installed: InstalledPackage[], catalog: CatalogResult, declared: Set<string>, officialDeclared?: Set<string>): SearchItem[];
 export type InstalledPackage = import("./_adapter.mjs").InstalledPackage;
 export type CatalogResult = import("./_adapter.mjs").CatalogResult;
 export type CatalogPackage = CatalogResult["packages"][number];

package/api/discover/_catalog-view.mjs

@@ -59,15 +59,24 @@ export function hasKind(entry, kind) {
 }
 
 /**
- * Where a catalog package stands against the project.
+ * Where a catalog package stands against the project. An entry the official
+ * list supplied is checked against the project's own package.json
+ * (`officialDeclared`); any other entry against the folder discover runs in
+ * (`declared`).
  * @param {CatalogPackage} pkg
  * @param {Set<string>} installedNames
  * @param {Set<string>} declared
+ * @param {Set<string>} [officialDeclared]
  * @returns {{state: 'installed' | 'declared' | 'alias' | 'available', installedAs?: string}}
  */
-export function catalogState(pkg, installedNames, declared) {
+export function catalogState(pkg, installedNames, declared, officialDeclared) {
   if (installedNames.has(pkg.package)) return {state: 'installed'};
-  if (declared.has(pkg.package)) return {state: 'declared'};
+  if (
+    (pkg.official && officialDeclared ? officialDeclared : declared).has(
+      pkg.package,
+    )
+  )
+    return {state: 'declared'};
   const installedAs = pkg.aliases.find(
     name => installedNames.has(name) || declared.has(name),
   );
@@ -103,18 +112,28 @@ export function catalogEntry(pkg, version) {
 
 /**
  * What the project could add: every catalog package it does not have, once per
- * integration (the first name a source lists), never an alias of one it has.
+ * integration (the first name a source lists), never an alias of one it has,
+ * each with the command that adds it when `install` is given.
  * @param {CatalogResult} catalog
  * @param {InstalledPackage[]} installed
  * @param {Set<string>} declared
+ * @param {{officialDeclared?: Set<string>, install?: (pkg: CatalogPackage) => string}} [options]
  */
-export function availableEntries(catalog, installed, declared) {
+export function availableEntries(
+  catalog,
+  installed,
+  declared,
+  {officialDeclared, install} = {},
+) {
   const installedNames = new Set(installed.map(p => p.name));
   /** @type {Set<string>} */
   const integrations = new Set();
   const entries = [];
   for (const pkg of catalog.packages) {
-    if (catalogState(pkg, installedNames, declared).state !== 'available')
+    if (
+      catalogState(pkg, installedNames, declared, officialDeclared).state !==
+      'available'
+    )
       continue;
     if (integrations.has(pkg.integration)) continue;
     integrations.add(pkg.integration);
@@ -124,6 +143,7 @@ export function availableEntries(catalog, installed, declared) {
       ...entry,
       ...(pkg.aliases.length > 0 ? {aliases: pkg.aliases} : {}),
       source: pkg.source,
+      ...(install ? {install: install(pkg)} : {}),
     });
   }
   return entries;
@@ -150,9 +170,10 @@ export function withLatest(installed, catalog) {
  * @param {InstalledPackage[]} installed
  * @param {CatalogResult} catalog
  * @param {Set<string>} declared
+ * @param {Set<string>} [officialDeclared]
  * @returns {SearchItem[]}
  */
-export function searchItems(installed, catalog, declared) {
+export function searchItems(installed, catalog, declared, officialDeclared) {
   /** @type {SearchItem[]} */
   const items = [];
   for (const pkg of installed) {
@@ -176,7 +197,10 @@ export function searchItems(installed, catalog, declared) {
   /** @type {Set<string>} */
   const integrations = new Set();
   for (const pkg of catalog.packages) {
-    if (catalogState(pkg, installedNames, declared).state !== 'available')
+    if (
+      catalogState(pkg, installedNames, declared, officialDeclared).state !==
+      'available'
+    )
       continue;
     if (integrations.has(pkg.integration)) continue;
     integrations.add(pkg.integration);

package/api/discover/detail/doc/doc.mjs

@@ -14,6 +14,7 @@
  */
 
 import {findComponent, loadValidatedDoc} from '../../_adapter.mjs';
+import {linkComponentResponse} from '../../../component/_adapter.mjs';
 import {levenshteinDistance} from '../../../../foundation/text/string-utils.mjs';
 import {AstryxError} from '../../../error.mjs';
 import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
@@ -27,7 +28,14 @@ import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
  * @returns {Promise<import('../../discover.type.mjs').DiscoverDetailDocResponse>}
  */
 export async function docFromResult(result, opts) {
-  return {type: 'discover.detail.doc', data: await loadValidatedDoc(result, opts)};
+  const data = await loadValidatedDoc(result, opts);
+  // Its `{@link}`s read as the commands that open their docs, as
+  // `astryx component` prints them (spec:AST-047 FR9).
+  const linked = await linkComponentResponse(
+    {type: 'component.detail', package: result.pkg.name, data},
+    process.cwd(),
+  );
+  return {type: 'discover.detail.doc', data: linked.data};
 }
 
 /**

package/api/discover/discover.d.mts

@@ -1,6 +1,16 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * Whether discover answers a query in this project, or answers every query
+ * with the list (spec:AST-051 FR1): it answers once the project loads an
+ * integration or has a discover source of its own. This is the rule
+ * `discover()` applies to the project it loads; the command reads it to keep
+ * the list's hints from suggesting queries that only return the list.
+ * @param {import('../../foundation/config/project.mjs').Project | undefined} project
+ * @returns {boolean}
+ */
+export function answersQueries(project: import("../../foundation/config/project.mjs").Project | undefined): boolean;
 /**
  * @param {string} [query]
  * @param {import('./discover.type.mjs').DiscoverOptions} [options]
@@ -13,3 +23,4 @@
  * >}
  */
 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 { OFFICIAL_SOURCE_NAME } from "./_adapter.mjs";

package/api/discover/discover.doc.mjs

@@ -14,13 +14,15 @@ export const doc = {
   namespace: 'cli/api',
   displayName: 'discover()',
   summary:
-    'Browse and search integrations: the ones a project has and, through discover sources, the ones it could add.',
+    'Browse and search integrations: the ones a project has and, through the official list and discover sources, the ones it could add.',
   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 ' +
+    'Lists the integrations a project loads and the official packages it declares, then the packages it could add: ' +
+    'the official Astryx packages first, from the list the CLI carries, then whatever the discover sources of the ' +
+    'project and its integrations list, 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.',
+    'package. Discover only reads: it prints the command that adds a package and never runs it.' +
+    " In global mode: with `cwd` outside a project, integrations installed next to this CLI package globally are listed as installed; inside a project, only the project's own are, and the compatible global ones are listed in `meta.available` with source `installed for this computer` and an `install` command. See {@link namespace:global} and {@link generic:computer-integrations}.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'discover(query?: string, options?: DiscoverOptions): Promise<DiscoverListResponse | DiscoverDetailResponse | DiscoverDetailDocResponse | DiscoverItemResponse | DiscoverSearchResponse>',
@@ -89,12 +91,12 @@ 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.',
+        'What the project has: the integrations it loads and the official packages it declares (name, category, components, version, and a list per other kind they add), official packages first. meta.available lists what the project could add, official packages first, each with the command that adds it; inside a project, an integration installed for the computer that the project does not install is listed there too, with source `installed for this computer` and the install command for the project in `install`. meta.sources reports each source, the official list last. When it lists no integration it carries meta.configured.',
     },
     {
       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.',
+        "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. An entry from the official list lists the newest release this CLI knows as latest and the project's Core version; its add command pins the project's Core version, else the Core range it declares (quoted), else the latest release. A version or item the official list does not show answers ERR_UNKNOWN_PACKAGE.",
     },
     {
       type: 'discover.detail.doc',
@@ -123,7 +125,7 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_PACKAGE',
-      when: 'neither the project nor any discover source has the package',
+      when: 'neither the project, the official list, nor any discover source has the package',
     },
     {
       code: 'ERR_UNKNOWN_COMPONENT',

package/api/discover/discover.mjs

@@ -4,7 +4,8 @@
  * @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.
+ * sources and the official list the CLI carries, 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:
  *
@@ -22,14 +23,20 @@
  *   the discover leaves.
  */
 
+export {OFFICIAL_SOURCE_NAME} from './_adapter.mjs';
 import {
   addCommand,
   callSources,
+  computerAvailableEntries,
   declaredDependencies,
   describeInstalled,
   discoverPackages,
   findComponent,
   hasSources,
+  officialDeclarations,
+  officialFirst,
+  officialList,
+  withDeclaredOfficial,
 } from './_adapter.mjs';
 import {
   availableEntries,
@@ -49,9 +56,6 @@ 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.
@@ -144,6 +148,23 @@ function similarItems(entry, wanted) {
   }));
 }
 
+/**
+ * Whether discover answers a query in this project, or answers every query
+ * with the list (spec:AST-051 FR1): it answers once the project loads an
+ * integration or has a discover source of its own. This is the rule
+ * `discover()` applies to the project it loads; the command reads it to keep
+ * the list's hints from suggesting queries that only return the list.
+ * @param {import('../../foundation/config/project.mjs').Project | undefined} project
+ * @returns {boolean}
+ */
+export function answersQueries(project) {
+  return (
+    project != null &&
+    (project.loadedIntegrations.some(i => !i.__loadError) ||
+      hasSources(project))
+  );
+}
+
 /**
  * @param {string} [query]
  * @param {import('./discover.type.mjs').DiscoverOptions} [options]
@@ -165,24 +186,62 @@ export async function discover(query, options = {}) {
       : undefined;
 
   const {packages: scanned, configured, project} = await discoverPackages();
-  const withSources = hasSources(project);
-  const packages = await describeInstalled(project, scanned);
+  const integrations = await describeInstalled(project, scanned);
   const declared = declaredDependencies(project);
+  // The official list is always read, so discover always has a source.
+  const official = officialList({project});
+  const declarations = officialDeclarations(project, official.packages);
   const add = addCommand(project);
+  const addOfficial = addCommand(project, {official: official.packages});
+  /** @param {{package: string, official?: true}} pkg */
+  const installFor = pkg => (pkg.official ? addOfficial : add)(pkg.package);
 
   /** @param {{package?: string, version?: string}} [request] */
-  const catalogFor = async request =>
-    withSources ? await callSources(project, request) : NO_CATALOG;
+  const catalogFor = request => callSources(project, request, {official});
+  /**
+   * What the project has, once a catalog says which official packages it
+   * declares.
+   * @param {import('./_adapter.mjs').CatalogResult} catalog
+   */
+  const installedFor = catalog =>
+    withDeclaredOfficial(
+      project,
+      integrations,
+      catalog,
+      declarations,
+      official.packages,
+    );
 
-  // No query, or nothing to look through: the list.
-  if (!query || (packages.length === 0 && !withSources)) {
-    if (!withSources) return list(packages, {configured, type, only});
+  // No query, or any query in a project that loads no integration and has no
+  // discover source of its own: the list (spec:AST-051 FR1).
+  if (!query || (integrations.length === 0 && !hasSources(project))) {
     const catalog = await catalogFor();
+    const packages = installedFor(catalog);
+    // Inside a project, the integrations installed for the computer are
+    // available, never loaded (spec AST-081 FR12).
+    const computer = await computerAvailableEntries(
+      project,
+      packages,
+      declared,
+      add,
+    );
+    const fromSources = officialFirst(
+      availableEntries(catalog, packages, declared, {
+        officialDeclared: declarations.any,
+        install: installFor,
+      }),
+      official.packages,
+      entry => entry.name,
+    );
+    const named = new Set(fromSources.map(entry => entry.name));
     return list(withLatest(packages, catalog), {
       configured,
       type,
       only,
-      available: availableEntries(catalog, packages, declared),
+      available: [
+        ...fromSources,
+        ...computer.filter(entry => !named.has(entry.name)),
+      ],
       sources: catalog.sources,
     });
   }
@@ -199,7 +258,6 @@ 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
@@ -207,29 +265,72 @@ export async function discover(query, options = {}) {
    * @param {import('./_adapter.mjs').CatalogResult} catalog
    */
   const packageView = async catalog => {
+    const packages = installedFor(catalog);
+    const installedNames = new Set(packages.map(p => p.name));
     const entry = catalog.packages.find(p => p.package === target.name);
     const installedAs = entry
-      ? catalogState(entry, installedNames, declared).installedAs
+      ? catalogState(entry, installedNames, declared, declarations.any)
+          .installedAs
       : undefined;
-    const context = {catalog: entry, version: target.version, add, installedAs};
+    const isIntegration = integrations.some(p => p.name === target.name);
+    // An entry only the official list supplies answers for what it lists.
+    // Any other version or item of that package keeps the answer discover
+    // gave before the list existed: ERR_UNKNOWN_PACKAGE.
+    const officialOnly = entry?.official === true && !isIntegration;
+    if (officialOnly && target.version) {
+      const local = packages.find(p => p.name === target.name)?.version;
+      if (
+        target.version !== local &&
+        !entry.versions.some(v => v.version === target.version)
+      ) {
+        throw new AstryxError(
+          `${target.name}@${target.version} is not a version discover knows here: ${
+            entry.versions.length > 0
+              ? `it knows ${entry.versions.map(v => v.version).join(', ')}`
+              : 'it knows no version of it for this project'
+          }. Other versions are on the package registry.`,
+          [...new Set([...entry.versions.map(v => v.version), local])]
+            .filter(v => v != null)
+            .map(v => ({
+              name: `${target.name}@${v}`,
+              reason: 'version discover knows',
+            })),
+          ERROR_CODES.ERR_UNKNOWN_PACKAGE,
+        );
+      }
+    }
+    const context = {
+      catalog: entry,
+      version: target.version,
+      // Only an entry the official list supplied gets a pinned version.
+      add: entry?.official ? addOfficial : add,
+      installedAs,
+    };
     if (!target.item) return detail(packages, target.name, context);
     const found = item(packages, target.name, target.item, context);
     if (found) return found;
+    if (officialOnly) {
+      throw new AstryxError(
+        `"${target.item}" not found in ${target.name}`,
+        similarItems(entry, target.item),
+        ERROR_CODES.ERR_UNKNOWN_PACKAGE,
+      );
+    }
     // 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)) {
+    if (entry && !isIntegration) {
       throw new AstryxError(
         `"${target.item}" not found in ${target.name}`,
         similarItems(entry, target.item),
         ERROR_CODES.ERR_UNKNOWN_COMPONENT,
       );
     }
-    return await doc(packages, target.name, target.item, {lang, zh});
+    return await doc(integrations, 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);
+  const installedPkg = integrations.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});
@@ -251,8 +352,9 @@ export async function discover(query, options = {}) {
     );
   }
 
+  const packages = installedFor(listing);
   return await search(packages, query, {
-    items: searchItems(packages, listing, declared),
+    items: searchItems(packages, listing, declared, declarations.any),
     type,
     only,
     limit: limit ?? DEFAULT_LIMIT,

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

@@ -7,25 +7,29 @@
 export type DiscoverListResponse = {
     type: "discover.list";
     /**
-     * The integrations the project loads.
+     * What the project has: the integrations
+     * it loads and the official packages it declares, official packages first.
      */
     data: DiscoverListEntry[];
     /**
      * Present when the list is empty, and
-     * whenever the project has a discover source.
+     * whenever discover has a source, which is always: the official list the CLI
+     * carries is one.
      */
     meta?: DiscoverListMeta | undefined;
 };
 export type DiscoverListMeta = {
     /**
-     * Present when `data` is empty, so callers can
+     * Present when `data` lists no integration (a
+     * declared official package is not one), 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.
+     * one entry per integration, never an alias of a package it has; official
+     * packages first.
      */
     available?: DiscoverAvailableEntry[] | undefined;
     /**
@@ -34,7 +38,7 @@ export type DiscoverListMeta = {
     sources?: DiscoverSourceState[] | undefined;
 };
 /**
- * An installed integration.
+ * An installed integration, or an official package the project declares.
  */
 export type DiscoverListEntry = {
     name: string;
@@ -89,14 +93,23 @@ export type DiscoverAvailableEntry = {
      */
     aliases?: string[] | undefined;
     /**
-     * The discover source that lists it.
+     * The discover source that lists it; `Astryx` for
+     * the official list; `installed for this computer` for an integration
+     * installed beside the CLI that the project does not install (spec AST-081
+     * FR12).
      */
     source: string;
+    /**
+     * The package-manager command that adds it to
+     * this project; discover prints it and never runs it.
+     */
+    install?: string | undefined;
 };
 export type DiscoverSourceState = {
     name: string;
     /**
-     * `astryx.config`, or the integration that exports it.
+     * `astryx.config`, the integration that exports it, or
+     * `@astryxdesign/cli` for the official list.
      */
     from: string;
     /**

package/api/discover/discover.type.mjs

@@ -21,23 +21,27 @@
  * astryx --json discover
  * @typedef {object} DiscoverListResponse
  * @property {'discover.list'} type
- * @property {DiscoverListEntry[]} data The integrations the project loads.
+ * @property {DiscoverListEntry[]} data What the project has: the integrations
+ *   it loads and the official packages it declares, official packages first.
  * @property {DiscoverListMeta} [meta] Present when the list is empty, and
- *   whenever the project has a discover source.
+ *   whenever discover has a source, which is always: the official list the CLI
+ *   carries is one.
  */
 
 /**
  * @typedef {object} DiscoverListMeta
- * @property {boolean} [configured] Present when `data` is empty, so callers can
+ * @property {boolean} [configured] Present when `data` lists no integration (a
+ *   declared official package is not one), 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.
+ *   one entry per integration, never an alias of a package it has; official
+ *   packages first.
  * @property {DiscoverSourceState[]} [sources] What each discover source did.
  */
 
 /**
- * An installed integration.
+ * An installed integration, or an official package the project declares.
  * @typedef {object} DiscoverListEntry
  * @property {string} name
  * @property {string} category
@@ -66,13 +70,19 @@
  * @property {string[]} [agentDocs]
  * @property {string} [description]
  * @property {string[]} [aliases] The integration's other package names.
- * @property {string} source The discover source that lists it.
+ * @property {string} source The discover source that lists it; `Astryx` for
+ *   the official list; `installed for this computer` for an integration
+ *   installed beside the CLI that the project does not install (spec AST-081
+ *   FR12).
+ * @property {string} [install] The package-manager command that adds it to
+ *   this project; discover prints it and never runs it.
  */
 
 /**
  * @typedef {object} DiscoverSourceState
  * @property {string} name
- * @property {string} from `astryx.config`, or the integration that exports it.
+ * @property {string} from `astryx.config`, the integration that exports it, or
+ *   `@astryxdesign/cli` for the official list.
  * @property {'fresh' | 'saved' | 'failed'} status `saved`: the live call
  *   failed and discover used the copy saved at `savedAt`.
  * @property {string} [generatedAt]

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

@@ -2,9 +2,10 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * 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,
+ * Build the discover.list response. `data` lists installed integrations and
+ * the official packages the project declares. A `data` with no integration
+ * 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.
  *

package/api/discover/list/list.mjs

@@ -12,9 +12,10 @@ import {toEntry} from '../_adapter.mjs';
 import {hasKind} from '../_catalog-view.mjs';
 
 /**
- * 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,
+ * Build the discover.list response. `data` lists installed integrations and
+ * the official packages the project declares. A `data` with no integration
+ * 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.
  *
@@ -31,18 +32,24 @@ import {hasKind} from '../_catalog-view.mjs';
 export function list(packages, {configured, available, sources, type, only}) {
   const keep = (/** @type {Record<string, unknown>} */ entry) =>
     type == null || hasKind(entry, type);
-  const data =
+  const shown =
     only === 'available'
       ? []
-      : packages
-          .map(toEntry)
-          .filter(entry =>
-            keep(/** @type {Record<string, unknown>} */ (entry)),
-          );
+      : packages.filter(pkg =>
+          keep(/** @type {Record<string, unknown>} */ (toEntry(pkg))),
+        );
+  const data = shown.map(toEntry);
 
   /** @type {Record<string, unknown>} */
   const meta = {};
-  if (data.length === 0) meta.configured = configured;
+  // An official package the project declares is not an integration, so it
+  // never hides whether any integration is configured.
+  if (
+    !shown.some(
+      pkg => !(/** @type {{declaredOfficial?: true}} */ (pkg).declaredOfficial),
+    )
+  )
+    meta.configured = configured;
   if (sources !== undefined) {
     meta.available = only === 'installed' ? [] : (available ?? []).filter(keep);
     meta.sources = sources;