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

package/foundation/integrations/computer-integrations.mjs

@@ -225,12 +225,19 @@ export function peerProblem(pkg, release) {
 
 /**
  * The computer-level integrations installed beside the CLI at `cliRoot`, in
- * name order (declaration order when the root declares them). Reads
+ * name order (declaration order when the root declares them), then each
+ * integration a host approves (`approved`, architecture:cli-surface INV30),
+ * resolved by name from the package set that holds that CLI alone. Reads
  * package.json files only.
- * @param {{cliRoot: string, release: string, cacheDir?: string}} options
+ * @param {{cliRoot: string, release: string, cacheDir?: string, approved?: readonly string[]}} options
  * @returns {ComputerIntegrationCandidate[]}
  */
-export function scanComputerIntegrations({cliRoot, release, cacheDir}) {
+export function scanComputerIntegrations({
+  cliRoot,
+  release,
+  cacheDir,
+  approved = [],
+}) {
   const self = real(cliRoot);
   /** @type {ComputerIntegrationCandidate[]} */
   const found = [];
@@ -238,21 +245,43 @@ export function scanComputerIntegrations({cliRoot, release, cacheDir}) {
   for (const root of computerInstallRoots(cliRoot, {cacheDir})) {
     scanRoot(root, {self, release, found, seen});
   }
+  const owner = approved.length > 0 ? installPlaceOf(self).owner : null;
+  if (owner) scanRoot(owner, {self, release, found, seen}, approved);
   return found;
 }
 
 /**
- * Add the integrations installed in one install root.
+ * `name` as installed in `root`'s own `node_modules`, never in a folder above.
+ * @param {string} name
+ * @param {string} root
+ * @returns {{packageDir: string, hostDir: string} | null}
+ */
+function ownPackageDir(name, root) {
+  const packageDir = path.join(root, 'node_modules', ...name.split('/'));
+  return fs.existsSync(path.join(packageDir, 'package.json'))
+    ? {packageDir, hostDir: root}
+    : null;
+}
+
+/**
+ * Add the integrations installed in one install root: those it declares or
+ * installs, or, given `approved`, those names installed in its own
+ * `node_modules`.
  * @param {string} root
  * @param {{self: string, release: string, found: ComputerIntegrationCandidate[], seen: Set<string>}} into
+ * @param {readonly string[] | null} [approved]
  */
-function scanRoot(root, {self, release, found, seen}) {
-  const declared = readPackage(root)
-    ? readDeclaredDependencies(root).map(d => d.name)
-    : installedNames(root);
+function scanRoot(root, {self, release, found, seen}, approved = null) {
+  const declared =
+    approved ??
+    (readPackage(root)
+      ? readDeclaredDependencies(root).map(d => d.name)
+      : installedNames(root));
   for (const name of declared) {
     if (NOT_INTEGRATIONS.has(name)) continue;
-    const resolved = resolveInstalledPackageDir(name, root);
+    const resolved = approved
+      ? ownPackageDir(name, root)
+      : resolveInstalledPackageDir(name, root);
     if (!resolved) continue;
     const identity = real(resolved.packageDir);
     if (identity === self || seen.has(identity)) continue;

package/foundation/integrations/contribution-inventory.d.mts

@@ -1,6 +1,21 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * The contribution files readers read under each declared root that is a
+ * readable folder, package-relative, without importing anything. A folder
+ * inside a root that cannot be listed is skipped.
+ * @param {{components?: string, templates?: string, codemods?: string, docs?: string, themes?: string}} loaded
+ * @param {string} pkgDir
+ * @returns {string[]}
+ */
+export function contributionFiles(loaded: {
+    components?: string;
+    templates?: string;
+    codemods?: string;
+    docs?: string;
+    themes?: string;
+}, pkgDir: string): string[];
 /**
  * @typedef {object} FileInventoryRoot
  * @property {'themes'|'components'|'templates'|'codemods'|'docs'} kind
@@ -22,26 +37,6 @@
  * @returns {FileInventory}
  */
 export function computeRequiredFiles(loaded: import("./integrations.mjs").LoadedIntegration): FileInventory;
-/**
- * @typedef {object} ContributionIdentities
- * @property {{slug: string, exportName: string}[]} themes
- * @property {string[]} components
- * @property {{id: string, type: string, name: string, replaces?: string}[]} templates
- * @property {{version: string, id: string}[]} codemods
- * @property {string[]} docs
- * @property {string[]} agentDocsAppend
- */
-/**
- * The resolved fields needed to discover contribution identities.
- * @typedef {object} IdentitySource
- * @property {string} name
- * @property {string} [themes]
- * @property {string} [components]
- * @property {string} [templates]
- * @property {string} [codemods]
- * @property {string} [docs]
- * @property {{append?: readonly string[]}} [agentDocs]
- */
 /**
  * Run the same discovery functions a consumer uses to collect every
  * contribution identity from a loaded integration.

package/foundation/integrations/contribution-inventory.mjs

@@ -137,6 +137,29 @@ const ROOT_KINDS = /** @type {const} */ ([
   'docs',
 ]);
 
+/**
+ * The contribution files readers read under each declared root that is a
+ * readable folder, package-relative, without importing anything. A folder
+ * inside a root that cannot be listed is skipped.
+ * @param {{components?: string, templates?: string, codemods?: string, docs?: string, themes?: string}} loaded
+ * @param {string} pkgDir
+ * @returns {string[]}
+ */
+export function contributionFiles(loaded, pkgDir) {
+  /** @type {Set<string>} */
+  const files = new Set();
+  for (const kind of ROOT_KINDS) {
+    const root = loaded[kind];
+    if (!root || !isFolder(root)) continue;
+    try {
+      for (const file of ENUMERATORS[kind](root, pkgDir)) files.add(file);
+    } catch {
+      // An unreadable folder inside the root.
+    }
+  }
+  return [...files].sort();
+}
+
 // ── Public: static file inventory ────────────────────────────────
 
 /**
@@ -207,6 +230,19 @@ export function computeRequiredFiles(loaded) {
  * @property {{append?: readonly string[]}} [agentDocs]
  */
 
+/**
+ * Whether `dir` is a folder to list. A declared root that is a file is
+ * reported by the root check; discovery finds nothing in it.
+ * @param {string} dir
+ */
+function isFolder(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Run the same discovery functions a consumer uses to collect every
  * contribution identity from a loaded integration.
@@ -229,7 +265,7 @@ export async function collectIdentities(loaded) {
   /** @type {Array<{kind: string, message: string}>} */
   const errors = [];
 
-  if (loaded.themes && fs.existsSync(loaded.themes)) {
+  if (loaded.themes && isFolder(loaded.themes)) {
     try {
       const themes = await discoverIntegrationThemes(
         /** @type {import('./integrations.mjs').LoadedIntegration} */ (loaded),
@@ -245,7 +281,7 @@ export async function collectIdentities(loaded) {
     }
   }
 
-  if (loaded.components && fs.existsSync(loaded.components)) {
+  if (loaded.components && isFolder(loaded.components)) {
     try {
       const records = discoverIntegrationComponents(loaded) ?? [];
       // A family doc backs several records: load it, and report it, once.
@@ -275,7 +311,7 @@ export async function collectIdentities(loaded) {
     }
   }
 
-  if (loaded.templates && fs.existsSync(loaded.templates)) {
+  if (loaded.templates && isFolder(loaded.templates)) {
     try {
       const {templates, errors: templateErrors} =
         await discoverIntegrationTemplatesForOne(loaded);
@@ -298,7 +334,7 @@ export async function collectIdentities(loaded) {
     }
   }
 
-  if (loaded.codemods && fs.existsSync(loaded.codemods)) {
+  if (loaded.codemods && isFolder(loaded.codemods)) {
     try {
       const byVersion = await discoverIntegrationCodemods([loaded]);
       /** @type {{version: string, id: string}[]} */
@@ -317,7 +353,7 @@ export async function collectIdentities(loaded) {
     }
   }
 
-  if (loaded.docs && fs.existsSync(loaded.docs)) {
+  if (loaded.docs && isFolder(loaded.docs)) {
     try {
       const {
         records,

package/foundation/integrations/exports-subpaths.d.mts

@@ -0,0 +1,57 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file How a package.json `exports` field declares a subpath, read without
+ * touching the targets (which may be build output that does not exist yet).
+ *
+ * @input A package.json `exports` value and a `.`/`./…` subpath.
+ * @output Whether the subpath is declared for an ES module importer, and why
+ *   not when it is not.
+ * @position foundation/integrations; read by the public-import checks.
+ */
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+export function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Whether an export value gives an ES module importer something: a string,
+ * or a condition object / fallback array with a target under a condition
+ * other than `require` and `types`.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function importable(value: unknown): boolean;
+/**
+ * Every string target an export value names, any condition.
+ * @param {unknown} value
+ * @param {string[]} [out]
+ * @returns {string[]}
+ */
+export function allTargets(value: unknown, out?: string[]): string[];
+/**
+ * @typedef {object} SubpathDeclaration
+ * @property {'declared'|'no_exports'|'root_only'|'missing'|'blocked'|'not_importable'} state
+ * @property {unknown} [value] the matched export value
+ * @property {string} [wildcard] what a `*` key matched
+ */
+/**
+ * How a package's `exports` field declares one subpath, without touching the
+ * targets: a missing key, a key with only a `require` condition, an `exports`
+ * that is a bare string or a condition object (so only `.`), a wildcard that
+ * does not match, or a `null` that blocks it. An `exports` of `null` is no
+ * `exports` field, as Node reads it.
+ * @param {unknown} exportsField
+ * @param {string} subpath `.` or `./…`
+ * @returns {SubpathDeclaration}
+ */
+export function subpathDeclaration(exportsField: unknown, subpath: string): SubpathDeclaration;
+export type SubpathDeclaration = {
+    state: "declared" | "no_exports" | "root_only" | "missing" | "blocked" | "not_importable";
+    /**
+     * the matched export value
+     */
+    value?: unknown;
+    /**
+     * what a `*` key matched
+     */
+    wildcard?: string | undefined;
+};

package/foundation/integrations/exports-subpaths.mjs

@@ -0,0 +1,113 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file How a package.json `exports` field declares a subpath, read without
+ * touching the targets (which may be build output that does not exist yet).
+ *
+ * @input A package.json `exports` value and a `.`/`./…` subpath.
+ * @output Whether the subpath is declared for an ES module importer, and why
+ *   not when it is not.
+ * @position foundation/integrations; read by the public-import checks.
+ */
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+export function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Whether an export value gives an ES module importer something: a string,
+ * or a condition object / fallback array with a target under a condition
+ * other than `require` and `types`.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function importable(value) {
+  if (typeof value === 'string') return true;
+  if (Array.isArray(value)) return value.some(importable);
+  if (!isRecord(value)) return false;
+  return Object.entries(value).some(
+    ([condition, target]) =>
+      condition !== 'require' && condition !== 'types' && importable(target),
+  );
+}
+
+/**
+ * Every string target an export value names, any condition.
+ * @param {unknown} value
+ * @param {string[]} [out]
+ * @returns {string[]}
+ */
+export function allTargets(value, out = []) {
+  if (typeof value === 'string') out.push(value);
+  else if (Array.isArray(value)) for (const v of value) allTargets(v, out);
+  else if (isRecord(value))
+    for (const v of Object.values(value)) allTargets(v, out);
+  return out;
+}
+
+/**
+ * @typedef {object} SubpathDeclaration
+ * @property {'declared'|'no_exports'|'root_only'|'missing'|'blocked'|'not_importable'} state
+ * @property {unknown} [value] the matched export value
+ * @property {string} [wildcard] what a `*` key matched
+ */
+
+/**
+ * How a package's `exports` field declares one subpath, without touching the
+ * targets: a missing key, a key with only a `require` condition, an `exports`
+ * that is a bare string or a condition object (so only `.`), a wildcard that
+ * does not match, or a `null` that blocks it. An `exports` of `null` is no
+ * `exports` field, as Node reads it.
+ * @param {unknown} exportsField
+ * @param {string} subpath `.` or `./…`
+ * @returns {SubpathDeclaration}
+ */
+export function subpathDeclaration(exportsField, subpath) {
+  if (exportsField == null) return {state: 'no_exports'};
+  const keys = isRecord(exportsField) ? Object.keys(exportsField) : [];
+  // An empty object is a subpath map with no keys: it exports nothing, so
+  // every subpath (the root too) is missing from it.
+  const isMap =
+    isRecord(exportsField) && keys.every(key => key.startsWith('.'));
+  if (!isMap) {
+    if (subpath !== '.') return {state: 'root_only'};
+    return importable(exportsField)
+      ? {state: 'declared', value: exportsField}
+      : {state: 'not_importable', value: exportsField};
+  }
+  const map = /** @type {Record<string, unknown>} */ (exportsField);
+  /** @type {{value: unknown, wildcard: string} | null} */
+  let hit = null;
+  if (Object.hasOwn(map, subpath)) {
+    hit = {value: map[subpath], wildcard: ''};
+  } else {
+    const patterns = keys
+      .filter(key => key.split('*').length === 2)
+      .sort((a, b) => b.indexOf('*') - a.indexOf('*') || b.length - a.length);
+    for (const pattern of patterns) {
+      const star = pattern.indexOf('*');
+      const prefix = pattern.slice(0, star);
+      const suffix = pattern.slice(star + 1);
+      if (
+        subpath.length >= prefix.length + suffix.length &&
+        subpath.startsWith(prefix) &&
+        subpath.endsWith(suffix)
+      ) {
+        hit = {
+          value: map[pattern],
+          wildcard: subpath.slice(
+            prefix.length,
+            subpath.length - suffix.length,
+          ),
+        };
+        break;
+      }
+    }
+  }
+  if (!hit) return {state: 'missing'};
+  if (hit.value == null) return {state: 'blocked'};
+  if (!importable(hit.value))
+    return {state: 'not_importable', value: hit.value, wildcard: hit.wildcard};
+  return {state: 'declared', value: hit.value, wildcard: hit.wildcard};
+}

package/foundation/integrations/integrations.d.mts

@@ -45,13 +45,14 @@ 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, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string, cliCommandError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], declaredKeys: 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, cliCommandError?: string}>}
  */
 export function loadManifest(file: string, label?: string, { fresh }?: {
     fresh?: boolean;
 }): Promise<{
     manifest: import("../../authoring/integration/type").AstryxIntegration;
     unknownKeys: string[];
+    declaredKeys: string[];
     debug?: import("../../authoring/debug/type").DebugEventHandler;
     gapReport?: import("../../authoring/gap-report/type").GapReportHandler;
     gapReportError?: string;
@@ -79,6 +80,17 @@ export function loadManifestObject(file: string, label?: string, options?: {
  * @param {string} [cwd]
  */
 export function resolvePackageDir(packageName: string, cwd?: string): string;
+/**
+ * Where an integration named in astryx.config is installed: the nearest
+ * `node_modules/<name>` at or above `cwd`, found the way an autolinked
+ * dependency is, so a package a workspace hoists to its root loads in every
+ * member. When it is installed nowhere, `cwd`'s own `node_modules/<name>`,
+ * which the caller reports as not installed.
+ * @param {string} packageName
+ * @param {string} [cwd]
+ * @returns {string}
+ */
+export function resolveInstalledIntegrationDir(packageName: string, cwd?: string): string;
 /**
  * Load the integration package rooted at `packageDir` directly, without first
  * installing or publishing it. This is the self-resolution seam: an author in
@@ -134,6 +146,8 @@ export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProvider
  * @property {string} [__agentDocsError] contribution-specific validation
  *   failure; other manifest contributions remain available
  * @property {string} __spec
+ * @property {string} [__declaredProviderId] the manifest's `providerId` as
+ *   written, kept by validation so it can tell whether the package has one
  * @property {string} __packageDir
  * @property {Record<string, unknown>|null} [__packageExports] the owning
  *   package's `exports` map, kept from the package.json this loader already
@@ -145,6 +159,8 @@ export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProvider
  *   set on a package whose provider ID an earlier-loaded package already
  *   claims; it contributes nothing and is reported as a `duplicate_provider`
  *   warning
+ * @property {string[]} [__declaredKeys] the keys the manifest object itself
+ *   declares, before any is filled in (providerId from the package name)
  * @property {string[]} [__unknownKeys] manifest keys this CLI does not know —
  *   surfaced as a warning; the rest of the manifest still contributes
  * @property {boolean} [__autolinked] loaded because the project declares the
@@ -210,6 +226,11 @@ export type LoadedIntegration = {
      */
     __agentDocsError?: string | undefined;
     __spec: string;
+    /**
+     * the manifest's `providerId` as
+     * written, kept by validation so it can tell whether the package has one
+     */
+    __declaredProviderId?: string | undefined;
     __packageDir: string;
     /**
      * the owning
@@ -233,6 +254,11 @@ export type LoadedIntegration = {
         claimedBy: string;
         message: string;
     } | undefined;
+    /**
+     * the keys the manifest object itself
+     * declares, before any is filled in (providerId from the package name)
+     */
+    __declaredKeys?: string[] | undefined;
     /**
      * manifest keys this CLI does not know —
      * surfaced as a warning; the rest of the manifest still contributes

package/foundation/integrations/integrations.mjs

@@ -19,6 +19,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {assertWithin} from '../fs/path-safety.mjs';
+import {findNodeModulesPackage} from '../fs/paths.mjs';
 import {normalizeProviderId} from '../identity/provider-identity.mjs';
 // The key census and contribution parsers are internal to the schema module on
 // purpose: the public parser still validates the complete authored type, while
@@ -60,6 +61,8 @@ import {resolveProviders} from './provider-resolution.mjs';
  * @property {string} [__agentDocsError] contribution-specific validation
  *   failure; other manifest contributions remain available
  * @property {string} __spec
+ * @property {string} [__declaredProviderId] the manifest's `providerId` as
+ *   written, kept by validation so it can tell whether the package has one
  * @property {string} __packageDir
  * @property {Record<string, unknown>|null} [__packageExports] the owning
  *   package's `exports` map, kept from the package.json this loader already
@@ -71,6 +74,8 @@ import {resolveProviders} from './provider-resolution.mjs';
  *   set on a package whose provider ID an earlier-loaded package already
  *   claims; it contributes nothing and is reported as a `duplicate_provider`
  *   warning
+ * @property {string[]} [__declaredKeys] the keys the manifest object itself
+ *   declares, before any is filled in (providerId from the package name)
  * @property {string[]} [__unknownKeys] manifest keys this CLI does not know —
  *   surfaced as a warning; the rest of the manifest still contributes
  * @property {boolean} [__autolinked] loaded because the project declares the
@@ -213,7 +218,7 @@ function parseDiscoverSourceExport(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, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string, cliCommandError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], declaredKeys: 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, cliCommandError?: string}>}
  */
 export async function loadManifest(
   file,
@@ -222,6 +227,7 @@ export async function loadManifest(
 ) {
   const mod = await importUserModule(file, {fresh});
   const raw = mod?.default;
+  if (raw === undefined) throw new Error(noDefaultExportMessage(file, label, mod));
   const baseManifest = parseIntegrationBase(raw, label);
   const gapReport = parseGapReportHandlerExport(mod?.gapReport, label);
   const discover = parseDiscoverSourceExport(mod?.discover, label);
@@ -274,6 +280,8 @@ export async function loadManifest(
       ...(cliCommand == null ? {} : {cliCommand}),
     },
     unknownKeys: unknownIntegrationKeys(raw),
+    declaredKeys:
+      raw != null && typeof raw === 'object' ? Object.keys(raw) : [],
     debug:
       typeof mod?.debug === 'function'
         ? /** @type {import('../../authoring/debug/type').DebugEventHandler} */ (
@@ -289,6 +297,30 @@ export async function loadManifest(
   };
 }
 
+/**
+ * Why a manifest has no default export, said plainly instead of as a schema
+ * failure on `undefined`: the file is empty, or it exports other names.
+ * @param {string} file
+ * @param {string} label
+ * @param {Record<string, unknown> | undefined} mod
+ */
+function noDefaultExportMessage(file, label, mod) {
+  const fix = `Fix: export the manifest object as the default export: \`export default {components: './components'}\`, naming the roots the package has.`;
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    // Unreadable now: say only what is missing.
+  }
+  const names = Object.keys(mod ?? {}).filter(name => name !== 'default');
+  if (text.trim() === '') return `${label} is empty. ${fix}`;
+  const found =
+    names.length > 0
+      ? ` (it exports ${names.map(name => `\`${name}\``).join(', ')})`
+      : '';
+  return `${label} has no default export${found}. ${fix}`;
+}
+
 /**
  * Load and validate a manifest module's default export against the integration
  * schema. Throws if the default export is missing or invalid. Exposed for
@@ -337,6 +369,25 @@ export function resolvePackageDir(packageName, cwd = process.cwd()) {
   return dir;
 }
 
+/**
+ * Where an integration named in astryx.config is installed: the nearest
+ * `node_modules/<name>` at or above `cwd`, found the way an autolinked
+ * dependency is, so a package a workspace hoists to its root loads in every
+ * member. When it is installed nowhere, `cwd`'s own `node_modules/<name>`,
+ * which the caller reports as not installed.
+ * @param {string} packageName
+ * @param {string} [cwd]
+ * @returns {string}
+ */
+export function resolveInstalledIntegrationDir(
+  packageName,
+  cwd = process.cwd(),
+) {
+  // Validates the name first: it throws on a spec with path segments.
+  const ownDir = resolvePackageDir(packageName, cwd);
+  return findNodeModulesPackage(cwd, packageName)?.packageDir ?? ownDir;
+}
+
 /**
  * Find the single conventional root manifest sibling of the package's
  * package.json. Multiple present is a hard error; missing is a hard error.
@@ -396,6 +447,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
   let manifest;
   /** @type {string[]} */
   let unknownKeys;
+  /** @type {string[]} */
+  let declaredKeys;
   /** @type {import('../../authoring/debug/type').DebugEventHandler | undefined} */
   let debugHandler;
   /** @type {import('../../authoring/gap-report/type').GapReportHandler | undefined} */
@@ -414,6 +467,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     ({
       manifest,
       unknownKeys,
+      declaredKeys,
       debug: debugHandler,
       gapReport: gapReportHandler,
       gapReportError,
@@ -462,6 +516,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     __cliCommandError: cliCommandError,
     __agentDocsError: agentDocsError,
     __unknownKeys: unknownKeys,
+    __declaredKeys: declaredKeys,
     __debug: debugHandler,
     __gapReport: gapReportHandler,
     __gapReportError: gapReportError,
@@ -496,7 +551,7 @@ export async function loadIntegrations(
     if (!spec || seenSpecs.has(spec)) continue;
     seenSpecs.add(spec);
 
-    const packageDir = resolvePackageDir(spec, cwd);
+    const packageDir = resolveInstalledIntegrationDir(spec, cwd);
     const pkgPath = path.join(packageDir, 'package.json');
     let pkg;
     try {
@@ -512,6 +567,8 @@ export async function loadIntegrations(
     let manifest;
     /** @type {string[]} */
     let unknownKeys;
+    /** @type {string[]} */
+    let declaredKeys;
     /** @type {import('../../authoring/debug/type').DebugEventHandler | undefined} */
     let debugHandler;
     /** @type {import('../../authoring/gap-report/type').GapReportHandler | undefined} */
@@ -530,6 +587,7 @@ export async function loadIntegrations(
       ({
         manifest,
         unknownKeys,
+        declaredKeys,
         debug: debugHandler,
         gapReport: gapReportHandler,
         gapReportError,
@@ -585,6 +643,7 @@ export async function loadIntegrations(
       __cliCommandError: cliCommandError,
       __agentDocsError: agentDocsError,
       __unknownKeys: unknownKeys,
+      __declaredKeys: declaredKeys,
       __debug: debugHandler,
       __gapReport: gapReportHandler,
       __gapReportError: gapReportError,