@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/foundation/integrations/integrations.mjs

@@ -6,13 +6,19 @@
  * Integrations are PACKAGE NAMES listed in astryx.config.{ts,mjs,js}. Each
  * package declares a single conventional root manifest sibling to its
  * package.json — astryx.integration.{ts,mjs,js} — which contributes
- * components/templates/codemods/docs/themes roots and an optional issuesUrl. Identity
- * (name, version) comes from the package's package.json, not the manifest.
+ * components/templates/codemods/docs/themes roots and an optional issuesUrl.
+ * Stable provider identity and package metadata come from package.json, not the
+ * manifest.
+ *
+ * @input Integration package names, package.json files, and root manifests.
+ * @output LoadedIntegration records with normalized provider identity and roots.
+ * @position foundation/integrations — package contribution loading boundary.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {assertWithin} from '../fs/path-safety.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
 // the loader can isolate an invalid optional contribution from valid roots.
@@ -23,6 +29,8 @@ 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';
 
 /**
  * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
@@ -31,6 +39,10 @@ import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
  * are internal bookkeeping used by Doctor integration validation and Project.
  * @typedef {object} LoadedIntegration
  * @property {string} name
+ * @property {import('../../authoring/identity/type').ProviderId} [providerId]
+ *   normalized stable provider identity; absent only for a legacy unnamed local
+ *   package. Unique among contributing integrations: a later claimant is kept
+ *   inert with `__providerConflict` (see {@link markProviderConflicts})
  * @property {string} [version]
  * @property {string} [components]
  * @property {string} [templates]
@@ -49,6 +61,10 @@ import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
  * @property {string} __manifestFile
  * @property {string} [__loadError] set when the manifest failed to load/validate;
  *   such an integration contributes nothing and is surfaced via Project.issues()
+ * @property {{providerId: import('../../authoring/identity/type').ProviderId, claimedBy: string, message: string}} [__providerConflict]
+ *   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[]} [__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
@@ -65,6 +81,9 @@ import {parseGapReportHandler} from '../../authoring/gap-report/parse.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. */
@@ -74,6 +93,50 @@ export const MANIFEST_BASENAMES = [
   'astryx.integration.js',
 ];
 
+/**
+ * Normalize a package-owned provider ID without rejecting legacy unnamed local
+ * packages at this compatibility boundary.
+ * @param {unknown} name
+ * @returns {import('../../authoring/identity/type').ProviderId | undefined}
+ */
+function providerIdForPackage(name) {
+  if (typeof name !== 'string' || name.length === 0) return undefined;
+  try {
+    return normalizeProviderId(name);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve provider identity across loaded integrations, in precedence order.
+ *
+ * Artifact and document IDs are provider-scoped, so two packages cannot both
+ * contribute under one provider ID. The same package reached twice (an npm
+ * alias beside the package it aliases, with the same name and version) loads
+ * once. Any other later claimant, including the same package at another
+ * version, stays as an inert entry that carries the conflict. The package being
+ * authored claims its ID before precedence order is considered, because the
+ * source being edited is authoritative. The winner still contributes; Project
+ * issues, Doctor, and the per-command warning name the one set aside instead of
+ * dropping it without a word.
+ *
+ * The conflict pass of {@link resolveProviders}, for a list that is already
+ * assembled.
+ *
+ * @param {LoadedIntegration[]} integrations in precedence order
+ * @returns {LoadedIntegration[]}
+ */
+export function markProviderConflicts(integrations) {
+  return resolveProviders(
+    integrations.map(integration => ({
+      source: /** @type {const} */ ('configured'),
+      integration,
+      spec: integration?.__spec,
+    })),
+  ).integrations;
+}
+
 /**
  * Return the conventional root manifest paths present in `dir`, in
  * load-precedence order. Unlike {@link resolveManifestPath} this never throws —
@@ -108,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.
@@ -124,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,
@@ -135,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' &&
@@ -169,6 +250,8 @@ export async function loadManifest(
         : undefined,
     gapReport: gapReport.handler,
     gapReportError: gapReport.error,
+    discover: discover.source,
+    discoverError: discover.error,
     agentDocsError,
   };
 }
@@ -274,6 +357,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     typeof pkg.name === 'string' && pkg.name.length > 0
       ? pkg.name
       : '(local integration)';
+  const packageProviderId = providerIdForPackage(pkg.name);
   const manifestFile = resolveManifestPath(packageDir, spec);
 
   let manifest;
@@ -285,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 {
@@ -294,11 +382,14 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
       debug: debugHandler,
       gapReport: gapReportHandler,
       gapReportError,
+      discover: discoverSource,
+      discoverError,
       agentDocsError,
     } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
   } catch (err) {
     return {
       name: spec,
+      ...(packageProviderId == null ? {} : {providerId: packageProviderId}),
       version: pkg.version,
       __spec: spec,
       __packageDir: packageDir,
@@ -308,6 +399,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     };
   }
 
+  const providerId = providerIdForPackage(manifest.providerId ?? pkg.name);
+
   /** @param {string | null | undefined} value */
   const resolveRoot = value => {
     if (value == null) return undefined;
@@ -320,6 +413,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
 
   return {
     name: spec,
+    ...(providerId == null ? {} : {providerId}),
     version: pkg.version,
     components: resolveRoot(manifest.components),
     templates: resolveRoot(manifest.templates),
@@ -333,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,
@@ -345,20 +441,22 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
  * Load configured integrations.
  *
  * @param {string[]} [specs] package names
- * @param {{cwd?: string, fresh?: boolean}} [options]
+ * @param {{cwd?: string, fresh?: boolean, resolveProviders?: boolean}} [options]
+ *   `resolveProviders: false` leaves provider identity to a caller that
+ *   resolves it once over a larger set (Project.load)
  * @returns {Promise<LoadedIntegration[]>}
  */
 export async function loadIntegrations(
   specs = [],
-  {cwd = process.cwd(), fresh = false} = {},
+  {cwd = process.cwd(), fresh = false, resolveProviders = true} = {},
 ) {
   /** @type {LoadedIntegration[]} */
   const integrations = [];
-  const seen = new Set();
+  const seenSpecs = new Set();
 
   for (const spec of specs) {
-    if (!spec || seen.has(spec)) continue;
-    seen.add(spec);
+    if (!spec || seenSpecs.has(spec)) continue;
+    seenSpecs.add(spec);
 
     const packageDir = resolvePackageDir(spec, cwd);
     const pkgPath = path.join(packageDir, 'package.json');
@@ -371,6 +469,7 @@ export async function loadIntegrations(
       );
     }
 
+    const packageProviderId = providerIdForPackage(pkg.name ?? spec);
     const manifestFile = resolveManifestPath(packageDir, spec);
     let manifest;
     /** @type {string[]} */
@@ -381,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 {
@@ -390,6 +493,8 @@ export async function loadIntegrations(
         debug: debugHandler,
         gapReport: gapReportHandler,
         gapReportError,
+        discover: discoverSource,
+        discoverError,
         agentDocsError,
       } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
     } catch (err) {
@@ -399,6 +504,7 @@ export async function loadIntegrations(
       // discovery loops naturally skip it (no components/templates/codemods).
       integrations.push({
         name: pkg.name ?? spec,
+        ...(packageProviderId == null ? {} : {providerId: packageProviderId}),
         version: pkg.version,
         __spec: spec,
         __packageDir: packageDir,
@@ -408,6 +514,10 @@ export async function loadIntegrations(
       continue;
     }
 
+    const providerId = providerIdForPackage(
+      manifest.providerId ?? pkg.name ?? spec,
+    );
+
     /** @param {string | null | undefined} value */
     const resolveRoot = value => {
       if (value == null) return undefined;
@@ -421,6 +531,7 @@ export async function loadIntegrations(
 
     integrations.push({
       name: pkg.name ?? spec,
+      ...(providerId == null ? {} : {providerId}),
       version: pkg.version,
       components: resolveRoot(manifest.components),
       templates: resolveRoot(manifest.templates),
@@ -434,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,
@@ -441,5 +554,5 @@ export async function loadIntegrations(
     });
   }
 
-  return integrations;
+  return resolveProviders ? markProviderConflicts(integrations) : integrations;
 }