@astryxdesign/cli 0.6.3-canary.95336a1 → 0.6.3-canary.9c4d44d

package/README.md

@@ -82,7 +82,7 @@ Options:
 | `blog`        | Read the Astryx blog from the published feed                                  |
 | `build`       | Build a page: the template to start from, or the workflow playbook (no query) |
 | `component`   | List components or print component docs                                       |
-| `discover`    | Discover external packages and components                                     |
+| `discover`    | Browse and search integrations: the ones you have and the ones you could add  |
 | `docs`        | Print reference docs                                                          |
 | `doctor`      | Diagnose Astryx projects and integration packages                             |
 | `gap-report`  | Route a design-system gap to its owning package                               |
@@ -435,10 +435,11 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `docs.node`                       | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names).                                                                                                                           |
 | `blog.list`                       | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                                                                                                                                                                                                                   |
 | `blog.detail`                     | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                                                                                                                                                                                                                  |
-| `discover.list`                   | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                                                                                                                                                                         |
-| `discover.detail`                 | A single external package entry, for an @scope/name query.                                                                                                                                                                                                                                                                                                                                                                                 |
-| `discover.detail.doc`             | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                                                                                                                                                                                                                             |
-| `discover.search`                 | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                                                                                                                                                                                                                           |
+| `discover.list`                   | The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                   |
+| `discover.detail`                 | One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it.                                                                                                                                                                                                                   |
+| `discover.detail.doc`             | The validated ComponentDoc for one installed component, for an @scope/name/Component query.                                                                                                                                                                                                                                                                                                                                                |
+| `discover.item`                   | One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package.                                                                                                                                                                                                                                                                                   |
+| `discover.search`                 | The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list.                                                                                                                                                                                                                                          |
 | `search`                          | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title, parent (the command that opens the level above), package (for a docs-tree hit), and, for a hit on one section, section (docs), or displayName and kind (templates).                                        |
 | `build.help`                      | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation.                                                                                                                                                              |
 | `build.kit`                       | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, command, basis, reason, alternatives, ...}, pages (search's closest templates), blocks and domain as SearchResultEntry[], frame, foundation, and hint {reason, commands} when thin.                                                                                                                                         |

package/api/discover/_adapter.d.mts

@@ -12,20 +12,78 @@
  * configured" (`false`) from "configured but nothing discovered" (`true`),
  * which the list leaf surfaces as `meta`.
  *
- * @returns {Promise<{packages: ScannedPackage[], configured: boolean}>}
+ * @returns {Promise<{packages: ScannedPackage[], configured: boolean, project: Project}>}
  */
 export function discoverPackages(): Promise<{
     packages: ScannedPackage[];
     configured: boolean;
+    project: Project;
 }>;
 /**
- * Project a scanned package into the discover list/detail entry shape. Shared
- * by the list and detail leaves so the entry keys (and their order) stay in one
- * place.
- * @param {ScannedPackage} pkg
+ * Every integration the project loads, with what it adds. An integration with
+ * no components root is included with `components: []`; one that failed to
+ * load is left out (the integration-issues nudge and Doctor report it).
+ *
+ * @param {Project | undefined} project
+ * @param {ScannedPackage[]} scanned the packages {@link discoverPackages} found
+ * @returns {Promise<InstalledPackage[]>}
+ */
+export function describeInstalled(project: Project | undefined, scanned: ScannedPackage[]): Promise<InstalledPackage[]>;
+/**
+ * Whether the project has any discover source: its own `discover` config field,
+ * or an integration's `discover` named export (valid or not).
+ * @param {Project | undefined} project
+ * @returns {boolean}
+ */
+export function hasSources(project: Project | undefined): boolean;
+/**
+ * Package names the project's package.json declares in any dependency field.
+ * @param {Project | undefined} project
+ * @returns {Set<string>}
+ */
+export function declaredDependencies(project: Project | undefined): Set<string>;
+/**
+ * The command that adds a package with the project's package manager. Discover
+ * only prints it; it never runs it.
+ * @param {Project | undefined} project
+ * @returns {(name: string, version?: string) => string}
+ */
+export function addCommand(project: Project | undefined): (name: string, version?: string) => string;
+/**
+ * The per-user cache directory the saved copies live in, never inside a
+ * project. Standard platform locations only.
+ * @returns {string}
+ */
+export function defaultCacheDir(): string;
+/**
+ * Call every discover source — the project's `discover` first, then each
+ * integration's in load order — once per distinct function. A source that
+ * throws, times out, or returns an invalid catalog falls back to its saved copy;
+ * with none, it is reported and adds nothing. The others always count.
+ *
+ * @param {Project | undefined} project
+ * @param {{package?: string, version?: string}} [request] ask for one package,
+ *   and optionally one version's contributions
+ * @param {{cacheDir?: string, timeoutMs?: number}} [options]
+ * @returns {Promise<CatalogResult>}
+ */
+export function callSources(project: Project | undefined, request?: {
+    package?: string;
+    version?: string;
+}, options?: {
+    cacheDir?: string;
+    timeoutMs?: number;
+}): Promise<CatalogResult>;
+/**
+ * Project a scanned or installed package into the discover list/detail entry
+ * shape. Shared by the list and detail leaves so the entry keys (and their
+ * order) stay in one place. A kind list appears only when it is not empty.
+ * @param {InstalledPackage & {latest?: string}} pkg
  * @returns {import('./discover.type.mjs').DiscoverListEntry}
  */
-export function toEntry(pkg: ScannedPackage): import("./discover.type.mjs").DiscoverListEntry;
+export function toEntry(pkg: InstalledPackage & {
+    latest?: string;
+}): import("./discover.type.mjs").DiscoverListEntry;
 /**
  * Locate a component's doc file within the given packages (case-insensitive).
  * @param {ScannedPackage[]} packages
@@ -46,7 +104,56 @@ export function loadValidatedDoc(result: ComponentResolution, { lang, zh }: {
     lang?: string | null;
     zh?: boolean;
 }): Promise<import("./discover.type.mjs").DiscoverDetailDocResponse["data"]>;
+/** The list and detail entry fields for each item kind, in display order. */
+export const KIND_FIELDS: readonly [readonly ["component", "components"], readonly ["template", "templates"], readonly ["doc", "docs"], readonly ["theme", "themes"], readonly ["codemod", "codemods"], readonly ["agent-doc", "agentDocs"]];
 export type ScannedPackage = import("./_package-scanner.mjs").ScannedPackage;
+export type DiscoverPackage = import("../../authoring/discover/type").DiscoverPackage;
+export type DiscoverSource = import("../../authoring/discover/type").DiscoverSource;
+/**
+ * An installed integration with what it adds, per kind. `components` is the
+ * scanned component list the discover leaves have always used.
+ */
+export type InstalledPackage = ScannedPackage & {
+    templates?: string[];
+    docs?: string[];
+    themes?: string[];
+    codemods?: string[];
+};
+/**
+ * What one source did on this run.
+ */
+export type SourceState = {
+    /**
+     * the source's own name, or where it came from when it
+     * gave none
+     */
+    name: string;
+    /**
+     * `astryx.config`, or the integration that exports it
+     */
+    from: string;
+    status: "fresh" | "saved" | "failed";
+    generatedAt?: string | undefined;
+    complete?: boolean | undefined;
+    /**
+     * when the saved copy in use was written
+     */
+    savedAt?: string | undefined;
+    /**
+     * why the live call failed
+     */
+    error?: string | undefined;
+};
+/**
+ * Everything every source returned, merged. When two sources list the same
+ * package, the earlier source's entry is kept.
+ */
+export type CatalogResult = {
+    sources: SourceState[];
+    packages: Array<DiscoverPackage & {
+        source: string;
+    }>;
+};
 /**
  * A located component doc within a scanned package — the shape returned by
  * {@link findComponent}, consumed by {@link loadValidatedDoc}.
@@ -56,3 +163,4 @@ export type ComponentResolution = {
     docPath: string;
     componentName: string;
 };
+import { Project } from '../../foundation/config/project.mjs';

package/api/discover/_adapter.mjs

@@ -1,31 +1,81 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Shared external-package adapter for the discover leaves.
+ * @file Shared adapter for the discover leaves: the one place discover reaches
+ * the environment.
  *
  * Every `discover.*` leaf projects already-resolved data into a typed response;
- * none of them touch the integration system or the filesystem directly. This
- * adapter is the single place that does: it discovers the configured external
- * packages, locates a component's doc file within them, and loads + validates a
- * component's docs. Keeping that I/O here (rather than duplicated across leaves)
- * is what lets `list`, `detail`, `detail/doc`, and `search` stay pure
- * projections.
+ * none of them touch the integration system, the filesystem, or a source. This
+ * adapter does: it resolves the project's installed integrations and what each
+ * one adds, calls every discover source and keeps a saved copy of each answer,
+ * locates and loads a component's doc, and names the package manager's add
+ * command. Keeping that I/O here (INV21) is what lets `list`, `detail`,
+ * `detail/doc`, `detail/item`, and `search` stay pure projections.
  *
- * @position api/discover — orchestration over lib/project, lib/package-scanner,
- *   and lib/component-loader; the discover dispatcher + leaves consume it.
+ * @position api/discover — orchestration over foundation/config/project,
+ *   foundation/integrations, the discovery loaders, and discover sources.
  */
 
+import {createHash} from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import {Project} from '../../foundation/config/project.mjs';
 import {
   scanAllPackages,
   findComponentInPackages,
 } from './_package-scanner.mjs';
 import {loadDocs} from '../../foundation/discovery/component-loader.mjs';
+import {collectIdentities} from '../../foundation/integrations/contribution-inventory.mjs';
+import {detectPackageManager} from '../../foundation/env/package-manager.mjs';
+import {assertWithin} from '../../foundation/fs/path-safety.mjs';
+import {parseDiscoverCatalog} from '../../authoring/discover/parse.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
+const SOURCE_TIMEOUT_MS = 30_000;
+
+const DEPENDENCY_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+];
+
 /**
  * @typedef {import('./_package-scanner.mjs').ScannedPackage} ScannedPackage
+ * @typedef {import('../../authoring/discover/type').DiscoverPackage} DiscoverPackage
+ * @typedef {import('../../authoring/discover/type').DiscoverSource} DiscoverSource
+ */
+
+/**
+ * An installed integration with what it adds, per kind. `components` is the
+ * scanned component list the discover leaves have always used.
+ * @typedef {ScannedPackage & {
+ *   templates?: string[],
+ *   docs?: string[],
+ *   themes?: string[],
+ *   codemods?: string[],
+ * }} InstalledPackage
+ */
+
+/**
+ * What one source did on this run.
+ * @typedef {object} SourceState
+ * @property {string} name the source's own name, or where it came from when it
+ *   gave none
+ * @property {string} from `astryx.config`, or the integration that exports it
+ * @property {'fresh' | 'saved' | 'failed'} status
+ * @property {string} [generatedAt]
+ * @property {boolean} [complete]
+ * @property {string} [savedAt] when the saved copy in use was written
+ * @property {string} [error] why the live call failed
+ */
+
+/**
+ * Everything every source returned, merged. When two sources list the same
+ * package, the earlier source's entry is kept.
+ * @typedef {{sources: SourceState[], packages: Array<DiscoverPackage & {source: string}>}} CatalogResult
  */
 
 /**
@@ -68,7 +118,7 @@ function validateDocs(docs) {
  * configured" (`false`) from "configured but nothing discovered" (`true`),
  * which the list leaf surfaces as `meta`.
  *
- * @returns {Promise<{packages: ScannedPackage[], configured: boolean}>}
+ * @returns {Promise<{packages: ScannedPackage[], configured: boolean, project: Project}>}
  */
 export async function discoverPackages() {
   const project = await Project.load();
@@ -86,25 +136,323 @@ export async function discoverPackages() {
       docsDir: integration.components,
     }));
   if (explicitPackages.length === 0) {
-    return {packages: [], configured: loadedIntegrations.length > 0};
+    return {packages: [], configured: loadedIntegrations.length > 0, project};
   }
 
   const packages = scanAllPackages(
     [],
     /** @type {ScannedPackage[]} */ (/** @type {unknown} */ (explicitPackages)),
   );
-  return {packages, configured: true};
+  return {packages, configured: true, project};
+}
+
+/**
+ * Every integration the project loads, with what it adds. An integration with
+ * no components root is included with `components: []`; one that failed to
+ * load is left out (the integration-issues nudge and Doctor report it).
+ *
+ * @param {Project | undefined} project
+ * @param {ScannedPackage[]} scanned the packages {@link discoverPackages} found
+ * @returns {Promise<InstalledPackage[]>}
+ */
+export async function describeInstalled(project, scanned) {
+  if (project == null) return scanned;
+  const byName = new Map(scanned.map(pkg => [pkg.name, pkg]));
+  /** @type {InstalledPackage[]} */
+  const installed = [];
+  for (const integration of project.loadedIntegrations) {
+    if (integration.__loadError) continue;
+    const base =
+      byName.get(integration.name) ??
+      /** @type {ScannedPackage} */ (
+        /** @type {unknown} */ ({
+          name: integration.name,
+          category: integration.name,
+          version: integration.version,
+          components: [],
+        })
+      );
+    // Components come from the scan above; loading every component doc again
+    // here would only slow the list down.
+    const {identities} = await collectIdentities({
+      ...integration,
+      components: undefined,
+    });
+    installed.push({
+      ...base,
+      templates: identities.templates.map(t => t.id),
+      docs: identities.docs,
+      themes: identities.themes.map(t => t.slug),
+      codemods: identities.codemods.map(c => `${c.version}/${c.id}`),
+    });
+  }
+  return installed;
 }
 
 /**
- * Project a scanned package into the discover list/detail entry shape. Shared
- * by the list and detail leaves so the entry keys (and their order) stay in one
- * place.
- * @param {ScannedPackage} pkg
+ * Whether the project has any discover source: its own `discover` config field,
+ * or an integration's `discover` named export (valid or not).
+ * @param {Project | undefined} project
+ * @returns {boolean}
+ */
+export function hasSources(project) {
+  if (project == null) return false;
+  if (typeof project.config?.discover === 'function') return true;
+  return project.loadedIntegrations.some(
+    i => i.__discover != null || i.__discoverError != null,
+  );
+}
+
+/**
+ * Package names the project's package.json declares in any dependency field.
+ * @param {Project | undefined} project
+ * @returns {Set<string>}
+ */
+export function declaredDependencies(project) {
+  /** @type {Set<string>} */
+  const names = new Set();
+  if (project == null) return names;
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(project.cwd, 'package.json'), 'utf8'),
+    );
+    for (const field of DEPENDENCY_FIELDS) {
+      for (const name of Object.keys(pkg?.[field] ?? {})) names.add(name);
+    }
+  } catch {
+    // No readable package.json: nothing is declared.
+  }
+  return names;
+}
+
+/**
+ * The command that adds a package with the project's package manager. Discover
+ * only prints it; it never runs it.
+ * @param {Project | undefined} project
+ * @returns {(name: string, version?: string) => string}
+ */
+export function addCommand(project) {
+  const pm = detectPackageManager(project?.cwd ?? process.cwd());
+  const verb =
+    pm === 'pnpm'
+      ? 'pnpm add'
+      : pm === 'yarn'
+        ? 'yarn add'
+        : pm === 'bun'
+          ? 'bun add'
+          : 'npm install';
+  return (name, version) => `${verb} ${version ? `${name}@${version}` : name}`;
+}
+
+/**
+ * The per-user cache directory the saved copies live in, never inside a
+ * project. Standard platform locations only.
+ * @returns {string}
+ */
+export function defaultCacheDir() {
+  const home = os.homedir();
+  if (process.platform === 'win32') {
+    return path.join(
+      process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'),
+      'astryx',
+      'Cache',
+    );
+  }
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Caches', 'astryx');
+  }
+  return path.join(
+    process.env.XDG_CACHE_HOME || path.join(home, '.cache'),
+    'astryx',
+  );
+}
+
+/**
+ * @param {string} cacheDir
+ * @param {string} from
+ * @param {{package?: string, version?: string}} request
+ */
+function savedCopyPath(cacheDir, from, request) {
+  const key = createHash('sha256')
+    .update(`${from}\n${request.package ?? ''}\n${request.version ?? ''}`)
+    .digest('hex')
+    .slice(0, 32);
+  const dir = path.join(cacheDir, 'discover');
+  return assertWithin(`${key}.json`, dir, {label: 'discover saved copy'});
+}
+
+/**
+ * @param {string} file
+ * @param {string} label
+ */
+function readSavedCopy(file, label) {
+  try {
+    const saved = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return {
+      savedAt: String(saved.savedAt),
+      catalog: parseDiscoverCatalog(saved.catalog, label),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} file
+ * @param {import('../../authoring/discover/type').DiscoverCatalog} catalog
+ */
+function writeSavedCopy(file, catalog) {
+  try {
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(
+      tmp,
+      JSON.stringify({savedAt: new Date().toISOString(), catalog}),
+    );
+    fs.renameSync(tmp, file);
+  } catch {
+    // An unwritable cache only costs the offline copy.
+  }
+}
+
+/**
+ * @param {DiscoverSource} source
+ * @param {{package?: string, version?: string}} request
+ * @param {string} label
+ * @param {number} timeoutMs
+ */
+async function callSource(source, request, label, timeoutMs) {
+  const controller = new AbortController();
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  const timedOut = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(
+        new Error(`${label} did not answer within ${timeoutMs / 1000} seconds`),
+      );
+    }, timeoutMs);
+  });
+  try {
+    const answer = await Promise.race([
+      Promise.resolve().then(() =>
+        source({signal: controller.signal, ...request}),
+      ),
+      timedOut,
+    ]);
+    return parseDiscoverCatalog(answer, label);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Call every discover source — the project's `discover` first, then each
+ * integration's in load order — once per distinct function. A source that
+ * throws, times out, or returns an invalid catalog falls back to its saved copy;
+ * with none, it is reported and adds nothing. The others always count.
+ *
+ * @param {Project | undefined} project
+ * @param {{package?: string, version?: string}} [request] ask for one package,
+ *   and optionally one version's contributions
+ * @param {{cacheDir?: string, timeoutMs?: number}} [options]
+ * @returns {Promise<CatalogResult>}
+ */
+export async function callSources(project, request = {}, options = {}) {
+  const {cacheDir = defaultCacheDir(), timeoutMs = SOURCE_TIMEOUT_MS} = options;
+  /** @type {CatalogResult} */
+  const result = {sources: [], packages: []};
+  if (project == null) return result;
+
+  /** @type {Array<{from: string, source?: DiscoverSource, error?: string}>} */
+  const origins = [];
+  if (typeof project.config?.discover === 'function') {
+    origins.push({from: 'astryx.config', source: project.config.discover});
+  }
+  for (const integration of project.loadedIntegrations) {
+    if (integration.__discoverError) {
+      origins.push({from: integration.name, error: integration.__discoverError});
+    } else if (integration.__discover) {
+      origins.push({from: integration.name, source: integration.__discover});
+    }
+  }
+
+  /** @type {Set<unknown>} */
+  const called = new Set();
+  /** @type {Set<string>} */
+  const seen = new Set();
+  const ask = request.package
+    ? {package: request.package, ...(request.version ? {version: request.version} : {})}
+    : {};
+  for (const {from, source, error} of origins) {
+    if (source == null) {
+      result.sources.push({name: from, from, status: 'failed', error});
+      continue;
+    }
+    if (called.has(source)) continue;
+    called.add(source);
+
+    const label = `the discover source from ${from}`;
+    const file = savedCopyPath(cacheDir, from, ask);
+    /** @type {import('../../authoring/discover/type').DiscoverCatalog} */
+    let catalog;
+    try {
+      catalog = await callSource(source, ask, label, timeoutMs);
+      writeSavedCopy(file, catalog);
+      result.sources.push({
+        name: catalog.source.name,
+        from,
+        status: 'fresh',
+        generatedAt: catalog.source.generatedAt,
+        complete: catalog.source.complete,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const saved = readSavedCopy(file, label);
+      if (saved == null) {
+        result.sources.push({name: from, from, status: 'failed', error: message});
+        continue;
+      }
+      catalog = saved.catalog;
+      result.sources.push({
+        name: catalog.source.name,
+        from,
+        status: 'saved',
+        generatedAt: catalog.source.generatedAt,
+        complete: catalog.source.complete,
+        savedAt: saved.savedAt,
+        error: message,
+      });
+    }
+    for (const pkg of catalog.packages) {
+      if (seen.has(pkg.package)) continue;
+      seen.add(pkg.package);
+      result.packages.push({...pkg, source: catalog.source.name});
+    }
+  }
+  return result;
+}
+
+/** The list and detail entry fields for each item kind, in display order. */
+export const KIND_FIELDS = /** @type {const} */ ([
+  ['component', 'components'],
+  ['template', 'templates'],
+  ['doc', 'docs'],
+  ['theme', 'themes'],
+  ['codemod', 'codemods'],
+  ['agent-doc', 'agentDocs'],
+]);
+
+/**
+ * Project a scanned or installed package into the discover list/detail entry
+ * shape. Shared by the list and detail leaves so the entry keys (and their
+ * order) stay in one place. A kind list appears only when it is not empty.
+ * @param {InstalledPackage & {latest?: string}} pkg
  * @returns {import('./discover.type.mjs').DiscoverListEntry}
  */
 export function toEntry(pkg) {
-  return {
+  /** @type {Record<string, unknown>} */
+  const entry = {
     name: pkg.name,
     category: pkg.category,
     components: pkg.components,
@@ -112,6 +460,13 @@ export function toEntry(pkg) {
     description: pkg.description,
     displayName: pkg.displayName,
   };
+  for (const [, field] of KIND_FIELDS) {
+    if (field === 'components') continue;
+    const values = /** @type {Record<string, unknown>} */ (pkg)[field];
+    if (Array.isArray(values) && values.length > 0) entry[field] = values;
+  }
+  if (pkg.latest) entry.latest = pkg.latest;
+  return /** @type {import('./discover.type.mjs').DiscoverListEntry} */ (entry);
 }
 
 /**