@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/api/discover/_adapter.mjs

@@ -8,6 +8,7 @@
  * 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,
+ * reads the official list the CLI carries after them,
  * 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.
@@ -18,9 +19,14 @@
 
 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 {
+  Project,
+  availableComputerIntegrations,
+} from '../../foundation/config/project.mjs';
+import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
+import {projectAddCommand} from '../../foundation/release/notices.mjs';
+import {hostedRun} from '../../foundation/runtime/package-root.mjs';
 import {
   scanAllPackages,
   findComponentInPackages,
@@ -28,13 +34,30 @@ import {
 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 {isValidSemver, semverCompare} from '../../foundation/env/semver.mjs';
 import {assertWithin} from '../../foundation/fs/path-safety.mjs';
+import {userCacheDir} from '../../foundation/env/user-dirs.mjs';
+import {CLI_ROOT, findInstalledPackage} from '../../foundation/fs/paths.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;
 
+/** The name the official list goes by, as a source and on each of its entries. */
+export const OFFICIAL_SOURCE_NAME = 'Astryx';
+
+/** Where the official list comes from: the CLI package that carries it. */
+const OFFICIAL_SOURCE_FROM = '@astryxdesign/cli';
+
+/** The official list, generated from the repository when the CLI is built. */
+export const OFFICIAL_LIST_FILE = path.join(
+  CLI_ROOT,
+  'assets',
+  'discover',
+  'official-packages.json',
+);
+
 const DEPENDENCY_FIELDS = [
   'dependencies',
   'devDependencies',
@@ -48,6 +71,29 @@ const DEPENDENCY_FIELDS = [
  * @typedef {import('../../authoring/discover/type').DiscoverSource} DiscoverSource
  */
 
+/**
+ * An official package as this CLI lists it (spec:AST-051 FR11), with what its
+ * add command pins (FR2): the project's Core version, the Core range the
+ * project declares, or the latest release; with none, it pins nothing.
+ * @typedef {DiscoverPackage & {pin?: string}} OfficialPackage
+ */
+
+/**
+ * The official packages the project's package.json declares: the real package
+ * name of each, mapped to the name it is installed under (an npm alias such as
+ * `"my-theme": "npm:@astryxdesign/theme-gothic@0.7.0"` installs under
+ * `my-theme`). `dependency` holds those declared in dependencies,
+ * devDependencies or optionalDependencies, which make a package the project's
+ * own; `any` adds peerDependencies, which only keep it from being offered.
+ * @typedef {{dependency: Map<string, string>, any: Set<string>}} OfficialDeclarations
+ */
+
+/**
+ * The official list as this CLI reads it. `error` says why the file could not
+ * be read; the list is then empty and discover reports it like a failed source.
+ * @typedef {{packages: OfficialPackage[], error?: string}} OfficialList
+ */
+
 /**
  * An installed integration with what it adds, per kind. `components` is the
  * scanned component list the discover leaves have always used.
@@ -64,7 +110,8 @@ const DEPENDENCY_FIELDS = [
  * @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 {string} from `astryx.config`, the integration that exports it, or
+ *   `@astryxdesign/cli` for the official list
  * @property {'fresh' | 'saved' | 'failed'} status
  * @property {string} [generatedAt]
  * @property {boolean} [complete]
@@ -73,9 +120,10 @@ const DEPENDENCY_FIELDS = [
  */
 
 /**
- * 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
+ * Everything every source returned, merged, the official list last. When two
+ * sources list the same package, the earlier source's entry is kept. `official`
+ * marks an entry the official list supplied.
+ * @typedef {{sources: SourceState[], packages: Array<DiscoverPackage & {source: string, official?: true}>}} CatalogResult
  */
 
 /**
@@ -196,6 +244,7 @@ export async function describeInstalled(project, scanned) {
  * @returns {boolean}
  */
 export function hasSources(project) {
+  if (doorSources().length > 0) return true;
   if (project == null) return false;
   if (typeof project.config?.discover === 'function') return true;
   return project.loadedIntegrations.some(
@@ -203,6 +252,48 @@ export function hasSources(project) {
   );
 }
 
+/** Where a discover source a host passed comes from (spec AST-081 FR1). */
+const DOOR_SOURCE = 'the host';
+
+/**
+ * The discover sources the host that started this run passed, if any.
+ * @returns {readonly DiscoverSource[]}
+ */
+function doorSources() {
+  return /** @type {readonly DiscoverSource[]} */ (
+    hostedRun()?.discoverSources ?? []
+  );
+}
+
+/** The source name of a package installed for the computer. */
+const COMPUTER_SOURCE = 'installed for this computer';
+
+/**
+ * The integrations installed for the computer that a project could add, as
+ * available entries with the project's install command (spec AST-081 FR12).
+ * Empty outside a project, where they load instead.
+ * @param {Project | undefined} project
+ * @param {Array<{name: string}>} installed
+ * @param {Set<string>} declared
+ * @returns {Promise<import('./discover.type.mjs').DiscoverAvailableEntry[]>}
+ */
+export async function computerAvailableEntries(project, installed, declared) {
+  const cwd = project?.cwd ?? process.cwd();
+  if (isOutsideProject(cwd)) return [];
+  // The same command doctor names: in the project spec:AST-040 FR9 defines,
+  // and none where FR9 finds no project.
+  const add = projectAddCommand(cwd);
+  const have = new Set([...installed.map(pkg => pkg.name), ...declared]);
+  return (await availableComputerIntegrations(cwd, have)).map(c => ({
+    name: c.name,
+    components: [],
+    ...(c.version ? {version: c.version} : {}),
+    ...(c.description ? {description: c.description} : {}),
+    source: COMPUTER_SOURCE,
+    ...(add ? {install: add(c.name)} : {}),
+  }));
+}
+
 /**
  * Package names the project's package.json declares in any dependency field.
  * @param {Project | undefined} project
@@ -225,13 +316,151 @@ export function declaredDependencies(project) {
   return names;
 }
 
+/**
+ * The nearest package.json at or above the project's folder, read. Discover
+ * runs from any folder of a project; this is the project's own manifest.
+ * @param {Project | undefined} project
+ * @returns {{dir: string, pkg: Record<string, any>} | null}
+ */
+function nearestManifest(project) {
+  let dir = project?.cwd ?? process.cwd();
+  for (;;) {
+    const file = path.join(dir, 'package.json');
+    if (fs.existsSync(file)) {
+      try {
+        return {dir, pkg: JSON.parse(fs.readFileSync(file, 'utf8'))};
+      } catch {
+        return null;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** The fields that make a declared package the project's own. */
+const OWN_DEPENDENCY_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+];
+
+/**
+ * The package a dependency entry installs: its own name, or the target of an
+ * npm alias (`npm:<name>@<range>`).
+ * @param {string} name
+ * @param {unknown} spec
+ * @returns {string}
+ */
+function declaredPackage(name, spec) {
+  if (typeof spec !== 'string' || !spec.startsWith('npm:')) return name;
+  const target = spec.slice('npm:'.length);
+  const at = target.indexOf('@', 1);
+  return at > 0 ? target.slice(0, at) : target;
+}
+
+/**
+ * What the project's own package.json, the nearest one above the folder
+ * discover runs in, declares among the official packages.
+ * @param {Project | undefined} project
+ * @param {OfficialPackage[]} official
+ * @returns {OfficialDeclarations}
+ */
+export function officialDeclarations(project, official) {
+  const names = new Set(official.map(pkg => pkg.package));
+  /** @type {OfficialDeclarations} */
+  const declared = {dependency: new Map(), any: new Set()};
+  const manifest = nearestManifest(project);
+  if (manifest == null) return declared;
+  for (const field of DEPENDENCY_FIELDS) {
+    for (const [local, spec] of Object.entries(manifest.pkg?.[field] ?? {})) {
+      const real = declaredPackage(local, spec);
+      if (!names.has(real)) continue;
+      declared.any.add(real);
+      if (
+        OWN_DEPENDENCY_FIELDS.includes(field) &&
+        !declared.dependency.has(real)
+      )
+        declared.dependency.set(real, local);
+    }
+  }
+  return declared;
+}
+
+/**
+ * One part of a semver range: an optional comparator and a version that may
+ * use `x` or `*` wildcards.
+ */
+const RANGE_PART =
+  /^(?:[<>]=?|=|\^|~)?v?(?:\d+|[xX*])(?:\.(?:\d+|[xX*])){0,2}(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+
+/**
+ * Whether a dependency spec is a semver range every supported package manager
+ * resolves: comparators, wildcards, `||` and hyphen ranges. A dist-tag, path,
+ * URL, alias or workspace protocol is not.
+ * @param {string} spec
+ * @returns {boolean}
+ */
+function isSemverRange(spec) {
+  const parts = spec
+    .trim()
+    .split(/\s*\|\|\s*|\s+/u)
+    .filter(part => part !== '-');
+  return parts.length > 0 && parts.every(part => RANGE_PART.test(part));
+}
+
+/**
+ * The project's Core: the installed copy's version, else what its own
+ * package.json declares (a fresh clone before install): an exact `version`, or
+ * a semver `range`. Neither, for a declaration no package manager can pin
+ * against, such as a path or a dist-tag. Null when the project has no Core.
+ * @param {Project | undefined} project
+ * @returns {{version?: string, range?: string} | null}
+ */
+function projectCore(project) {
+  const installed = installedVersion(project, '@astryxdesign/core');
+  if (installed) return {version: installed};
+  const manifest = nearestManifest(project);
+  for (const field of OWN_DEPENDENCY_FIELDS) {
+    const spec = manifest?.pkg?.[field]?.['@astryxdesign/core'];
+    if (typeof spec !== 'string') continue;
+    // A space after an operator (`~ 0.6.8`, `>= 0.6.8 < 0.7.0`) is allowed by
+    // node-semver; join each operator to its version before reading the spec.
+    const range = spec.trim().replace(/([<>]=?|=|\^|~)\s+/gu, '$1');
+    const exact = range.replace(/^=/u, '');
+    if (isValidSemver(exact)) return {version: exact};
+    return isSemverRange(range) ? {range} : {};
+  }
+  return null;
+}
+
+/**
+ * Newest first: by release number, then a release before its prereleases.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function newerFirst(a, b) {
+  const byNumber = semverCompare(b, a);
+  if (byNumber !== 0) return byNumber;
+  const aRelease = !a.includes('-');
+  if (aRelease !== !b.includes('-')) return aRelease ? -1 : 1;
+  return b.localeCompare(a, 'en', {numeric: true});
+}
+
 /**
  * The command that adds a package with the project's package manager. Discover
- * only prints it; it never runs it.
+ * only prints it; it never runs it. Asked for one version, it adds that
+ * version. Given the official list, it otherwise pins an official package to
+ * what its entry names (spec:AST-051 FR2): the project's Core version or
+ * declared Core range, else the latest release. A range is quoted, because
+ * `^`, `<`, `>`, `|` and spaces mean something to a shell.
  * @param {Project | undefined} project
+ * @param {{official?: OfficialPackage[]}} [options]
  * @returns {(name: string, version?: string) => string}
  */
-export function addCommand(project) {
+export function addCommand(project, {official = []} = {}) {
   const pm = detectPackageManager(project?.cwd ?? process.cwd());
   const verb =
     pm === 'pnpm'
@@ -241,7 +470,15 @@ export function addCommand(project) {
         : pm === 'bun'
           ? 'bun add'
           : 'npm install';
-  return (name, version) => `${verb} ${version ? `${name}@${version}` : name}`;
+  const byName = new Map(official.map(pkg => [pkg.package, pkg]));
+  return (name, version) => {
+    if (version) return `${verb} ${name}@${version}`;
+    const pin = byName.get(name)?.pin;
+    if (!pin) return `${verb} ${name}`;
+    return isValidSemver(pin)
+      ? `${verb} ${name}@${pin}`
+      : `${verb} "${name}@${pin}"`;
+  };
 }
 
 /**
@@ -250,26 +487,13 @@ export function addCommand(project) {
  * @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',
-  );
+  return userCacheDir();
 }
 
 /**
  * @param {string} cacheDir
- * @param {string} from
+ * @param {string} from the source's key: its `from` label, with the host for
+ *   a host's source
  * @param {{package?: string, version?: string}} request
  */
 function savedCopyPath(cacheDir, from, request) {
@@ -347,8 +571,9 @@ async function callSource(source, request, label, timeoutMs) {
 }
 
 /**
- * Call every discover source — the project's `discover` first, then each
- * integration's in load order — once per distinct function. A source that
+ * Call the discover sources — the project's `discover` first, then each
+ * integration's in load order, then each a host passed, named as the host's
+ * (spec AST-081 FR1, AST-051 FR6) — 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.
  *
@@ -358,24 +583,34 @@ async function callSource(source, request, label, timeoutMs) {
  * @param {{cacheDir?: string, timeoutMs?: number}} [options]
  * @returns {Promise<CatalogResult>}
  */
-export async function callSources(project, request = {}, options = {}) {
+async function callOwnSources(project, request = {}, options = {}) {
   const {cacheDir = defaultCacheDir(), timeoutMs = SOURCE_TIMEOUT_MS} = options;
   /** @type {CatalogResult} */
   const result = {sources: [], packages: []};
-  if (project == null) return result;
+  const fromDoor = doorSources();
+  if (project == null && fromDoor.length === 0) return result;
 
-  /** @type {Array<{from: string, source?: DiscoverSource, error?: string}>} */
+  /** @type {Array<{from: string, key?: string, source?: DiscoverSource, error?: string}>} */
   const origins = [];
-  if (typeof project.config?.discover === 'function') {
+  if (typeof project?.config?.discover === 'function') {
     origins.push({from: 'astryx.config', source: project.config.discover});
   }
-  for (const integration of project.loadedIntegrations) {
+  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});
     }
   }
+  // Every tool that carries the CLI reports its sources as the host's, so
+  // their saved copies are kept per host, by the root that holds its CLI
+  // (spec:AST-051 FR8).
+  const host = hostedRun()?.startingRoot ?? '';
+  fromDoor.forEach((source, index) => {
+    const from =
+      fromDoor.length === 1 ? DOOR_SOURCE : `${DOOR_SOURCE} (${index + 1})`;
+    origins.push({from, key: `${from}\n${host}`, source});
+  });
 
   /** @type {Set<unknown>} */
   const called = new Set();
@@ -384,7 +619,7 @@ export async function callSources(project, request = {}, options = {}) {
   const ask = request.package
     ? {package: request.package, ...(request.version ? {version: request.version} : {})}
     : {};
-  for (const {from, source, error} of origins) {
+  for (const {from, key = from, source, error} of origins) {
     if (source == null) {
       result.sources.push({name: from, from, status: 'failed', error});
       continue;
@@ -393,7 +628,7 @@ export async function callSources(project, request = {}, options = {}) {
     called.add(source);
 
     const label = `the discover source from ${from}`;
-    const file = savedCopyPath(cacheDir, from, ask);
+    const file = savedCopyPath(cacheDir, key, ask);
     /** @type {import('../../authoring/discover/type').DiscoverCatalog} */
     let catalog;
     try {
@@ -433,6 +668,257 @@ export async function callSources(project, request = {}, options = {}) {
   return result;
 }
 
+/**
+ * Call every discover source (see {@link callOwnSources}), then read the
+ * official list (spec:AST-051 FR11). The list comes last, so a source keeps
+ * its entry for an official package, or for any package of the same
+ * integration (FR7); the list adds the official packages no source covers.
+ * The result stays in source order; discover puts official packages first
+ * only where it shows them ({@link officialFirst}).
+ *
+ * @param {Project | undefined} project
+ * @param {{package?: string, version?: string}} [request]
+ * @param {{cacheDir?: string, timeoutMs?: number, official?: OfficialList}} [options]
+ *   `official`: the list {@link officialList} read; read here when absent
+ * @returns {Promise<CatalogResult>}
+ */
+export async function callSources(project, request = {}, options = {}) {
+  const {official = officialList({project}), ...rest} = options;
+  const own = await callOwnSources(project, request, rest);
+  // A source's entry wins for its package and for the integration it
+  // publishes under any name (FR7), so a fork or mirror keeps its place.
+  const seen = new Set(
+    own.packages.flatMap(pkg => [pkg.package, pkg.integration, ...pkg.aliases]),
+  );
+  /** @type {CatalogResult['packages']} */
+  const added = [];
+  for (const {pin: _pin, ...pkg} of official.packages) {
+    if (seen.has(pkg.package)) continue;
+    if (request.package && pkg.package !== request.package) continue;
+    added.push({...pkg, source: OFFICIAL_SOURCE_NAME, official: true});
+  }
+  return {
+    sources: [
+      ...own.sources,
+      official.error
+        ? {
+            name: OFFICIAL_SOURCE_NAME,
+            from: OFFICIAL_SOURCE_FROM,
+            status: 'failed',
+            error: official.error,
+          }
+        : {
+            name: OFFICIAL_SOURCE_NAME,
+            from: OFFICIAL_SOURCE_FROM,
+            status: 'fresh',
+            complete: true,
+          },
+    ],
+    // Source order: the first entry per integration is the one discover
+    // keeps. Official packages are put first only where discover shows them.
+    packages: [...own.packages, ...added],
+  };
+}
+
+/**
+ * Official packages first, in the official list's order; the rest keep theirs.
+ * @template T
+ * @param {T[]} items
+ * @param {OfficialPackage[]} official
+ * @param {(item: T) => string} nameOf
+ * @returns {T[]}
+ */
+export function officialFirst(items, official, nameOf) {
+  const order = new Map(official.map((pkg, index) => [pkg.package, index]));
+  const rank = (/** @type {T} */ item) => order.get(nameOf(item)) ?? order.size;
+  return [...items].sort((a, b) => rank(a) - rank(b));
+}
+
+/**
+ * The official list this CLI carries (spec:AST-051 FR11). The file holds no
+ * versions; each entry takes them from this CLI and the project:
+ *
+ * - Its latest release is the newest release this CLI knows: its own version
+ *   on a release CLI, or the project's Core version when that is a newer
+ *   release.
+ * - A package released with Core lists a release CLI's own version and the
+ *   project's Core version (installed, else declared exactly), so each,
+ *   the latest release included, can be looked up. Its add command pins the project's Core version, else the Core range
+ *   the project declares, else the latest release; nothing on a canary CLI in
+ *   a project with no Core, which may have been published without it.
+ * - A canary-only package is listed only by a canary CLI, as a prerelease at
+ *   the project's Core version when that is a prerelease, else at the CLI's
+ *   own version when the project has no Core. It is not listed beside a
+ *   released or declared Core, which it cannot be installed with.
+ *
+ * @param {{file?: string, version?: string, project?: Project}} [options] the
+ *   list file and the CLI version to read it for, both defaulting to this
+ *   CLI's own, and the project whose Core decides the versions
+ * @returns {OfficialList}
+ */
+export function officialList({
+  file = OFFICIAL_LIST_FILE,
+  version,
+  project,
+} = {}) {
+  try {
+    const cli = version ?? packageVersion(CLI_ROOT);
+    if (cli == null) throw new Error('the CLI package names no version');
+    const core = project == null ? null : projectCore(project);
+    const list = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const canaryCli = /-canary\./u.test(cli);
+    /** @type {(v: string | undefined) => v is string} */
+    const isRelease = v => v != null && !v.includes('-');
+    const latest =
+      [cli, core?.version].filter(isRelease).sort(newerFirst)[0] ?? null;
+    /** @type {OfficialPackage[]} */
+    const packages = [];
+    for (const pkg of list.packages) {
+      /** @type {string[]} */
+      let listed = [];
+      /** @type {string | null} */
+      let entryLatest = null;
+      /** @type {string | undefined} */
+      let pin;
+      if (pkg.canaryOnly === true) {
+        if (!canaryCli) continue;
+        if (core == null) pin = cli;
+        else if (core.version && !isRelease(core.version)) pin = core.version;
+        else continue;
+        listed = [pin];
+      } else if (pkg.releasedWithCore === true) {
+        entryLatest = latest;
+        listed = [
+          ...new Set(
+            [isRelease(cli) ? cli : undefined, core?.version].filter(
+              /** @returns {v is string} */ v => v != null,
+            ),
+          ),
+        ].sort(newerFirst);
+        // The project's Core version, else the plain range it declares, else
+        // the latest release (spec:AST-051 FR11): a Core declared as
+        // `workspace:*`, a `file:` path or a dist-tag, and not installed,
+        // still gets a pin.
+        pin =
+          core == null
+            ? canaryCli
+              ? undefined
+              : cli
+            : (core.version ?? core.range ?? entryLatest ?? undefined);
+      }
+      packages.push({
+        package: pkg.package,
+        integration: pkg.package,
+        aliases: [],
+        ...(pkg.description ? {description: pkg.description} : {}),
+        latest: entryLatest,
+        versions: listed.map(v => ({
+          version: v,
+          publishedAt: null,
+          prerelease: v.includes('-'),
+          status: 'ok',
+        })),
+        contributions: pkg.contributions,
+        ...(pin ? {pin} : {}),
+      });
+    }
+    return {packages};
+  } catch (err) {
+    return {
+      packages: [],
+      error: `the official list could not be read (${err instanceof Error ? err.message : String(err)})`,
+    };
+  }
+}
+
+/**
+ * What the project has: its installed integrations plus each official package
+ * its own package.json declares as a dependency whose entry the official list
+ * supplied, official packages first. A declared official package that a source
+ * lists stays as that source shows it (FR7). One that failed to load as an
+ * integration stays out. A declared one takes what it adds from the list and
+ * its version from the copy the project installed, under an npm alias too.
+ *
+ * @param {Project | undefined} project
+ * @param {InstalledPackage[]} installed from {@link describeInstalled}
+ * @param {CatalogResult} catalog
+ * @param {OfficialDeclarations} declared from {@link officialDeclarations}
+ * @param {OfficialPackage[]} official the official list, for the order
+ * @returns {Array<InstalledPackage & {declaredOfficial?: true}>}
+ */
+export function withDeclaredOfficial(
+  project,
+  installed,
+  catalog,
+  declared,
+  official,
+) {
+  const loaded = new Set(project?.loadedIntegrations.map(i => i.name) ?? []);
+  /** @type {Array<InstalledPackage & {declaredOfficial?: true}>} */
+  const added = [];
+  for (const pkg of catalog.packages) {
+    const local = declared.dependency.get(pkg.package);
+    if (!pkg.official || local == null || loaded.has(pkg.package)) continue;
+    const version = installedVersion(project, local);
+    added.push(
+      /** @type {InstalledPackage & {declaredOfficial: true}} */ (
+        /** @type {unknown} */ ({
+          name: pkg.package,
+          category: pkg.package,
+          ...(version ? {version} : {}),
+          ...(pkg.description ? {description: pkg.description} : {}),
+          ...itemLists(pkg.contributions),
+          declaredOfficial: true,
+        })
+      ),
+    );
+  }
+  return officialFirst([...installed, ...added], official, pkg => pkg.name);
+}
+
+/**
+ * Group contributions into the entry fields, one list per kind that has any.
+ * `components` is always present, like on a scanned package.
+ * @param {DiscoverPackage['contributions']} contributions
+ * @returns {Record<string, string[]>}
+ */
+function itemLists(contributions) {
+  /** @type {Record<string, string[]>} */
+  const lists = {components: []};
+  for (const [kind, field] of KIND_FIELDS) {
+    const names = contributions.filter(c => c.kind === kind).map(c => c.name);
+    if (names.length > 0) lists[field] = names;
+  }
+  return lists;
+}
+
+/**
+ * The version in a package directory's package.json, if it names one.
+ * @param {string} dir
+ * @returns {string | undefined}
+ */
+function packageVersion(dir) {
+  try {
+    const {version} = JSON.parse(
+      fs.readFileSync(path.join(dir, 'package.json'), 'utf8'),
+    );
+    return typeof version === 'string' && version ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The version of `name` the project installed, if it installed it.
+ * @param {Project | undefined} project
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+function installedVersion(project, name) {
+  const dir = findInstalledPackage(project?.cwd ?? process.cwd(), name);
+  return dir == null ? undefined : packageVersion(dir);
+}
+
 /** The list and detail entry fields for each item kind, in display order. */
 export const KIND_FIELDS = /** @type {const} */ ([
   ['component', 'components'],