Skip to content

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

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

/**
 * @file The command that runs the CLI for this project, when something other
 * than the package-manager guess says what it is.
 *
 * `getCliInvocation` (package-manager.mjs) is the one picker every printed
 * command goes through. It asks, in order:
 *
 * 1. **The integrations** — the `cliCommand` field of each loaded
 *    integration's manifest. `Project.load` records them per project with
 *    {@link recordDeclaredCliCommands}. One command, declared by one or more
 *    integrations, is used. Two different commands cancel each other out: the
 *    picker falls back to its guess, even when a host set a door, and
 *    `astryx doctor` warns.
 * 2. **The door** — the command a host ran this call through. A host sets it
 *    for the duration of one call with {@link runWithCliDoor}; nothing in the
 *    public API sets it yet, so it is empty in every plain run.
 * 3. **The guess** — the package-manager prefix, as before.
 *
 * @input A host's door name; the loaded integrations of a project.
 * @output The declared command for a directory, or the conflict.
 * @position foundation/env — read by the picker and by `astryx doctor`.
 */

import {AsyncLocalStorage} from 'node:async_hooks';
import * as fs from 'node:fs';
import * as path from 'node:path';

/**
 * One integration's declared command.
 * @typedef {object} DeclaredCliCommand
 * @property {string} package the integration package that declared it
 * @property {string} command its `cliCommand` value
 */

/** @type {AsyncLocalStorage<{command: string}>} */
const doorScope = new AsyncLocalStorage();

/**
 * Run `fn` with `command` as the door printed commands start with. The slot a
 * host fills for one call. An integration's `cliCommand` still comes first,
 * and conflicting ones still fall back to the guess.
 * @template T
 * @param {string} command e.g. `astryx` for a global launcher
 * @param {() => T} fn
 * @returns {T}
 */
export function runWithCliDoor(command, fn) {
  return doorScope.run({command}, fn);
}

/**
 * The door of the current call, if a host set one.
 * @returns {string | undefined}
 */
export function cliDoor() {
  return doorScope.getStore()?.command;
}

/** @type {Map<string, DeclaredCliCommand[]>} */
const declaredByProject = new Map();

/**
 * The directory a project is keyed by: the nearest one with a package.json,
 * the same root `Project.load` resolves; otherwise the directory itself.
 * @param {string} dir
 * @returns {string}
 */
function projectKey(dir) {
  const start = path.resolve(dir);
  let current = start;
  for (;;) {
    if (fs.existsSync(path.join(current, 'package.json'))) return current;
    const parent = path.dirname(current);
    if (parent === current) return start;
    current = parent;
  }
}

/**
 * The commands a set of loaded integrations declares, in load order. An
 * integration that failed to load, or was set aside for a provider conflict,
 * contributes nothing, so it declares nothing either.
 * @param {ReadonlyArray<{name?: string, __spec?: string, cliCommand?: string, __loadError?: string, __providerConflict?: unknown}>} integrations
 * @returns {DeclaredCliCommand[]}
 */
export function declaredCliCommandsOf(integrations) {
  /** @type {DeclaredCliCommand[]} */
  const declared = [];
  for (const integration of integrations) {
    if (integration.__loadError != null) continue;
    if (integration.__providerConflict != null) continue;
    if (typeof integration.cliCommand !== 'string') continue;
    declared.push({
      package: integration.name ?? integration.__spec ?? '(unnamed)',
      command: integration.cliCommand,
    });
  }
  return declared;
}

/**
 * Choose among declarations: one command, declared by one or more
 * integrations, is used; different commands are a conflict.
 * @param {DeclaredCliCommand[]} declared
 * @returns {{command?: string, conflict: boolean, declared: DeclaredCliCommand[]}}
 */
export function chooseDeclaredCliCommand(declared) {
  const commands = new Set(declared.map(entry => entry.command));
  if (commands.size === 1) {
    return {command: declared[0].command, conflict: false, declared};
  }
  return {conflict: commands.size > 1, declared};
}

/**
 * Record the commands a project's loaded integrations declare. Called by
 * `Project.load` each time it resolves the integration set; the latest load
 * wins.
 * @param {string} projectDir
 * @param {Parameters<typeof declaredCliCommandsOf>[0]} integrations
 * @returns {void}
 */
export function recordDeclaredCliCommands(projectDir, integrations) {
  declaredByProject.set(
    projectKey(projectDir),
    declaredCliCommandsOf(integrations),
  );
}

/**
 * Whether this process has loaded the project at `targetDir`.
 * @param {string} [targetDir=process.cwd()]
 * @returns {boolean}
 */
export function hasRecordedProject(targetDir = process.cwd()) {
  return declaredByProject.has(projectKey(targetDir));
}

/**
 * What the integrations of the project at `targetDir` declare, as recorded by
 * its last `Project.load` in this process; see
 * {@link chooseDeclaredCliCommand}.
 * @param {string} [targetDir=process.cwd()]
 * @returns {{command?: string, conflict: boolean, declared: DeclaredCliCommand[]}}
 */
export function declaredCliCommand(targetDir = process.cwd()) {
  return chooseDeclaredCliCommand(
    declaredByProject.get(projectKey(targetDir)) ?? [],
  );
}