@astryxdesign/cli 0.6.4 → 0.6.5-canary.031021b

package/foundation/discovery/authoring-self-docs.test.mjs

@@ -63,7 +63,9 @@ describe('authoring self-docs', () => {
 describe('what the authoring docs say about the docs tree', () => {
   it('marks exactly the fields the docs tree does not read yet', () => {
     const notReadYet = graphFieldsDoc.fields
-      .filter(field => /Not read yet/.test(field.description))
+      .filter(field =>
+        /^Reserved: .*Nothing reads it today/.test(field.description),
+      )
       .map(field => field.name);
     // The tree reads `placement` for every guide (spec:AST-046); the other
     // graph fields are still refused by every topic reader.
@@ -79,7 +81,9 @@ describe('what the authoring docs say about the docs tree', () => {
     expect(placement.description).toMatch(
       /Read for every guide, the CLI's and each integration's/,
     );
-    expect(graphFieldsDoc.description).toMatch(/not built yet/);
+    expect(graphFieldsDoc.description).toMatch(
+      /Nothing reads `aliases` or `audience` today/,
+    );
   });
 
   it('keeps graph blocks behind the separate GraphContentBlock type, and a section takes a reference block', () => {

package/foundation/discovery/cli-self-docs.mjs

@@ -315,12 +315,20 @@ function functionSection(fn, index) {
   }
   const params = fn.params ?? [];
   if (params.length > 0) {
+    // A Default column only when some parameter declares a default, so a
+    // function with none keeps a three-column table.
+    const defaults = params.some(
+      (/** @type {any} */ p) => typeof p.default === 'string' && p.default !== '',
+    );
     content.push({
       type: 'table',
-      headers: ['Parameter', 'Type', 'Description'],
+      headers: defaults
+        ? ['Parameter', 'Type', 'Default', 'Description']
+        : ['Parameter', 'Type', 'Description'],
       rows: params.map((/** @type {any} */ p) => [
-        `\`${p.name}\``,
+        `\`${p.name}\`${p.required ? ' (required)' : ''}`,
         `\`${p.type ?? ''}\``,
+        ...(defaults ? [p.default ?? ''] : []),
         p.description ?? '',
       ]),
     });
@@ -405,6 +413,12 @@ export function cliDocSection(doc, index) {
   if (doc.type === 'command') return commandSection(doc, index);
   if (doc.type === 'function') return functionSection(doc, index);
   if (doc.type === 'enum') return enumSection(doc);
+  if (doc.type === 'namespace')
+    return {
+      id: routeSegment(doc.name),
+      title: doc.title,
+      content: doc.blocks ?? [],
+    };
   return {...selfDocSection(doc), id: routeSegment(doc.name)};
 }
 

package/foundation/discovery/cli-self-docs.test.mjs

@@ -315,6 +315,26 @@ describe('cliDocSection', () => {
     ]);
   });
 
+  it('marks required parameters and adds a Default column when a parameter has a default', () => {
+    const beta = fn('beta', {
+      params: [
+        {name: 'slug', type: 'string', description: 'The slug.', required: true},
+        {name: 'options.limit', type: 'number', description: 'How many.', default: '20'},
+      ],
+    });
+    const table = cliDocSection(beta, indexOf([beta])).content.find(
+      (/** @type {any} */ block) => block.type === 'table',
+    );
+    expect(table).toEqual({
+      type: 'table',
+      headers: ['Parameter', 'Type', 'Default', 'Description'],
+      rows: [
+        ['`slug` (required)', '`string`', '', 'The slug.'],
+        ['`options.limit`', '`number`', '20', 'How many.'],
+      ],
+    });
+  });
+
   it('renders an API function, an enum, and a schema', () => {
     const alpha = fn('alpha', {
       description: 'Longer.',

package/foundation/discovery/docs-discovery.mjs

@@ -626,7 +626,11 @@ function findMergeTarget(sections, section) {
   const sameTitle = sections.findIndex(
     candidate => sourceTitle(candidate) === title,
   );
-  return sameTitle;
+  if (sameTitle !== -1) return sameTitle;
+  // A base section retitled later keeps its old key as its `id`, so an
+  // extension that still names it by the old title finds it by that id. A
+  // title variant of a section with no id stays a separate section.
+  return sections.findIndex(candidate => candidate.id === key);
 }
 
 /**

package/foundation/discovery/docs-discovery.test.mjs

@@ -509,6 +509,27 @@ describe('mergeTopic', () => {
     expect(base.sections[0].content[0].text).toBe('npm i');
   });
 
+  it('finds a retitled base section by the key its old title derives', () => {
+    // A base section retitled later keeps its old key as its `id`; an
+    // extension that still names it by the old title replaces it.
+    const merged = mergeTopic(
+      {
+        ...base,
+        sections: [
+          {id: 'quick-start', title: 'Wrap your app in a theme', content: []},
+          {id: 'tokens', title: 'Tokens', content: []},
+        ],
+      },
+      {sections: [{title: 'Quick Start', content: []}]},
+    );
+    expect(merged.sections.map(section => [section.id, section.title])).toEqual(
+      [
+        ['quick-start', 'Quick Start'],
+        ['tokens', 'Tokens'],
+      ],
+    );
+  });
+
   it('replaces a section by stable ID even when its title changes', () => {
     const merged = mergeTopic(
       {

package/foundation/discovery/docs-section-key.d.mts

@@ -32,7 +32,7 @@ export function sectionTitleKey(title: unknown): string;
 export function sectionKey(section: any): string;
 /**
  * A name as a docs-tree route segment: lowercase words joined by hyphens, so
- * `integrationPackCheck` and `integration pack` both read naturally.
+ * `integrationPackCheck` and `integration verify` both read naturally.
  * @param {string} name
  * @returns {string}
  */

package/foundation/discovery/docs-section-key.mjs

@@ -95,7 +95,7 @@ function legacyTitleMatchIndex(sections, query) {
 
 /**
  * A name as a docs-tree route segment: lowercase words joined by hyphens, so
- * `integrationPackCheck` and `integration pack` both read naturally.
+ * `integrationPackCheck` and `integration verify` both read naturally.
  * @param {string} name
  * @returns {string}
  */

package/foundation/doc-compiler/doc-loads.test.mjs

@@ -53,8 +53,8 @@ const RUNNERS = {
     sites: ['import(node:child_process)', 'worker_threads.Worker'],
   },
   'api/integration/pack-check.mjs': {
-    runs: '`npm pack`, `tar`, and a Node script that resolves the packed specifiers, to check a package as published',
-    sites: ['child_process.spawnSync ×3'],
+    runs: '`npm pack`, `tar`, and a Node script that resolves the packed specifiers, to check a package as published, and the package\'s doc modules, to see which need a newer CLI',
+    sites: ['child_process.spawnSync ×3', 'loadTopicModule'],
   },
   'api/swizzle/_github.mjs': {
     runs: '`gh auth status`, to check the GitHub CLI is signed in',
@@ -188,6 +188,7 @@ const RUNNERS = {
       'import ../../../api/integration/integrationPackCheck.doc.mjs',
       'import ./integration-add.doc.mjs',
       'import ./integration-pack.doc.mjs',
+      'import ./integration-verify.doc.mjs',
       'import ./integration.doc.mjs',
     ],
   },

package/foundation/doc-compiler/inputs.test.mjs

@@ -90,7 +90,6 @@ describe('collectDocInputs over what this repo ships', () => {
     ).toEqual([
       'Chat',
       'ChatComposerTokenElement',
-      'Code',
       'ContextMenuItem',
       'Heading',
       'Indicator',

package/foundation/doc-compiler/tree.d.mts

@@ -240,6 +240,10 @@ export type TreeNode = {
     name: string;
     title: string;
     summary: string;
+    /**
+     * an authored namespace's search keywords
+     */
+    keywords?: string[] | undefined;
     /**
      * the parent's route; null at the top
      */

package/foundation/doc-compiler/tree.mjs

@@ -58,7 +58,7 @@ export const KIND_GROUPS = Object.freeze({
   schema: {
     segment: 'schemas',
     title: 'Schemas',
-    summary: 'Every shape the CLI reads or returns, field by field.',
+    summary: 'Data shapes, field by field.',
   },
   enum: {
     segment: 'enums',
@@ -140,6 +140,7 @@ export const UNORGANIZED = 'unorganized';
  * @property {string} name
  * @property {string} title
  * @property {string} summary
+ * @property {string[]} [keywords] an authored namespace's search keywords
  * @property {string | null} parent the parent's route; null at the top
  * @property {string | null} slot the parent slot this node sits in
  * @property {number | null} order
@@ -420,10 +421,14 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
         name: input.doc.name,
         title: input.doc.title,
         summary: input.doc.summary,
+        ...(Array.isArray(input.doc.keywords)
+          ? {keywords: input.doc.keywords}
+          : {}),
         parent: parentRoute,
         slot: home?.slot ?? null,
         order: home?.order ?? null,
         generated: false,
+        ref: {selfDoc: input.doc},
         slots: Object.entries(input.doc.slots).map(([name, slot]) => ({
           name,
           title: slot.title,

package/foundation/integrations/cli-requirement.d.mts

@@ -20,13 +20,31 @@ export function lowestAdmitted(range: unknown): string | null;
  */
 export function docsTreeCliProblem(pkg: any): string | null;
 /**
- * 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}
  */
 export function replacesCliProblem(pkg: any): string | null;
+/**
+ * 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.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function sectionIdsCliProblem(pkg: any): string | null;
+/**
+ * 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.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function themesCliProblem(pkg: any): string | null;
 /**
  * The package.json with a CLI peer that reads namespace docs: optional, unless
  * the package already says otherwise.
@@ -37,9 +55,11 @@ export function withDocsTreeCli(pkg: any): any;
 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.
+ * and placed guides), its templates' `replaces`, and its typed theme
+ * descriptors. A release before it can hide every doc topic a package with a
+ * namespace doc or a placed guide ships, with no warning; it rejects
+ * `replaces`, drops that template, and hides the package's doc topics; and it
+ * rejects a themes root without the `manifest.json` catalog the CLI no longer
+ * writes, withholding the package's themes and doc topics.
  */
 export const DOCS_TREE_CLI: "0.7.0";

package/foundation/integrations/cli-requirement.mjs

@@ -6,8 +6,9 @@
  * @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.
+ * @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';
@@ -16,10 +17,12 @@ 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.
+ * and placed guides), its templates' `replaces`, and its typed theme
+ * descriptors. A release before it can hide every doc topic a package with a
+ * namespace doc or a placed guide ships, with no warning; it rejects
+ * `replaces`, drops that template, and hides the package's doc topics; and it
+ * rejects a themes root without the `manifest.json` catalog the CLI no longer
+ * writes, withholding the package's themes and doc topics.
  */
 export const DOCS_TREE_CLI = '0.7.0';
 
@@ -92,11 +95,11 @@ function cliRangeProblem(pkg, feature, loss) {
   const range = pkg?.peerDependencies?.[CLI_PACKAGE];
   const fix = `"${CLI_PACKAGE}": ">=${DOCS_TREE_CLI}" 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 ${DOCS_TREE_CLI} ${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}.`;
+    return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a stable CLI before ${DOCS_TREE_CLI}, which ${loss}. Declare ${fix}.`;
   }
   return null;
 }
@@ -119,8 +122,8 @@ export function docsTreeCliProblem(pkg) {
 }
 
 /**
- * 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,7 +132,39 @@ 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",
+  );
+}
+
+/**
+ * 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.
+ * @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',
+  );
+}
+
+/**
+ * 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.
+ * @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",
   );
 }
 

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

@@ -32,6 +32,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.7.0 does not read the docs tree',
+    );
   });
 
   it.each(['^0.6.0', '^0.6.0 || >=0.7.0', '*', '>=0.6.3'])(
@@ -39,7 +44,7 @@ describe('docsTreeCliProblem', () => {
     range => {
       expect(
         docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
-      ).toContain('admits a CLI older than');
+      ).toContain('admits a stable CLI before');
     },
   );
 
@@ -76,7 +81,7 @@ 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();

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>[];
+    };
+};