Skip to content

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

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

/**
 * @file upgrade API — dispatcher + barrel over the upgrade leaves.
 *
 * `upgrade(options)` runs codemods that migrate source from a previous Astryx
 * version to the currently installed one, refreshes the managed agent-docs
 * block, and reconciles ShadCN-copied compositions. It is the single entry the
 * CLI calls; it validates the invocation and routes to one leaf, each of which
 * returns its `{type, data}` envelope:
 *   - `list`     (api/upgrade/list)     → upgrade.list — codemods, no run
 *   - `registry` (api/upgrade/registry) → upgrade.registry — copied source only
 *   - `run`      (api/upgrade/run)      → upgrade.run — the terminal run receipt,
 *       plus the up_to_date / no_codemods / config_fixable short-circuits it
 *       delegates to the `status` leaf → upgrade.status
 *
 * Shared version-detection + codemod selection/execution I/O lives in
 * `_adapter.mjs` (the leaves project its results). Errors throw AstryxError
 * (stable code). Human progress is emitted through the shared `logger`
 * (silent by default), so the CLI keeps its exact output and a programmatic
 * caller stays quiet.
 */

import {list} from './list/list.mjs';
import {registryUpgrade} from './registry/registry.mjs';
import {run} from './run/run.mjs';
import {relativeToOrigin, scopeToProject} from './_adapter.mjs';
import {isValidSemver} from '../../foundation/env/semver.mjs';
import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {AstryxError} from '../error.mjs';
import {logger} from '../logger.mjs';

/**
 * @typedef {import('./upgrade.type.mjs').UpgradeOptions} UpgradeOptions
 */

/**
 * Run the upgrade pipeline. Validates the invocation, then dispatches to the
 * list/status/run leaves. Returns the leaf's receipt; throws AstryxError on
 * failure. Progress is emitted through the shared `logger` (silent by default).
 *
 * @param {UpgradeOptions} [options]
 * @param {{cwd?: string}} [ctx]
 * @returns {Promise<import('./upgrade.type.mjs').UpgradeListResponse | import('./upgrade.type.mjs').UpgradeRegistryResponse | import('./upgrade.type.mjs').UpgradeStatusResponse | import('./upgrade.type.mjs').UpgradeRunResponse>}
 */
export async function upgrade(options = {}, {cwd = process.cwd()} = {}) {
  logger.log('\nUpgrade');

  if (options.list && options.registry) {
    const msg = '`--list` and `--registry` cannot be used together.';
    logger.error(msg);
    logger.log('Aborted\n');
    throw new AstryxError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
  }

  if (options.list) {
    const ignored = [
      options.from ? '--from' : null,
      options.force ? '--force' : null,
      options.apply ? '--apply' : null,
      options.path && options.path !== './src' ? '--path' : null,
      options.codemod ? '--codemod' : null,
      options.skipCodemod?.length ? '--skip-codemod' : null,
      options.integration?.length ? '--integration' : null,
      options.installDeps ? '--install-deps' : null,
    ].filter(Boolean);
    if (ignored.length > 0) {
      const msg = `\`--list\` cannot be combined with ${ignored.join(', ')}: it lists available codemods and does not run a migration.`;
      logger.error(msg);
      logger.log('Aborted\n');
      throw new AstryxError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
    }
  }

  if (options.registry) {
    const incompatible = [
      options.from ? '--from' : null,
      options.force ? '--force' : null,
      options.codemod ? '--codemod' : null,
      options.skipCodemod?.length ? '--skip-codemod' : null,
      options.integration?.length ? '--integration' : null,
      options.installDeps ? '--install-deps' : null,
    ].filter(Boolean);
    if (incompatible.length > 0) {
      const msg = `\`--registry\` cannot be combined with ${incompatible.join(', ')}.`;
      logger.error(msg);
      logger.log('Aborted\n');
      throw new AstryxError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
    }
    const scoped = scopeToProject(options, cwd);
    return registryUpgrade(scoped.options, {
      cwd: scoped.cwd,
      origin: scoped.origin,
    });
  }

  if (!options.list && !options.from) {
    // Outside a project there is no version to install (spec AST-081 FR3).
    const msg = isOutsideProject(cwd)
      ? 'Missing required --from. This folder is outside a project; upgrade migrates the code of an app project that installs @astryxdesign/core.'
      : `Missing required --from. Install the target version first, then run \`${getCliInvocation()} upgrade --from <old-version>\`.`;
    logger.error(msg);
    logger.log('Aborted\n');
    throw new AstryxError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
  }

  if (!options.list && !isValidSemver(options.from)) {
    const msg = `Invalid --from value: "${options.from}". Expected a semver string like 0.0.5.`;
    logger.error(msg);
    logger.log('Aborted\n');
    throw new AstryxError(msg, undefined, ERROR_CODES.ERR_INVALID_VERSION);
  }

  if (options.list) {
    return list();
  }

  // A run from a subfolder upgrades the project the folder belongs to, and
  // names files relative to the folder it ran in.
  const scoped = scopeToProject(options, cwd);
  let result;
  try {
    result = await run(scoped.options, {
      cwd: scoped.cwd,
      origin: scoped.origin,
    });
  } catch (err) {
    // A failure after codemods wrote carries their receipt; name its files
    // from the folder the command ran in, as a returned receipt does.
    const receipt = /** @type {any} */ (err)?.receipt;
    if (err instanceof AstryxError && receipt) {
      /** @type {any} */ (err).receipt = relativeToOrigin(
        {type: 'upgrade.run', data: receipt},
        scoped,
      ).data;
    }
    throw err;
  }
  return relativeToOrigin(result, scoped);
}