@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/self-update/plan.ts

@@ -1,315 +0,0 @@
-/**
- * The plan an update carries out: for each install, the version it moves to
- * and the exact command that moves it, plus a notice for every copy sous
- * found and cannot act on.
- *
- * Planning has no side effects. What `buildUpdatePlans` returns is exactly
- * what a dry run prints and what a real run executes, one confirmation per
- * plan (sous-io/sous#135).
- */
-
-import { PACKAGE_NAME } from "../project-install.mjs";
-import type { GlobalInstallInfo, InstallDiscovery, ProjectInstallInfo } from "./installs.js";
-import {
-  globalInstall,
-  manualProjectAdd,
-  packageSpec,
-  projectAdd,
-  type DependencySection,
-} from "./managers.js";
-import semver from "semver";
-import {
-  chooseVersion,
-  type RegistryMetadata,
-  type VersionDirection,
-  type VersionRequest,
-} from "./versions.js";
-
-/** Which install a plan or a notice is about. */
-export type UpdateScope = "global" | "project";
-
-/** A command to run, where to run it, and nothing run yet. */
-export type PlannedCommand = {
-  command: string;
-  args: string[];
-  /** The directory to run it in; undefined for a global install, which runs anywhere. */
-  cwd?: string;
-};
-
-/** One install, and what an update does to it. */
-export type UpdatePlan = {
-  scope: UpdateScope;
-  /** The copy's path: the global package directory, or the project's `node_modules` copy. */
-  location: string;
-  /** The project root; set only for a project plan. */
-  projectRoot?: string;
-  /**
-   * Set only for a project that uses Yarn Plug'n'Play: the directory holding
-   * its `.pnp.cjs`. `location` is then that file, and the build runs through Yarn.
-   */
-  pnpRoot?: string;
-  /** The package manager that runs `command` (`npm`, `pnpm`, `yarn`, `yarn@berry`). */
-  manager: string;
-  /**
-   * True when the project's files named no manager and npm is assumed; the
-   * plan should say so. Always false for a global plan.
-   */
-  managerAssumed: boolean;
-  /** The version installed now. */
-  installed: string;
-  /** The version the update installs; equal to `installed` when `direction` is `current`. */
-  target: string;
-  /** `current` means there is nothing to do: report it and ask nothing. */
-  direction: VersionDirection;
-  /** How the project's package.json declares sous; set only for a project plan. */
-  declaredIn?: { section: DependencySection; range: string };
-  /** What installs `target`. Present for a `current` plan too, and not to be run then. */
-  command: PlannedCommand;
-};
-
-/**
- * Why a copy was found and not planned.
- *
- * - `npx`: the running copy is in npx's cache, which no install updates.
- * - `volta`: the running copy is managed by Volta; `manualCommand` is Volta's.
- * - `unknown-location`: the running copy is none of the installs (a source checkout, say).
- * - `undeclared`: the project has the package in `node_modules` but its package.json does not name it.
- * - `unsupported-manager`: the project's manager is one sous does not drive;
- *   `manualCommand` is that manager's own, when known.
- * - `unknown-version`: the copy's package.json names no version sous can compare.
- * - `not-found`: the run was narrowed to a scope that has no install.
- */
-export type UpdateNoticeKind =
-  | "npx"
-  | "volta"
-  | "unknown-location"
-  | "undeclared"
-  | "unsupported-manager"
-  | "unknown-version"
-  | "not-found";
-
-/** A copy sous will not act on, with the facts and one plain sentence saying why. */
-export type UpdateNotice = {
-  kind: UpdateNoticeKind;
-  /** The install the notice is about; undefined for one about the running copy as a whole (npx). */
-  scope?: UpdateScope;
-  /** The copy's path, when the notice is about one copy. */
-  location?: string;
-  /** A complete sentence saying what was found and why nothing is done to it. */
-  message: string;
-  /** The command a person would run by hand, when there is one; run in `cwd` when set. */
-  manualCommand?: PlannedCommand;
-};
-
-/** Every plan and every notice. */
-export type UpdatePlanSet = {
-  /** Global plans first, then the project plan. */
-  plans: UpdatePlan[];
-  notices: UpdateNotice[];
-};
-
-/** Options for `buildUpdatePlans`. */
-export type BuildUpdatePlansOptions = {
-  request: VersionRequest;
-  /** Whether prereleases count; undefined means "on when the installed version is a prerelease", per install. */
-  prerelease?: boolean;
-  /** Plan only this scope (`--global` or `--project`); undefined plans both. */
-  only?: UpdateScope;
-};
-
-/**
- * Works out every plan and every notice, one install at a time, each judged on
- * its own installed version.
- *
- * @throws ConfigError when a `spec` request matches nothing for an install
- *   (from `chooseVersion`).
- */
-export function buildUpdatePlans(
-  discovery: InstallDiscovery,
-  metadata: RegistryMetadata,
-  options: BuildUpdatePlansOptions
-): UpdatePlanSet {
-  const plans: UpdatePlan[] = [];
-  const notices: UpdateNotice[] = [];
-  const wants = (scope: UpdateScope): boolean => options.only === undefined || options.only === scope;
-
-  if (wants("global")) {
-    for (const install of discovery.globals) {
-      const planned = planGlobal(install, metadata, options);
-      if ("kind" in planned) notices.push(planned);
-      else plans.push(planned);
-    }
-  }
-  if (wants("project") && discovery.project !== undefined) {
-    const planned = planProject(discovery.project, metadata, options);
-    if ("kind" in planned) notices.push(planned);
-    else plans.push(planned);
-  }
-
-  notices.push(...runningNotices(discovery, metadata, options));
-
-  if (options.only === "global" && discovery.globals.length === 0) {
-    notices.push({
-      kind: "not-found",
-      scope: "global",
-      message: `No global install of ${PACKAGE_NAME} was found with npm, pnpm or Yarn.`,
-    });
-  }
-  if (options.only === "project" && discovery.project === undefined) {
-    notices.push({
-      kind: "not-found",
-      scope: "project",
-      message: `No project install of ${PACKAGE_NAME} was found in this directory or above it.`,
-    });
-  }
-  return { plans, notices };
-}
-
-/** The plan for one global install, or the notice saying why there is none. */
-function planGlobal(
-  install: GlobalInstallInfo,
-  metadata: RegistryMetadata,
-  options: BuildUpdatePlansOptions
-): UpdatePlan | UpdateNotice {
-  if (semver.valid(install.installed) === null) {
-    return unknownVersion("global", install.location, install.installed);
-  }
-  const choice = choose(install.installed, metadata, options);
-  return {
-    scope: "global",
-    location: install.location,
-    manager: install.manager,
-    managerAssumed: false,
-    installed: install.installed,
-    target: choice.target,
-    direction: choice.direction,
-    command: globalInstall(install.manager, choice.target),
-  };
-}
-
-/** The plan for the project install, or the notice saying why there is none. */
-function planProject(
-  install: ProjectInstallInfo,
-  metadata: RegistryMetadata,
-  options: BuildUpdatePlansOptions
-): UpdatePlan | UpdateNotice {
-  if (install.declared === undefined) {
-    return {
-      kind: "undeclared",
-      scope: "project",
-      location: install.location,
-      message:
-        `The project at ${install.projectRoot} has ${PACKAGE_NAME} in node_modules, ` +
-        "but its package.json does not declare it, so sous leaves it alone.",
-    };
-  }
-  if (semver.valid(install.installed) === null) {
-    return unknownVersion("project", install.location, install.installed);
-  }
-  const choice = choose(install.installed, metadata, options);
-  if (!install.manager.supported) {
-    const notice: UpdateNotice = {
-      kind: "unsupported-manager",
-      scope: "project",
-      location: install.location,
-      message:
-        `The project at ${install.projectRoot} uses ${install.manager.agent}, ` +
-        "which sous does not drive, so it has to be updated by hand.",
-    };
-    const manual = manualProjectAdd(install.manager.agent, choice.target, install.declared.section);
-    if (manual !== undefined) notice.manualCommand = { ...manual, cwd: install.projectRoot };
-    return notice;
-  }
-  const command = projectAdd(install.manager.agent, choice.target, {
-    section: install.declared.section,
-    workspaceRoot: install.workspaceRoot,
-  });
-  const plan: UpdatePlan = {
-    scope: "project",
-    location: install.location,
-    projectRoot: install.projectRoot,
-    manager: install.manager.agent,
-    managerAssumed: !install.manager.detected,
-    installed: install.installed,
-    target: choice.target,
-    direction: choice.direction,
-    declaredIn: install.declared,
-    command: { ...command, cwd: install.projectRoot },
-  };
-  if (install.pnpRoot !== undefined) plan.pnpRoot = install.pnpRoot;
-  return plan;
-}
-
-/**
- * The notices about the running copy when it is none of the installs planned:
- * npx (always), and Volta or an unknown location (global scope). Volta's
- * command names the version the same request chooses for the running copy.
- */
-function runningNotices(
-  discovery: InstallDiscovery,
-  metadata: RegistryMetadata,
-  options: BuildUpdatePlansOptions
-): UpdateNotice[] {
-  const { running } = discovery;
-  if (running.kind === "npx") {
-    return [
-      {
-        kind: "npx",
-        location: running.realPath,
-        message:
-          "This sous is running through npx, which is not an install: " +
-          "npx keeps its own cache, and no install sous updates changes it.",
-      },
-    ];
-  }
-  if (options.only === "project") return [];
-  if (running.kind === "volta") {
-    const notice: UpdateNotice = {
-      kind: "volta",
-      scope: "global",
-      location: running.realPath,
-      message: "This sous is managed by Volta, which sous does not drive, so Volta has to update it.",
-    };
-    if (semver.valid(running.installed) !== null) {
-      const { target } = choose(running.installed, metadata, options);
-      notice.manualCommand = { command: "volta", args: ["install", packageSpec(target)] };
-    }
-    return [notice];
-  }
-  if (running.kind === "unknown") {
-    return [
-      {
-        kind: "unknown-location",
-        scope: "global",
-        location: running.realPath,
-        message:
-          "This sous is not the project install or a global install of npm, pnpm or Yarn " +
-          "(it may be a source checkout), so sous does not update it.",
-      },
-    ];
-  }
-  return [];
-}
-
-/** Chooses a version for one install. */
-function choose(installed: string, metadata: RegistryMetadata, options: BuildUpdatePlansOptions) {
-  return chooseVersion({
-    current: installed,
-    versions: metadata.versions,
-    distTags: metadata.distTags,
-    request: options.request,
-    ...(options.prerelease === undefined ? {} : { prerelease: options.prerelease }),
-  });
-}
-
-/** The notice for a copy whose version cannot be compared. */
-function unknownVersion(scope: UpdateScope, location: string, installed: string): UpdateNotice {
-  return {
-    kind: "unknown-version",
-    scope,
-    location,
-    message:
-      `The ${scope} install at ${location} names its version as "${installed}", ` +
-      "which sous cannot compare with the published versions, so it has to be updated by hand.",
-  };
-}

package/src/lib/self-update/registry.ts

@@ -1,99 +0,0 @@
-/**
- * Asks the npm registry which versions of sous are published.
- *
- * One request: a GET of the package's abbreviated document, the same small
- * answer an install reads. Finding out what is published is the point of an
- * update, so a registry that cannot be reached is an error, never a warning.
- * The fetch is injectable, so no test reaches the network.
- */
-
-import { PACKAGE_NAME } from "../project-install.mjs";
-import { fetchText, type FetchLike } from "../repos/providers/http.js";
-import { parseRegistryMetadata, type RegistryMetadata } from "./versions.js";
-
-/** The registry sous asks when the environment names no other. */
-export const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
-
-/** The media type of the abbreviated package document. */
-export const ABBREVIATED_METADATA_TYPE = "application/vnd.npm.install-v1+json";
-
-/** How long the registry has to answer before the request is abandoned. */
-export const REGISTRY_TIMEOUT_MS = 15_000;
-
-/** The environment variables that name another registry, in the order they are read. */
-export const REGISTRY_ENV_NAMES = ["npm_config_registry", "NPM_CONFIG_REGISTRY"] as const;
-
-/**
- * The registry base URL, always ending in `/`: the first non-blank value of
- * `REGISTRY_ENV_NAMES`, or `DEFAULT_REGISTRY`. npm sets `npm_config_registry`
- * for the scripts it runs, so a project's `.npmrc` registry reaches sous that
- * way too.
- *
- * registryBaseUrl({ npm_config_registry: "https://npm.example.com" })
- * // -> "https://npm.example.com/"
- */
-export function registryBaseUrl(env: Readonly<Record<string, string | undefined>>): string {
-  for (const name of REGISTRY_ENV_NAMES) {
-    const value = env[name]?.trim();
-    if (value !== undefined && value.length > 0) {
-      return value.endsWith("/") ? value : `${value}/`;
-    }
-  }
-  return DEFAULT_REGISTRY;
-}
-
-/**
- * The URL of the package's document on a registry. The scope's slash is
- * encoded, which every registry accepts.
- *
- * packageMetadataUrl("https://registry.npmjs.org/")
- * // -> "https://registry.npmjs.org/@sous-io%2fsous"
- */
-export function packageMetadataUrl(base: string): string {
-  return `${base}${PACKAGE_NAME.replace("/", "%2f")}`;
-}
-
-/** Options for `fetchPublishedVersions`. */
-export type FetchPublishedVersionsOptions = {
-  /** Where the registry override is read from. Defaults to `process.env`. */
-  env?: Readonly<Record<string, string | undefined>>;
-  /** The fetch implementation. Defaults to the global `fetch`. */
-  fetchImpl?: FetchLike;
-  /** How long to wait for an answer. Defaults to `REGISTRY_TIMEOUT_MS`. */
-  timeoutMs?: number;
-};
-
-/**
- * Fetches and reads what the registry publishes for `@sous-io/sous`.
- *
- * @throws ConfigError naming the URL and quoting the reason when the registry
- *   cannot be reached, answers with an error status, runs past the timeout, or
- *   sends something that is not a package document.
- */
-export async function fetchPublishedVersions(
-  options: FetchPublishedVersionsOptions = {}
-): Promise<RegistryMetadata> {
-  const url = packageMetadataUrl(registryBaseUrl(options.env ?? process.env));
-  const fetched = await fetchText(url, {
-    label: `list of published ${PACKAGE_NAME} versions`,
-    accept: ABBREVIATED_METADATA_TYPE,
-    signal: AbortSignal.timeout(options.timeoutMs ?? REGISTRY_TIMEOUT_MS),
-    statusHints: registryStatusHints,
-    ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
-  });
-  return parseRegistryMetadata(fetched.text, url);
-}
-
-/** What a failed status usually means when the URL is the package's document. */
-function registryStatusHints(status: number): string[] {
-  if (status === 404) {
-    return [
-      `  The registry has no package named ${PACKAGE_NAME}. When npm_config_registry ` +
-        "names a mirror, the mirror may not carry it.",
-    ];
-  }
-  if (status === 401 || status === 403) {
-    return ["  The registry refused the request without credentials, and sous sends none."];
-  }
-  return [];
-}