@astryxdesign/cli 0.6.4 → 0.6.5-canary.00f1ed9

package/foundation/integrations/cli-requirement.mjs

@@ -1,13 +1,16 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file The CLI an integration's namespace docs need (spec:AST-046 FR11).
+ * @file The CLI release an integration's newer contributions need
+ * (spec:AST-046 FR11).
  *
  * @input A package.json object.
  * @output Whether its `peerDependencies` range for `@astryxdesign/cli` admits
- *   only CLIs that read namespace docs, and the package.json that declares it.
- * @position foundation/integrations; read by `integration add doc --parent`,
- *   which declares the peer, and `integration pack --check`, which requires it.
+ *   only CLIs that read what the package ships, and the package.json that
+ *   declares that range.
+ * @position foundation/integrations; read by `integration add doc --parent`
+ *   and `integration add theme`, which declare the peer, and
+ *   `integration verify`, which requires it.
  */
 
 import {semverCompare} from '../env/semver.mjs';
@@ -15,13 +18,34 @@ import {semverCompare} from '../env/semver.mjs';
 export const CLI_PACKAGE = '@astryxdesign/cli';
 
 /**
- * The first CLI release that reads an integration's docs tree (namespace docs
- * and placed guides) and its templates' `replaces`. A release before it can
- * hide every doc topic a package with a namespace doc or a placed guide
- * ships, with no warning, and it rejects `replaces` and withholds the
- * package's templates and doc topics.
+ * The first stable CLI release that reads an integration's docs tree:
+ * namespace docs and placed guides. Published 0.6.3 rejects a namespace doc
+ * and hides every doc topic the package ships, with no warning; published
+ * 0.6.4 lists the namespace and reads its guides.
  */
-export const DOCS_TREE_CLI = '0.7.0';
+export const NAMESPACE_DOCS_CLI = '0.6.4';
+
+/**
+ * The first CLI release that reads a template's `replaces` and `keywords`. A
+ * release before it rejects either field, drops that template, and hides the
+ * package's doc topics.
+ */
+export const REPLACES_CLI = '0.7.0';
+
+/**
+ * The first stable CLI release that reads typed theme descriptors, the theme
+ * folder `integration add theme` writes. Published 0.6.3 rejects a themes root
+ * with no `manifest.json` catalog and withholds the package's themes and doc
+ * topics; published 0.6.4 lists the themes.
+ */
+export const THEMES_CLI = '0.6.4';
+
+/**
+ * The first stable CLI release that reads a doc section's `id`. Published
+ * 0.6.3 rejects the field and hides every doc topic the package ships;
+ * published 0.6.4 reads the section by its id.
+ */
+export const SECTION_IDS_CLI = '0.6.4';
 
 const VERSION_RE = /^v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 
@@ -86,17 +110,25 @@ export function lowestAdmitted(range) {
  * @param {any} pkg package.json
  * @param {string} feature what the package does, e.g. "ships a namespace doc"
  * @param {string} loss what an older CLI does with it
+ * @param {string} floor the first stable CLI release that reads it
  * @returns {string | null}
  */
-function cliRangeProblem(pkg, feature, loss) {
+export function cliRangeProblem(pkg, feature, loss, floor) {
+  // A floor that is missing or not a version means a caller passed the
+  // arguments in another order, as after a merge with a caller written for
+  // another signature. Fail loudly rather than compare a range against
+  // feature text, or against nothing.
+  if (typeof floor !== 'string' || lowerVersion(floor) == null) {
+    throw new TypeError(`cliRangeProblem: floor "${floor}" is not a version`);
+  }
   const range = pkg?.peerDependencies?.[CLI_PACKAGE];
-  const fix = `"${CLI_PACKAGE}": ">=${DOCS_TREE_CLI}" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required)`;
+  const fix = `"${CLI_PACKAGE}": ">=${floor}" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required)`;
   if (typeof range !== 'string') {
-    return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A CLI older than ${DOCS_TREE_CLI} ${loss}. Declare ${fix}.`;
+    return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A stable CLI before ${floor} ${loss}. Declare ${fix}.`;
   }
   const lowest = lowestAdmitted(range);
-  if (lowest == null || semverCompare(lowest, DOCS_TREE_CLI) < 0) {
-    return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a CLI older than ${DOCS_TREE_CLI}, which ${loss}. Declare ${fix}.`;
+  if (lowest == null || semverCompare(lowest, floor) < 0) {
+    return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a stable CLI before ${floor}, which ${loss}. Declare ${fix}.`;
   }
   return null;
 }
@@ -106,7 +138,7 @@ function cliRangeProblem(pkg, feature, loss) {
  * docs on an older CLI, or null when its declared CLI range admits only CLIs
  * that read the docs tree. Published 0.6.3 hides every topic of a package
  * with a namespace doc; builds of main before the docs tree also do so for a
- * placed guide.
+ * placed guide. Published 0.6.4 reads both.
  * @param {any} pkg package.json
  * @returns {string | null}
  */
@@ -115,12 +147,13 @@ export function docsTreeCliProblem(pkg) {
     pkg,
     'ships a namespace doc or a placed guide',
     'does not read the docs tree, and can hide every doc topic the package ships',
+    NAMESPACE_DOCS_CLI,
   );
 }
 
 /**
- * Why a package with a template that sets `replaces` would lose its templates
- * and doc topics on an older CLI (spec:AST-035), or null when its declared CLI
+ * Why a package with a template that sets `replaces` would lose templates and
+ * doc topics on an older CLI (spec:AST-035), or null when its declared CLI
  * range admits only CLIs that read the field.
  * @param {any} pkg package.json
  * @returns {string | null}
@@ -129,26 +162,90 @@ export function replacesCliProblem(pkg) {
   return cliRangeProblem(
     pkg,
     'has a template that sets `replaces`',
-    "rejects the field, and withholds the package's templates and doc topics",
+    "rejects the field, drops that template, and hides the package's doc topics",
+    REPLACES_CLI,
   );
 }
 
 /**
- * The package.json with a CLI peer that reads namespace docs: optional, unless
- * the package already says otherwise.
+ * Why a package with a doc section that sets `id` would lose its doc topics on
+ * an older CLI, or null when its declared CLI range admits only CLIs that read
+ * the field. Published 0.6.3 rejects a section `id` and hides every doc topic
+ * the package ships; published 0.6.4 reads it.
  * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function sectionIdsCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'has a doc section that sets `id`',
+    'rejects the field, and can hide every doc topic the package ships',
+    SECTION_IDS_CLI,
+  );
+}
+
+/**
+ * Why a package that ships a theme would lose its themes and doc topics on an
+ * older CLI, or null when its declared CLI range admits only CLIs that read
+ * typed theme descriptors. Published 0.6.3 rejects a themes root with no
+ * `manifest.json` catalog, which `integration add theme` no longer writes;
+ * published 0.6.4 reads the descriptors.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function themesCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'ships a theme',
+    "cannot read typed theme descriptors, and can drop the package's themes and hide its doc topics",
+    THEMES_CLI,
+  );
+}
+
+/**
+ * Why a package with a template that sets `keywords` would lose that template
+ * and its doc topics on an older CLI, or null when its declared CLI range
+ * admits only CLIs that read the field. Published 0.6.3 rejects the field,
+ * drops that template, and hides the package's doc topics.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function keywordsCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'has a template that sets `keywords`',
+    "rejects the field, drops that template, and hides the package's doc topics",
+    REPLACES_CLI,
+  );
+}
+
+/**
+ * The package.json with a CLI peer of `>=floor`: optional, unless the package
+ * already says otherwise. Call it only when the package's range admits a CLI
+ * before `floor`, so a stricter range is never lowered.
+ * @param {any} pkg package.json
+ * @param {string} floor the first stable CLI release the package needs
  * @returns {any}
  */
-export function withDocsTreeCli(pkg) {
+export function withCliPeer(pkg, floor) {
   const meta = pkg.peerDependenciesMeta ?? {};
   return {
     ...pkg,
     peerDependencies: {
       ...(pkg.peerDependencies ?? {}),
-      [CLI_PACKAGE]: `>=${DOCS_TREE_CLI}`,
+      [CLI_PACKAGE]: `>=${floor}`,
     },
     peerDependenciesMeta: meta[CLI_PACKAGE]
       ? meta
       : {...meta, [CLI_PACKAGE]: {optional: true}},
   };
 }
+
+/**
+ * The package.json with a CLI peer that reads namespace docs.
+ * @param {any} pkg package.json
+ * @returns {any}
+ */
+export function withDocsTreeCli(pkg) {
+  return withCliPeer(pkg, NAMESPACE_DOCS_CLI);
+}

package/foundation/integrations/cli-requirement.test.mjs

@@ -1,11 +1,22 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import fs from 'node:fs';
 import {describe, expect, it} from 'vitest';
+import {semverCompare} from '../env/semver.mjs';
+import * as requirement from './cli-requirement.mjs';
 import {
-  DOCS_TREE_CLI,
+  NAMESPACE_DOCS_CLI,
+  REPLACES_CLI,
+  SECTION_IDS_CLI,
+  cliRangeProblem,
+  THEMES_CLI,
   lowestAdmitted,
   docsTreeCliProblem,
+  keywordsCliProblem,
   replacesCliProblem,
+  sectionIdsCliProblem,
+  themesCliProblem,
+  withCliPeer,
   withDocsTreeCli,
 } from './cli-requirement.mjs';
 
@@ -32,6 +43,11 @@ describe('docsTreeCliProblem', () => {
     expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
       'declares no @astryxdesign/cli peer',
     );
+    // Stable releases: a canary built from main before its release reports
+    // the older version and reads every feature.
+    expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
+      'A stable CLI before 0.6.4 does not read the docs tree',
+    );
   });
 
   it.each(['^0.6.0', '^0.6.0 || >=0.7.0', '*', '>=0.6.3'])(
@@ -39,20 +55,23 @@ describe('docsTreeCliProblem', () => {
     range => {
       expect(
         docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
-      ).toContain('admits a CLI older than');
+      ).toContain('admits a stable CLI before');
     },
   );
 
-  it.each(['>=0.7.0', '^0.7.2', '>=0.7.0 <2'])('accepts %s', range => {
-    expect(
-      docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
-    ).toBeNull();
-  });
+  it.each(['>=0.6.4', '^0.6.4', '>=0.7.0', '^0.7.2', '>=0.7.0 <2'])(
+    'accepts %s',
+    range => {
+      expect(
+        docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
+      ).toBeNull();
+    },
+  );
 
   it('declares the peer as optional, and keeps what the package says of it', () => {
     const declared = withDocsTreeCli({name: '@acme/kit'});
     expect(declared.peerDependencies).toEqual({
-      '@astryxdesign/cli': `>=${DOCS_TREE_CLI}`,
+      '@astryxdesign/cli': '>=0.6.4',
     });
     expect(declared.peerDependenciesMeta).toEqual({
       '@astryxdesign/cli': {optional: true},
@@ -76,9 +95,122 @@ describe('replacesCliProblem', () => {
     );
     expect(
       replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '^0.6.0'}}),
-    ).toContain('admits a CLI older than');
+    ).toContain('admits a stable CLI before');
     expect(
       replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.7.0'}}),
     ).toBeNull();
+    // Unlike the docs tree, `replaces` still needs 0.7.0.
+    expect(
+      replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.6.4'}}),
+    ).toContain('admits a stable CLI before 0.7.0');
+  });
+});
+
+describe('themesCliProblem and sectionIdsCliProblem', () => {
+  // Published 0.6.4 reads typed theme descriptors and section ids. Published
+  // 0.6.3 rejects both and hides the package's doc topics.
+  it.each([
+    ['a theme', themesCliProblem, 'ships a theme'],
+    ['a section id', sectionIdsCliProblem, 'sets `id`'],
+  ])('asks for a CLI from 0.6.4 for %s', (_name, problem, feature) => {
+    expect(problem({name: '@acme/kit'})).toContain(feature);
+    expect(problem({name: '@acme/kit'})).toContain('A stable CLI before 0.6.4');
+    for (const range of ['>=0.6.4', '^0.6.4', '>=0.6.5', '>=0.7.0']) {
+      expect(
+        problem({peerDependencies: {'@astryxdesign/cli': range}}),
+      ).toBeNull();
+    }
+    for (const range of ['^0.6.0', '>=0.6.3', '*']) {
+      expect(
+        problem({peerDependencies: {'@astryxdesign/cli': range}}),
+      ).toContain('admits a stable CLI before 0.6.4');
+    }
+  });
+
+  it('keeps 0.7.0 for replaces and keywords', () => {
+    const pkg = {peerDependencies: {'@astryxdesign/cli': '>=0.6.4'}};
+    expect(docsTreeCliProblem(pkg)).toBeNull();
+    expect(replacesCliProblem(pkg)).toContain(
+      'admits a stable CLI before 0.7.0',
+    );
+    expect(keywordsCliProblem(pkg)).toContain(
+      'admits a stable CLI before 0.7.0',
+    );
+    expect(
+      keywordsCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.7.0'}}),
+    ).toBeNull();
+  });
+
+  it('names a released CLI for a feature that already shipped', () => {
+    const {version} = JSON.parse(
+      fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf-8'),
+    );
+    for (const floor of [NAMESPACE_DOCS_CLI, THEMES_CLI, SECTION_IDS_CLI]) {
+      expect(semverCompare(floor, version.split('-')[0])).toBeLessThanOrEqual(
+        0,
+      );
+    }
+  });
+
+  it('declares the floor a theme needs as an optional peer', () => {
+    const declared = withCliPeer({name: '@acme/kit'}, THEMES_CLI);
+    expect(declared.peerDependencies).toEqual({
+      '@astryxdesign/cli': '>=0.6.4',
+    });
+    expect(declared.peerDependenciesMeta).toEqual({
+      '@astryxdesign/cli': {optional: true},
+    });
+    expect(themesCliProblem(declared)).toBeNull();
+  });
+});
+
+describe('cliRangeProblem', () => {
+  it('fails loudly when a caller names no floor', () => {
+    expect(() =>
+      // @ts-expect-error: the floor is required
+      cliRangeProblem({name: '@acme/kit'}, 'ships x', 'drops x'),
+    ).toThrow(TypeError);
+  });
+
+  it('fails loudly when the floor is not a version', () => {
+    expect(() =>
+      cliRangeProblem({name: '@acme/kit'}, '0.6.4', 'ships x', 'drops x'),
+    ).toThrow(TypeError);
+  });
+});
+
+describe('every feature check names its CLI floor', () => {
+  // The first stable CLI release that reads each feature. A new check, or a
+  // check whose floor changes, fails here until this table says so on
+  // purpose, so a floor never moves as a side effect of another change.
+  const FLOORS = {
+    docsTreeCliProblem: '0.6.4',
+    replacesCliProblem: REPLACES_CLI,
+    keywordsCliProblem: REPLACES_CLI,
+    sectionIdsCliProblem: '0.6.4',
+    themesCliProblem: '0.6.4',
+  };
+
+  it('asks each feature for the CLI release this table names', () => {
+    const named = Object.fromEntries(
+      Object.entries(requirement)
+        .filter(
+          ([name, value]) =>
+            typeof value === 'function' &&
+            /CliProblem$/.test(name) &&
+            name !== 'cliRangeProblem',
+        )
+        .map(([name, check]) => [
+          name,
+          /A stable CLI before (\d+\.\d+\.\d+)/.exec(
+            check({name: '@acme/kit'}) ?? '',
+          )?.[1] ?? null,
+        ]),
+    );
+    expect(named).toEqual({
+      ...FLOORS,
+      replacesCliProblem: '0.7.0',
+      keywordsCliProblem: '0.7.0',
+    });
   });
 });

package/foundation/integrations/contribution-inventory.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Contribution inventory for integration pack-check.
+ * @file Contribution inventory for `astryx integration verify`.
  *
  * Enumerates the files and contribution identities an integration package
  * declares, for cross-referencing against the npm tarball. The file inventory

package/foundation/integrations/integrations.d.mts

@@ -45,7 +45,7 @@ export function findManifestPaths(dir: string): string[];
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, agentDocsError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string}>}
  */
 export function loadManifest(file: string, label?: string, { fresh }?: {
     fresh?: boolean;
@@ -55,6 +55,8 @@ export function loadManifest(file: string, label?: string, { fresh }?: {
     debug?: import("../../authoring/debug/type").DebugEventHandler;
     gapReport?: import("../../authoring/gap-report/type").GapReportHandler;
     gapReportError?: string;
+    discover?: import("../../authoring/discover/type").DiscoverSource;
+    discoverError?: string;
     agentDocsError?: string;
 }>;
 /**
@@ -154,6 +156,9 @@ export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProvider
  *   validated package-owned handler from the `gapReport` NAMED export.
  * @property {string} [__gapReportError] isolated named-handler validation error.
  *   Named exports are not manifest keys — see {@link loadManifest}.
+ * @property {import('../../authoring/discover/type').DiscoverSource} [__discover]
+ *   validated catalog source from the `discover` NAMED export.
+ * @property {string} [__discoverError] isolated discover-source validation error.
  */
 /** Conventional manifest basenames, in load-precedence order. */
 export const MANIFEST_BASENAMES: string[];
@@ -245,4 +250,12 @@ export type LoadedIntegration = {
      * Named exports are not manifest keys — see {@link loadManifest}.
      */
     __gapReportError?: string | undefined;
+    /**
+     * validated catalog source from the `discover` NAMED export.
+     */
+    __discover?: import("../../authoring/discover/type").DiscoverSource | undefined;
+    /**
+     * isolated discover-source validation error.
+     */
+    __discoverError?: string | undefined;
 };

package/foundation/integrations/integrations.mjs

@@ -29,6 +29,7 @@ import {
 } from '../../authoring/integration/schema.mjs';
 import {importUserModule, findPresentFiles} from '../fs/module-loader.mjs';
 import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
+import {parseDiscoverSource} from '../../authoring/discover/parse.mjs';
 import {resolveProviders} from './provider-resolution.mjs';
 
 /**
@@ -80,6 +81,9 @@ import {resolveProviders} from './provider-resolution.mjs';
  *   validated package-owned handler from the `gapReport` NAMED export.
  * @property {string} [__gapReportError] isolated named-handler validation error.
  *   Named exports are not manifest keys — see {@link loadManifest}.
+ * @property {import('../../authoring/discover/type').DiscoverSource} [__discover]
+ *   validated catalog source from the `discover` NAMED export.
+ * @property {string} [__discoverError] isolated discover-source validation error.
  */
 
 /** Conventional manifest basenames, in load-precedence order. */
@@ -167,6 +171,23 @@ function parseGapReportHandlerExport(value, label) {
   }
 }
 
+/**
+ * Parse the optional named discover source the same way: a malformed one is
+ * isolated from every other contribution and reported by `astryx discover`.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {{source?: import('../../authoring/discover/type').DiscoverSource, error?: string}}
+ */
+function parseDiscoverSourceExport(value, label) {
+  if (value === undefined) return {};
+  try {
+    return {source: parseDiscoverSource(value, `${label} named export "discover"`)};
+  } catch (error) {
+    return {error: error instanceof Error ? error.message : String(error)};
+  }
+}
+
 /**
  * Load and validate a manifest module's default export, while isolating the
  * optional `agentDocs` contribution from the manifest's other fields.
@@ -183,7 +204,7 @@ function parseGapReportHandlerExport(value, label) {
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, agentDocsError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string}>}
  */
 export async function loadManifest(
   file,
@@ -194,6 +215,7 @@ export async function loadManifest(
   const raw = mod?.default;
   const baseManifest = parseIntegrationBase(raw, label);
   const gapReport = parseGapReportHandlerExport(mod?.gapReport, label);
+  const discover = parseDiscoverSourceExport(mod?.discover, label);
   const hasAgentDocs =
     raw != null &&
     typeof raw === 'object' &&
@@ -228,6 +250,8 @@ export async function loadManifest(
         : undefined,
     gapReport: gapReport.handler,
     gapReportError: gapReport.error,
+    discover: discover.source,
+    discoverError: discover.error,
     agentDocsError,
   };
 }
@@ -345,6 +369,10 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
   let gapReportHandler;
   /** @type {string | undefined} */
   let gapReportError;
+  /** @type {import('../../authoring/discover/type').DiscoverSource | undefined} */
+  let discoverSource;
+  /** @type {string | undefined} */
+  let discoverError;
   /** @type {string | undefined} */
   let agentDocsError;
   try {
@@ -354,6 +382,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
       debug: debugHandler,
       gapReport: gapReportHandler,
       gapReportError,
+      discover: discoverSource,
+      discoverError,
       agentDocsError,
     } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
   } catch (err) {
@@ -397,6 +427,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     __debug: debugHandler,
     __gapReport: gapReportHandler,
     __gapReportError: gapReportError,
+    __discover: discoverSource,
+    __discoverError: discoverError,
     __spec: spec,
     __packageDir: packageDir,
     __packageExports: pkg.exports ?? null,
@@ -448,6 +480,10 @@ export async function loadIntegrations(
     let gapReportHandler;
     /** @type {string | undefined} */
     let gapReportError;
+    /** @type {import('../../authoring/discover/type').DiscoverSource | undefined} */
+    let discoverSource;
+    /** @type {string | undefined} */
+    let discoverError;
     /** @type {string | undefined} */
     let agentDocsError;
     try {
@@ -457,6 +493,8 @@ export async function loadIntegrations(
         debug: debugHandler,
         gapReport: gapReportHandler,
         gapReportError,
+        discover: discoverSource,
+        discoverError,
         agentDocsError,
       } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
     } catch (err) {
@@ -507,6 +545,8 @@ export async function loadIntegrations(
       __debug: debugHandler,
       __gapReport: gapReportHandler,
       __gapReportError: gapReportError,
+      __discover: discoverSource,
+      __discoverError: discoverError,
       __spec: spec,
       __packageDir: packageDir,
       __packageExports: pkg.exports ?? null,

package/foundation/integrations/integrations.test.mjs

@@ -785,3 +785,34 @@ describe('the `gapReport` named export', () => {
     expect(loaded.__unknownKeys).toEqual(['gapReport']);
   });
 });
+
+describe('the `discover` named export', () => {
+  it('is carried out of the manifest module as __discover', async () => {
+    writeManifestPackage(tmpDir, {
+      body:
+        `export async function discover() { return {schemaVersion: 1}; }\n` +
+        `export default {issuesUrl: 'https://example.com/i'};\n`,
+    });
+
+    const [loaded] = await loadIntegrations(['@acme/widgets'], {cwd: tmpDir});
+
+    expect(typeof loaded.__discover).toBe('function');
+    expect(loaded.__discoverError).toBeUndefined();
+    expect(loaded.__unknownKeys).toEqual([]);
+    expect(loaded.issuesUrl).toBe('https://example.com/i');
+  });
+
+  it('keeps the manifest and records why when the export is not a function', async () => {
+    writeManifestPackage(tmpDir, {
+      body:
+        `export const discover = {url: 'https://example.com/catalog.json'};\n` +
+        `export default {issuesUrl: 'https://example.com/i'};\n`,
+    });
+
+    const [loaded] = await loadIntegrations(['@acme/widgets'], {cwd: tmpDir});
+
+    expect(loaded.__discover).toBeUndefined();
+    expect(loaded.__discoverError).toContain('must be a function');
+    expect(loaded.issuesUrl).toBe('https://example.com/i');
+  });
+});

package/foundation/response/batch.type.d.mts

@@ -0,0 +1,33 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * One complete row for an accepted selector.
+ */
+export type BatchRow<TResult, TCandidate> = ({
+    selector: string;
+    status: "found";
+    result: TResult;
+} | {
+    selector: string;
+    status: "ambiguous";
+    code: string;
+    error: string;
+    candidates: TCandidate[];
+} | {
+    selector: string;
+    status: "not_found" | "error";
+    code: string;
+    error: string;
+    suggestions?: import("./base").Suggestion[];
+});
+/**
+ * One ordered batch receipt inside the shared `{type, data}` success envelope.
+ */
+export type BatchResponse<TType extends string, TResult, TCandidate> = {
+    type: TType;
+    data: {
+        count: number;
+        results: BatchRow<TResult, TCandidate>[];
+    };
+};