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

package/foundation/runtime/package-root.mjs

@@ -0,0 +1,174 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The active hosted run (architecture:cli-surface INV30, spec AST-081
+ * FR1): the package sets, approved integrations, and discover sources a host
+ * passed through `@astryxdesign/cli/host`, the root that holds the copy that
+ * started the run, and the packages the run resolved.
+ *
+ * Only the host entry activates a hosted run, once per process. With none
+ * active, every lookup that consults it behaves as it does without a host.
+ *
+ * @input What the host entry passes to `activateHostedRun`.
+ * @output `hostedRun()` for the lookups that consult it; the resolved-package
+ *   record the host entry returns.
+ * @position foundation/runtime — read by the release choice, Core lookups,
+ *   computer-level integrations, and discover; written by host/index.mjs.
+ */
+
+import * as fs from 'node:fs';
+import {relativeWithin, samePath} from '../fs/path-compare.mjs';
+
+/**
+ * @typedef {object} HostedRun
+ * @property {readonly string[]} roots the host's package sets, in its order
+ * @property {readonly string[]} integrations the integrations it approves for
+ *   use outside a project
+ * @property {readonly Function[]} discoverSources its own discover sources
+ * @property {string | null} startingRoot the root that holds the copy that
+ *   started the run
+ * @property {string | null} projectRoot the project the run works in, if any
+ * @property {((hostEntry: string) => Promise<(options: object) => Promise<{status: number, packages: Array<{name: string, version: string | null, source: 'project' | 'package-set'}>}>>) | null} loadHostEntry
+ *   loads another release's host entry, from one of the package sets, to hand
+ *   this run over to in this process
+ */
+
+/** @type {HostedRun | null} */
+let active = null;
+
+/** @type {Map<string, {name: string, version: string | null, dir: string | null, source: 'project' | 'package-set' | undefined}>} */
+const resolved = new Map();
+
+/**
+ * @param {string} p
+ * @returns {string}
+ */
+function real(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Start the hosted run of this process.
+ * @param {{roots?: readonly string[], integrations?: readonly string[], discoverSources?: readonly Function[], startingRoot?: string | null, projectRoot?: string | null, loadHostEntry?: HostedRun['loadHostEntry']}} inputs
+ * @returns {HostedRun}
+ */
+export function activateHostedRun({
+  roots = [],
+  integrations = [],
+  discoverSources = [],
+  startingRoot = null,
+  projectRoot = null,
+  loadHostEntry = null,
+}) {
+  if (active)
+    throw new Error('A hosted run is already active in this process.');
+  active = Object.freeze({
+    roots: Object.freeze([...roots]),
+    integrations: Object.freeze([...integrations]),
+    discoverSources: Object.freeze([...discoverSources]),
+    startingRoot,
+    projectRoot,
+    loadHostEntry,
+  });
+  return active;
+}
+
+/**
+ * The hosted run of this process, or null when no host started it.
+ * @returns {HostedRun | null}
+ */
+export function hostedRun() {
+  return active;
+}
+
+/**
+ * Note one package the run resolved. The first record of a name stands. Does
+ * nothing outside a hosted run.
+ * @param {string} name
+ * @param {unknown} version
+ * @param {string | null | undefined} dir
+ * @param {'project' | 'package-set'} [source] where it came from, when the
+ *   caller knows; otherwise the folder that holds `dir` says
+ */
+export function recordResolved(name, version, dir, source) {
+  if (!active || typeof name !== 'string' || resolved.has(name)) return;
+  resolved.set(name, {
+    name,
+    version: typeof version === 'string' ? version : null,
+    dir: dir ?? null,
+    source,
+  });
+}
+
+/**
+ * Note every integration a project load resolved: one installed for the
+ * computer, an approved one included, comes from a package set; any other,
+ * from the project.
+ * @param {ReadonlyArray<{name: string, version?: string, __packageDir?: string, __computer?: boolean}>} integrations
+ */
+export function recordResolvedIntegrations(integrations) {
+  if (!active) return;
+  for (const integration of integrations) {
+    recordResolved(
+      integration.name,
+      integration.version,
+      integration.__packageDir,
+      integration.__computer ? 'package-set' : 'project',
+    );
+  }
+}
+
+/**
+ * Where a package in `dir` came from: the deepest of the project and the
+ * package sets (the root that holds the starting copy, and the roots the host
+ * passed) that holds it. A root that is the project itself, as when the
+ * host's CLI is installed in the project, counts as the project.
+ * @param {string | null} dir
+ * @returns {'project' | 'package-set'}
+ */
+function sourceOf(dir) {
+  if (!active || !dir) return 'project';
+  const target = real(dir);
+  /** @type {Array<{base: string, source: 'project' | 'package-set'}>} */
+  const holders = [];
+  if (active.projectRoot) {
+    holders.push({base: real(active.projectRoot), source: 'project'});
+  }
+  for (const root of [active.startingRoot, ...active.roots]) {
+    if (root) holders.push({base: real(root), source: 'package-set'});
+  }
+  /** @type {{base: string, source: 'project' | 'package-set'} | null} */
+  let best = null;
+  for (const holder of holders) {
+    const holds =
+      samePath(holder.base, target) ||
+      relativeWithin(holder.base, target) != null;
+    // The project comes first, so it keeps a tie with a root that is itself.
+    if (holds && (!best || holder.base.length > best.base.length))
+      best = holder;
+  }
+  return best ? best.source : 'project';
+}
+
+/**
+ * Each package the run resolved: its name, version, and whether it came from
+ * the project or a package set (INV30).
+ * @returns {Array<{name: string, version: string | null, source: 'project' | 'package-set'}>}
+ */
+export function resolvedPackages() {
+  return [...resolved.values()].map(({name, version, dir, source}) => ({
+    name,
+    version,
+    source: source ?? sourceOf(dir),
+  }));
+}
+
+/** Forget the hosted run. Tests only. */
+export function _resetHostedRun() {
+  active = null;
+  resolved.clear();
+}

package/foundation/runtime/package-set.d.mts

@@ -0,0 +1,62 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * A root's own copy of `name`, read from its `node_modules` only: a root never
+ * reaches past itself.
+ * @param {string} root
+ * @param {string} name
+ * @returns {{dir: string, version: string | null} | null}
+ */
+export function rootPackage(root: string, name: string): {
+    dir: string;
+    version: string | null;
+} | null;
+/**
+ * Whether `version` is one the project's install could bring in for `range`:
+ * a plain version range only, and a prerelease only when the range names a
+ * prerelease of the same version.
+ * @param {string | null} version
+ * @param {string} range
+ * @returns {boolean}
+ */
+export function satisfiesInstall(version: string | null, range: string): boolean;
+/**
+ * @typedef {object} ServingRoot
+ * @property {string} root
+ * @property {string} cliDir the root's CLI package
+ * @property {string | null} bin the root's `astryx` bin
+ * @property {string | null} hostEntry the root's `host/index.mjs`, when its
+ *   CLI ships one
+ */
+/**
+ * The first of `roots` that may serve a run in `projectDir` that CLI
+ * `release` answers.
+ * @param {{release: string, projectDir: string | null, roots: readonly string[], needsHostEntry?: boolean}} input
+ *   `needsHostEntry` keeps out a root whose CLI has no host entry
+ * @returns {ServingRoot | {reason: string}}
+ */
+export function qualifyingRoot({ release, projectDir, roots, needsHostEntry, }: {
+    release: string;
+    projectDir: string | null;
+    roots: readonly string[];
+    needsHostEntry?: boolean;
+}): ServingRoot | {
+    reason: string;
+};
+export type ServingRoot = {
+    root: string;
+    /**
+     * the root's CLI package
+     */
+    cliDir: string;
+    /**
+     * the root's `astryx` bin
+     */
+    bin: string | null;
+    /**
+     * the root's `host/index.mjs`, when its
+     * CLI ships one
+     */
+    hostEntry: string | null;
+};

package/foundation/runtime/package-set.mjs

@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Matching a project to a host's package sets (architecture:cli-surface
+ * INV30). A package set is a root whose `node_modules` holds a CLI, the Core
+ * equal to it, and the integrations installed with them; a run resolves from at
+ * most one root, and a hosted run installs nothing.
+ *
+ * Inside a project a root fills only the `@astryxdesign/*` packages the
+ * project leaves uninstalled whose copy in the root ships no integration
+ * manifest. For a run that a release other than the starting copy answers, the
+ * first root in the host's order qualifies when its CLI and Core are that
+ * release and it holds, for each package it may fill, the version the project
+ * would install: the lockfile's, else a published version in the declared
+ * range.
+ *
+ * @input A release, the project folder, and the host's roots.
+ * @output The root that serves the run, or why none can.
+ * @position foundation/runtime — read by the release choice (handoff.mjs) in a
+ *   hosted run.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {findManifestPaths} from '../integrations/integrations.mjs';
+import {readJson} from '../release/project.mjs';
+import {cliBinOf, isVersionRange} from '../release/cache.mjs';
+import {isValidSemver, satisfiesRange} from '../env/semver.mjs';
+import {projectAstryxPins} from './locked-versions.mjs';
+
+const CLI = '@astryxdesign/cli';
+const CORE = '@astryxdesign/core';
+
+/**
+ * A root's own copy of `name`, read from its `node_modules` only: a root never
+ * reaches past itself.
+ * @param {string} root
+ * @param {string} name
+ * @returns {{dir: string, version: string | null} | null}
+ */
+export function rootPackage(root, name) {
+  const dir = path.join(root, 'node_modules', ...name.split('/'));
+  const pkg = readJson(path.join(dir, 'package.json'));
+  if (!pkg || typeof pkg !== 'object' || pkg.name !== name) return null;
+  return {dir, version: typeof pkg.version === 'string' ? pkg.version : null};
+}
+
+/**
+ * Whether `version` is one the project's install could bring in for `range`:
+ * a plain version range only, and a prerelease only when the range names a
+ * prerelease of the same version.
+ * @param {string | null} version
+ * @param {string} range
+ * @returns {boolean}
+ */
+export function satisfiesInstall(version, range) {
+  if (!version || !isValidSemver(version) || !isVersionRange(range)) {
+    return false;
+  }
+  const dash = version.indexOf('-');
+  if (dash !== -1 && !range.includes(`${version.slice(0, dash)}-`)) {
+    return false;
+  }
+  return satisfiesRange(version, range);
+}
+
+/**
+ * Whether `root` holds what the project would install for one pin it leaves
+ * uninstalled. A package the root holds as an integration, or does not hold at
+ * all, is one the root never fills, so it never keeps the root out.
+ * @param {string} root
+ * @param {import('./locked-versions.mjs').AstryxPin} pin
+ * @returns {boolean}
+ */
+function holds(root, pin) {
+  if (pin.name === CLI) return true;
+  const copy = rootPackage(root, pin.name);
+  if (!copy) return pin.name !== CORE;
+  if (findManifestPaths(copy.dir).length > 0) return true;
+  if (pin.locked) return copy.version === pin.locked;
+  return satisfiesInstall(copy.version, pin.declared);
+}
+
+/**
+ * @typedef {object} ServingRoot
+ * @property {string} root
+ * @property {string} cliDir the root's CLI package
+ * @property {string | null} bin the root's `astryx` bin
+ * @property {string | null} hostEntry the root's `host/index.mjs`, when its
+ *   CLI ships one
+ */
+
+/**
+ * The first of `roots` that may serve a run in `projectDir` that CLI
+ * `release` answers.
+ * @param {{release: string, projectDir: string | null, roots: readonly string[], needsHostEntry?: boolean}} input
+ *   `needsHostEntry` keeps out a root whose CLI has no host entry
+ * @returns {ServingRoot | {reason: string}}
+ */
+export function qualifyingRoot({
+  release,
+  projectDir,
+  roots,
+  needsHostEntry = false,
+}) {
+  const open = projectDir
+    ? projectAstryxPins(projectDir).filter(pin => pin.installed === null)
+    : [];
+  for (const root of roots) {
+    const cli = rootPackage(root, CLI);
+    if (!cli || cli.version !== release) continue;
+    const core = rootPackage(root, CORE);
+    if (!core || core.version !== release) continue;
+    const hostEntry = path.join(cli.dir, 'host', 'index.mjs');
+    const hasHostEntry = fs.existsSync(hostEntry);
+    if (needsHostEntry && !hasHostEntry) continue;
+    const bin = cliBinOf(cli.dir);
+    if (!bin && !hasHostEntry) continue;
+    if (!open.every(pin => holds(root, pin))) continue;
+    return {
+      root,
+      cliDir: cli.dir,
+      bin,
+      hostEntry: hasHostEntry ? hostEntry : null,
+    };
+  }
+  return {
+    reason: `no package set the host passed holds CLI ${release} with this project's packages`,
+  };
+}