Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
24.5 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Integration manifest loading for Astryx config.
 *
 * 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 the experimental
 * `experimental.iconSets` root), an optional issuesUrl, and an optional
 * cliCommand.
 * 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 {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
// the loader can isolate an invalid optional contribution from valid roots.
import {
  parseAgentDocsField,
  parseCliCommandField,
  parseIntegrationBase,
  unknownIntegrationKeys,
} from '../../authoring/integration/schema.mjs';
import {importUserModule, findPresentFiles} from '../fs/module-loader.mjs';
import {findManifestPaths, MANIFEST_BASENAMES} from './manifest-paths.mjs';

export {findManifestPaths, MANIFEST_BASENAMES};
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
 * the package's package.json; the `components`/`templates`/`codemods`/`docs`/
 * `themes` roots are absolute paths resolved from the manifest. The `__`-prefixed fields
 * 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]
 * @property {string} [codemods]
 * @property {string} [docs]
 * @property {string} [themes]
 * @property {string} [iconSets] the manifest's `experimental.iconSets` root
 * @property {string} [issuesUrl]
 * @property {{append?: readonly string[]}} [agentDocs]
 * @property {string} [cliCommand] the command this package's users run the
 *   CLI with; read by the picker in foundation/env (see cli-command.mjs)
 * @property {string} [__cliCommandError] why a declared `cliCommand` was
 *   ignored; the rest of the manifest still contributes
 * @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
 *   parsed so import resolution does not read it a second time
 * @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[]} [__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
 *   package as a dependency and it ships a manifest, with no astryx.config
 *   entry naming it — see foundation/integrations/autolink.mjs
 * @property {boolean} [__computer] loaded because it is installed beside the
 *   running CLI and the folder is outside a project (spec AST-081 FR12) — see
 *   foundation/integrations/computer-integrations.mjs
 * @property {boolean} [__local] loaded from the package containing the current
 *   working directory, so an author sees the exact bytes they are editing
 * @property {string} [__dependencyField] for an autolinked integration, the
 *   package.json field that declared it (`dependencies`, `devDependencies`,
 *   `optionalDependencies`)
 * @property {import('../../authoring/debug/type').DebugEventHandler} [__debug]
 *   the manifest module's `debug` NAMED export, when it exported a function.
 * @property {import('../../authoring/gap-report/type').GapReportHandler} [__gapReport]
 *   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.
 */


/**
 * 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;
}


/**
 * Parse the optional named gap-report handler without making it part of the
 * default manifest schema. A malformed handler is isolated from every other
 * integration contribution and represented as a failed delivery at fan-out.
 *
 * @param {unknown} value
 * @param {string} label
 * @returns {{handler?: import('../../authoring/gap-report/type').GapReportHandler, error?: string}}
 */
function parseGapReportHandlerExport(value, label) {
  if (value === undefined) return {};
  try {
    return {
      handler: parseGapReportHandler(
        value,
        `${label} named export "gapReport"`,
      ),
    };
  } catch (error) {
    return {error: error instanceof Error ? error.message : String(error)};
  }
}

/**
 * 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.
 *
 * The base manifest still fails as one unit when a root or `issuesUrl` is
 * invalid. `agentDocs` is parsed separately: a bad contribution is returned as
 * `agentDocsError`, while valid components/templates/docs/codemods stay loaded.
 * The raw object is also inspected before parsing so unknown-key warnings retain
 * forward compatibility.
 *
 * `debug` and `gapReport` come back separately because they are named exports,
 * not manifest keys. A CLI that does not know them simply does not read them.
 *
 * @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[], 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,
  label = 'integration manifest',
  {fresh = false} = {},
) {
  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);
  const hasAgentDocs =
    raw != null &&
    typeof raw === 'object' &&
    !Array.isArray(raw) &&
    Object.prototype.hasOwnProperty.call(raw, 'agentDocs');
  const rawAgentDocs = hasAgentDocs
    ? /** @type {{agentDocs?: unknown}} */ (raw).agentDocs
    : undefined;
  /** @type {import('../../authoring/integration/type').AstryxIntegration['agentDocs']} */
  let agentDocs;
  /** @type {string | undefined} */
  let agentDocsError;
  if (hasAgentDocs && rawAgentDocs !== undefined) {
    try {
      agentDocs = parseAgentDocsField(
        rawAgentDocs,
        `${label} field "agentDocs"`,
      );
    } catch (err) {
      agentDocsError = err instanceof Error ? err.message : String(err);
    }
  }

  /** @type {string | undefined} */
  let cliCommand;
  /** @type {string | undefined} */
  let cliCommandError;
  const rawCliCommand =
    raw != null && typeof raw === 'object' && !Array.isArray(raw)
      ? /** @type {{cliCommand?: unknown}} */ (raw).cliCommand
      : undefined;
  if (rawCliCommand !== undefined) {
    try {
      cliCommand = parseCliCommandField(
        rawCliCommand,
        `${label} field "cliCommand"`,
      );
    } catch (err) {
      cliCommandError = err instanceof Error ? err.message : String(err);
    }
  }

  return {
    manifest: {
      ...baseManifest,
      ...(agentDocs == null ? {} : {agentDocs}),
      ...(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} */ (
            mod.debug
          )
        : undefined,
    gapReport: gapReport.handler,
    gapReportError: gapReport.error,
    discover: discover.source,
    discoverError: discover.error,
    agentDocsError,
    cliCommandError,
  };
}

/**
 * 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
 * Doctor integration validation.
 * @param {string} file absolute manifest path
 * @param {string} [label] used in error messages
 * @param {{fresh?: boolean}} [options]
 * @returns {Promise<import('../../authoring/integration/type').AstryxIntegration>}
 */
export async function loadManifestObject(
  file,
  label = 'integration manifest',
  options,
) {
  return (await loadManifest(file, label, options)).manifest;
}

/**
 * Resolve the directory of an installed integration package from the consumer's
 * node_modules.
 * @param {string} packageName
 * @param {string} [cwd]
 */
export function resolvePackageDir(packageName, cwd = process.cwd()) {
  // An integration spec is a bare npm package name — never a path. Reject `..`,
  // `.`, and absolute specs so a config can't point the loader (which then
  // dynamically imports the manifest) at an arbitrary module outside
  // node_modules.
  if (
    typeof packageName !== 'string' ||
    packageName.length === 0 ||
    path.isAbsolute(packageName) ||
    packageName.split('/').some(seg => seg === '..' || seg === '.')
  ) {
    throw new Error(
      `Invalid integration package name "${packageName}". Use a bare package name (no path segments).`,
    );
  }
  const nodeModules = path.resolve(cwd, 'node_modules');
  const dir = path.resolve(nodeModules, ...packageName.split('/'));
  if (dir !== nodeModules && !dir.startsWith(nodeModules + path.sep)) {
    throw new Error(
      `Integration "${packageName}" resolves outside node_modules.`,
    );
  }
  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.
 * @param {string} packageDir
 * @param {string} spec
 * @returns {string} absolute manifest path
 */
function resolveManifestPath(packageDir, spec) {
  const present = findPresentFiles(packageDir, MANIFEST_BASENAMES);
  if (present.length === 0) {
    throw new Error(
      `Integration package "${spec}" has no conventional root manifest. Add one of: ${MANIFEST_BASENAMES.join(', ')} next to its package.json.`,
    );
  }
  if (present.length > 1) {
    throw new Error(
      `Integration package "${spec}" has multiple root manifests (${present
        .map(file => path.basename(file))
        .join(', ')}). Keep exactly one.`,
    );
  }
  return present[0];
}

/**
 * Load the integration package rooted at `packageDir` directly, without first
 * installing or publishing it. This is the self-resolution seam: an author in
 * a package with a manifest sees the same contributions a consumer installs.
 *
 * A missing manifest returns null. A broken manifest returns the same load-error
 * marker as an installed integration, so Project issues stay truthful.
 *
 * @param {string} packageDir
 * @param {{fresh?: boolean}} [options]
 * @returns {Promise<LoadedIntegration|null>}
 */
export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
  const manifests = findManifestPaths(packageDir);
  if (manifests.length === 0) return null;

  const pkgPath = path.join(packageDir, 'package.json');
  let pkg;
  try {
    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
  } catch {
    throw new Error(
      `Could not read the local integration package at ${pkgPath}.`,
    );
  }
  const spec =
    typeof pkg.name === 'string' && pkg.name.length > 0
      ? pkg.name
      : '(local integration)';
  const packageProviderId = providerIdForPackage(pkg.name);
  const manifestFile = resolveManifestPath(packageDir, spec);

  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} */
  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;
  /** @type {string | undefined} */
  let cliCommandError;
  try {
    ({
      manifest,
      unknownKeys,
      declaredKeys,
      debug: debugHandler,
      gapReport: gapReportHandler,
      gapReportError,
      discover: discoverSource,
      discoverError,
      agentDocsError,
      cliCommandError,
    } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
  } catch (err) {
    return {
      name: spec,
      ...(packageProviderId == null ? {} : {providerId: packageProviderId}),
      version: pkg.version,
      __spec: spec,
      __packageDir: packageDir,
      __manifestFile: manifestFile,
      __loadError: err instanceof Error ? err.message : String(err),
      __local: true,
    };
  }

  const providerId = providerIdForPackage(manifest.providerId ?? pkg.name);

  /** @param {string | null | undefined} value */
  const resolveRoot = value => {
    if (value == null) return undefined;
    try {
      return assertWithin(value, packageDir, {label: 'contribution root'});
    } catch {
      return undefined;
    }
  };

  return {
    name: spec,
    ...(providerId == null ? {} : {providerId}),
    version: pkg.version,
    components: resolveRoot(manifest.components),
    templates: resolveRoot(manifest.templates),
    codemods: resolveRoot(manifest.codemods),
    docs: resolveRoot(manifest.docs),
    themes: resolveRoot(manifest.themes),
    iconSets: resolveRoot(manifest.experimental?.iconSets),
    issuesUrl: manifest.issuesUrl,
    agentDocs: manifest.agentDocs,
    cliCommand: manifest.cliCommand,
    __cliCommandError: cliCommandError,
    __agentDocsError: agentDocsError,
    __unknownKeys: unknownKeys,
    __declaredKeys: declaredKeys,
    __debug: debugHandler,
    __gapReport: gapReportHandler,
    __gapReportError: gapReportError,
    __discover: discoverSource,
    __discoverError: discoverError,
    __spec: spec,
    __packageDir: packageDir,
    __packageExports: pkg.exports ?? null,
    __manifestFile: manifestFile,
    __local: true,
  };
}

/**
 * Load configured integrations.
 *
 * @param {string[]} [specs] package names
 * @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, resolveProviders = true} = {},
) {
  /** @type {LoadedIntegration[]} */
  const integrations = [];
  const seenSpecs = new Set();

  for (const spec of specs) {
    if (!spec || seenSpecs.has(spec)) continue;
    seenSpecs.add(spec);

    const packageDir = resolveInstalledIntegrationDir(spec, cwd);
    const pkgPath = path.join(packageDir, 'package.json');
    let pkg;
    try {
      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
    } catch {
      throw new Error(
        `Could not find installed integration package "${spec}" at ${pkgPath}. Install it first.`,
      );
    }

    const packageProviderId = providerIdForPackage(pkg.name ?? spec);
    const manifestFile = resolveManifestPath(packageDir, spec);
    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} */
    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;
    /** @type {string | undefined} */
    let cliCommandError;
    try {
      ({
        manifest,
        unknownKeys,
        declaredKeys,
        debug: debugHandler,
        gapReport: gapReportHandler,
        gapReportError,
        discover: discoverSource,
        discoverError,
        agentDocsError,
        cliCommandError,
      } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
    } catch (err) {
      // A manifest that throws on import or fails schema validation must NOT take
      // down every command (component/docs/theme don't need this integration).
      // Record a load-error marker; Project surfaces it via issues() and the
      // 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,
        __manifestFile: manifestFile,
        __loadError: err instanceof Error ? err.message : String(err),
      });
      continue;
    }

    const providerId = providerIdForPackage(
      manifest.providerId ?? pkg.name ?? spec,
    );

    /** @param {string | null | undefined} value */
    const resolveRoot = value => {
      if (value == null) return undefined;
      try {
        return assertWithin(value, packageDir, {label: 'contribution root'});
      } catch {
        // Root escapes the package — skip silently (reported by Doctor validation).
        return undefined;
      }
    };

    integrations.push({
      name: pkg.name ?? spec,
      ...(providerId == null ? {} : {providerId}),
      version: pkg.version,
      components: resolveRoot(manifest.components),
      templates: resolveRoot(manifest.templates),
      codemods: resolveRoot(manifest.codemods),
      docs: resolveRoot(manifest.docs),
      themes: resolveRoot(manifest.themes),
      iconSets: resolveRoot(manifest.experimental?.iconSets),
      issuesUrl: manifest.issuesUrl,
      agentDocs: manifest.agentDocs,
      cliCommand: manifest.cliCommand,
      __cliCommandError: cliCommandError,
      __agentDocsError: agentDocsError,
      __unknownKeys: unknownKeys,
      __declaredKeys: declaredKeys,
      __debug: debugHandler,
      __gapReport: gapReportHandler,
      __gapReportError: gapReportError,
      __discover: discoverSource,
      __discoverError: discoverError,
      __spec: spec,
      __packageDir: packageDir,
      __packageExports: pkg.exports ?? null,
      __manifestFile: manifestFile,
    });
  }

  return resolveProviders ? markProviderConflicts(integrations) : integrations;
}