@sous-io/sous 0.2.29 → 0.2.31

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

@@ -31,7 +31,7 @@ export type UpdatePlanFacts = {
   missingRepos: MissingRepo[];
   /** The questions the new versions ask that nothing answers yet. */
   questions: PlannedVariable[];
-  /** Recipes whose files are not on this machine, so their questions are unknown. */
+  /** Recipes whose files are not on this machine and whose index does not record their questions. */
   unreadable: string[];
   /** Repositories whose index could not be fetched, so their pins stay where they are. */
   unreachable: Array<{ repo: string; reason: string }>;
@@ -153,7 +153,8 @@ export function formatUpdatePlan(
   if (facts.unreadable.length > 0) {
     notes.push(
       `A dry run downloads no recipe, so the dependencies of the versions not on this ` +
-        `machine yet are not shown: ${facts.unreadable.join(", ")}.`
+        `machine yet, and not described by their index, are not shown: ` +
+        `${facts.unreadable.join(", ")}.`
     );
   }
   for (const entry of facts.unreachable) {

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

@@ -0,0 +1,14 @@
+/**
+ * The self-update layer: which copies of sous are installed, which version
+ * each should move to, and the package manager command that moves it.
+ *
+ * Import from here rather than from the individual modules. Nothing exported
+ * here installs anything; `run.ts`, imported on its own by `sous update`, is
+ * the flow that runs the commands the plans name.
+ */
+
+export * from "./versions.js";
+export * from "./registry.js";
+export * from "./managers.js";
+export * from "./installs.js";
+export * from "./plan.js";

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

@@ -0,0 +1,412 @@
+/**
+ * Finds every copy of sous an update could move: the project's own install,
+ * each global install, and the copy that is running now.
+ *
+ * Discovery only reads. The package managers are asked through an injectable
+ * command runner (capturing output, never installing anything), and the
+ * project's manager is read from its files by package-manager-detector, so a
+ * test drives every case with a fake runner and a temporary directory.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { detect } from "package-manager-detector/detect";
+import {
+  PACKAGE_NAME,
+  findProjectCopy,
+  readPackageJson,
+  realpathOr,
+} from "../project-install.mjs";
+import { spawnCommand, type CommandRunner } from "../repos/providers/git.js";
+import {
+  GLOBAL_MANAGERS,
+  isProjectManager,
+  type DependencySection,
+  type GlobalManager,
+  type ProjectManager,
+} from "./managers.js";
+
+/** The version reported for a copy whose package.json names none. */
+export const UNKNOWN_VERSION = "unknown";
+
+/** How the project's package.json declares sous. */
+export type DeclaredDependency = {
+  section: DependencySection;
+  /** The range as written, for example `0.2.18` or `^0.2.18`. */
+  range: string;
+};
+
+/**
+ * Which manager owns a project, as far as its files say.
+ *
+ * - `supported: true`: a manager sous drives. `detected` is false when the
+ *   project's files named none and npm is assumed, which the plan says.
+ * - `supported: false`: a manager package-manager-detector recognized that
+ *   sous does not drive (`bun`, `deno`, `pnpm-rush`, ...), named by its agent.
+ */
+export type ProjectManagerInfo =
+  | { supported: true; agent: ProjectManager; detected: boolean }
+  | { supported: false; agent: string };
+
+/** The project's own install of sous. */
+export type ProjectInstallInfo = {
+  /**
+   * The directory holding the project's package.json: the one holding the
+   * `node_modules` the copy is in, or under Yarn Plug'n'Play the nearest one
+   * that declares the package.
+   */
+  projectRoot: string;
+  /**
+   * The copy's path under `node_modules`, as found (not resolved through
+   * links), or under Yarn Plug'n'Play the `.pnp.cjs` file that maps it, since
+   * the package itself stays in Yarn's cache.
+   */
+  location: string;
+  /** The copy's real path, which is what is compared with other copies. */
+  realPath: string;
+  /**
+   * The version in the copy's package.json (under Yarn Plug'n'Play, the one
+   * `yarn.lock` resolves the declared range to), or `UNKNOWN_VERSION`.
+   */
+  installed: string;
+  /** How package.json declares sous; undefined when it is installed but not declared. */
+  declared?: DeclaredDependency;
+  manager: ProjectManagerInfo;
+  /** Whether the project is a workspace root, as its manager reads one. */
+  workspaceRoot: boolean;
+  /**
+   * Set only when the project uses Yarn Plug'n'Play: the directory holding
+   * `.pnp.cjs` and `yarn.lock` (the project root, or its workspace's root).
+   */
+  pnpRoot?: string;
+};
+
+/** One global install of sous, and the manager whose global root holds it. */
+export type GlobalInstallInfo = {
+  manager: GlobalManager;
+  /** The copy's path under the manager's global root, as found. */
+  location: string;
+  /** The copy's real path. */
+  realPath: string;
+  /** The version in the copy's package.json, or `UNKNOWN_VERSION`. */
+  installed: string;
+};
+
+/**
+ * What the running copy is.
+ *
+ * - `project` / `global`: one of the installs found (`global` names its manager).
+ * - `npx`: a copy in npx's cache, which no install updates.
+ * - `volta`: a copy Volta manages, which only Volta updates.
+ * - `unknown`: anywhere else, such as a source checkout.
+ */
+export type RunningInstall = {
+  kind: "project" | "global" | "npx" | "volta" | "unknown";
+  /** The global manager, set only when `kind` is `global`. */
+  manager?: GlobalManager;
+  /** The running copy's real path. */
+  realPath: string;
+  /** The version in the running copy's package.json, or `UNKNOWN_VERSION`. */
+  installed: string;
+};
+
+/** Everything discovery found. */
+export type InstallDiscovery = {
+  /** The project's own install, when the working directory is inside a project that has one. */
+  project?: ProjectInstallInfo;
+  /** Every global install found, one per manager whose global root holds a copy. */
+  globals: GlobalInstallInfo[];
+  running: RunningInstall;
+};
+
+/** Options for `discoverInstalls`. */
+export type DiscoverInstallsOptions = {
+  /** Where the project lookup starts. */
+  cwd: string;
+  /** The package root of the running copy. */
+  ownRoot: string;
+  /** How the managers are asked for their global roots. Defaults to spawning them. */
+  run?: CommandRunner;
+};
+
+/**
+ * Finds the project install, the global installs and what the running copy is.
+ * No step fails the run: a manager that is not installed or cannot answer is
+ * skipped, and a copy whose package.json is unreadable is left out.
+ */
+export async function discoverInstalls(options: DiscoverInstallsOptions): Promise<InstallDiscovery> {
+  const run = options.run ?? spawnCommand;
+  const project = await findProjectInstallInfo(options.cwd);
+  const globals = await findGlobalInstalls(run);
+  const running = classifyRunning(options.ownRoot, project, globals);
+  return project === undefined ? { globals, running } : { project, globals, running };
+}
+
+/**
+ * The project install nearest `cwd`: the copy the hand-off finds
+ * (`findProjectCopy`), and when there is none, a Yarn Plug'n'Play project
+ * that declares the package (`findPnpInstall`). Undefined when there is
+ * neither, or the `node_modules` copy found is some other package.
+ */
+export async function findProjectInstallInfo(cwd: string): Promise<ProjectInstallInfo | undefined> {
+  const location = findProjectCopy(cwd);
+  if (location === undefined) return findPnpInstall(cwd);
+  const copy = readPackageJson(location);
+  if (copy?.name !== PACKAGE_NAME) return undefined;
+
+  // <projectRoot>/node_modules/@sous-io/sous
+  const projectRoot = path.resolve(location, "..", "..", "..");
+  return describeProject(projectRoot, await projectManager(projectRoot), {
+    location,
+    realPath: realpathOr(location),
+    installed: versionOf(copy),
+  });
+}
+
+/** The file Yarn Plug'n'Play writes in place of `node_modules`. */
+export const PNP_FILE = ".pnp.cjs";
+
+/**
+ * A Yarn Plug'n'Play install, which has no `node_modules` copy to find: the
+ * nearest package.json at or above `cwd` that declares the package, with a
+ * `.pnp.cjs` in its directory or above it. The version is the one `yarn.lock`
+ * (beside `.pnp.cjs`) resolves the declared range to, and the manager is Yarn
+ * Berry, the only Yarn that writes `.pnp.cjs`. Undefined when either is missing.
+ */
+export function findPnpInstall(cwd: string): ProjectInstallInfo | undefined {
+  const projectRoot = findUp(cwd, (dir) => declaredDependency(readPackageJson(dir)) !== undefined);
+  if (projectRoot === undefined) return undefined;
+  const pnpRoot = findUp(projectRoot, (dir) => fs.existsSync(path.join(dir, PNP_FILE)));
+  if (pnpRoot === undefined) return undefined;
+
+  const range = declaredDependency(readPackageJson(projectRoot))?.range ?? "";
+  let lockfile = "";
+  try {
+    lockfile = fs.readFileSync(path.join(pnpRoot, "yarn.lock"), "utf8");
+  } catch {
+    // No lockfile: the version is unknown, and the plan says so.
+  }
+  const location = path.join(pnpRoot, PNP_FILE);
+  const info = describeProject(
+    projectRoot,
+    { supported: true, agent: "yarn@berry", detected: true },
+    {
+      location,
+      realPath: realpathOr(location),
+      installed: yarnLockVersion(lockfile, range) ?? UNKNOWN_VERSION,
+    }
+  );
+  info.pnpRoot = pnpRoot;
+  return info;
+}
+
+/**
+ * The version a Yarn Berry `yarn.lock` resolves the package's declared
+ * `range` to. Each entry opens with an unindented key listing the
+ * descriptors it answers (`"@sous-io/sous@npm:0.2.28, @sous-io/sous@npm:^0.2.0":`)
+ * and holds an indented `version:` line. The entry whose key names the range
+ * wins; when none does and the lockfile holds exactly one version of the
+ * package, that version is the answer. Undefined otherwise.
+ *
+ * yarnLockVersion('"@sous-io/sous@npm:0.2.28":\n  version: 0.2.28\n', "0.2.28") -> "0.2.28"
+ */
+export function yarnLockVersion(lockfile: string, range: string): string | undefined {
+  const prefix = `${PACKAGE_NAME}@`;
+  const wanted = new Set([`${prefix}${range}`, `${prefix}npm:${range}`]);
+  const entries: { descriptors: string[]; version?: string }[] = [];
+  let entry: { descriptors: string[]; version?: string } | undefined;
+  for (const line of lockfile.split(/\r?\n/)) {
+    if (/^[^\s#].*:$/.test(line)) {
+      const descriptors = line
+        .slice(0, -1)
+        .split(",")
+        .map((part) => part.trim().replace(/^"|"$/g, ""))
+        .filter((descriptor) => descriptor.startsWith(prefix));
+      entry = descriptors.length > 0 ? { descriptors } : undefined;
+      if (entry !== undefined) entries.push(entry);
+      continue;
+    }
+    const version = /^\s+version:\s*"?([^"\s]+)"?\s*$/.exec(line);
+    if (entry !== undefined && version !== null && entry.version === undefined) {
+      entry.version = version[1];
+    }
+  }
+  const exact = entries.find((candidate) => candidate.descriptors.some((d) => wanted.has(d)));
+  if (exact !== undefined) return exact.version;
+  const versions = new Set(entries.flatMap((candidate) => candidate.version ?? []));
+  return versions.size === 1 ? [...versions][0] : undefined;
+}
+
+/** A project install, from its root, its manager and the facts about its copy. */
+function describeProject(
+  projectRoot: string,
+  manager: ProjectManagerInfo,
+  copy: { location: string; realPath: string; installed: string }
+): ProjectInstallInfo {
+  const pkg = readPackageJson(projectRoot);
+  const declared = declaredDependency(pkg);
+  const info: ProjectInstallInfo = {
+    projectRoot,
+    ...copy,
+    manager,
+    workspaceRoot: isWorkspaceRoot(manager.agent, projectRoot, pkg),
+  };
+  if (declared !== undefined) info.declared = declared;
+  return info;
+}
+
+/** The nearest directory at or above `start` that `test` accepts, or undefined. */
+function findUp(start: string, test: (dir: string) => boolean): string | undefined {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (test(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/**
+ * How a package.json declares sous: `devDependencies` first, then
+ * `dependencies`; undefined when neither names it.
+ */
+export function declaredDependency(pkg: unknown): DeclaredDependency | undefined {
+  if (pkg === null || typeof pkg !== "object") return undefined;
+  for (const section of ["devDependencies", "dependencies"] as const) {
+    const block = (pkg as Record<string, unknown>)[section];
+    if (block === null || typeof block !== "object") continue;
+    const range = (block as Record<string, unknown>)[PACKAGE_NAME];
+    if (typeof range === "string") return { section, range };
+  }
+  return undefined;
+}
+
+/**
+ * Which manager owns the project at `projectRoot`, read by
+ * package-manager-detector from that directory alone (its `packageManager`
+ * and `devEngines` fields and its lockfile). Nothing found means npm, marked
+ * as not detected.
+ *
+ * Two corrections are made on top: a `yarn` answer from a lockfile is Yarn
+ * Berry when the project has a `.yarnrc.yml` or its `yarn.lock` carries Berry's
+ * `__metadata` header (the detector reads a lockfile as classic unless the
+ * `packageManager` field says otherwise), and `pnpm@6` is plain pnpm, whose
+ * `add` flags have not changed.
+ */
+export async function projectManager(projectRoot: string): Promise<ProjectManagerInfo> {
+  const found = await detect({ cwd: projectRoot, stopDir: projectRoot });
+  if (found === null) return { supported: true, agent: "npm", detected: false };
+  let agent: string = found.agent;
+  if (agent === "yarn" && isYarnBerryProject(projectRoot)) agent = "yarn@berry";
+  if (agent === "pnpm@6") agent = "pnpm";
+  return isProjectManager(agent)
+    ? { supported: true, agent, detected: true }
+    : { supported: false, agent };
+}
+
+/** Whether the files at `projectRoot` are Yarn Berry's rather than Yarn classic's. */
+function isYarnBerryProject(projectRoot: string): boolean {
+  if (fs.existsSync(path.join(projectRoot, ".yarnrc.yml"))) return true;
+  try {
+    return /^__metadata:/m.test(fs.readFileSync(path.join(projectRoot, "yarn.lock"), "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether `projectRoot` is a workspace root in the sense its manager needs a
+ * flag for: pnpm, when it holds a `pnpm-workspace.yaml`; Yarn classic, when
+ * its package.json has `workspaces`. Every other manager reads as false.
+ */
+export function isWorkspaceRoot(agent: string, projectRoot: string, pkg: unknown): boolean {
+  if (agent === "pnpm") return fs.existsSync(path.join(projectRoot, "pnpm-workspace.yaml"));
+  if (agent === "yarn") {
+    return pkg !== null && typeof pkg === "object" && "workspaces" in pkg;
+  }
+  return false;
+}
+
+/** The command that prints each global manager's global `node_modules`, and how to read it. */
+const GLOBAL_ROOT_QUERIES: Record<GlobalManager, { args: string[]; suffix?: string }> = {
+  npm: { args: ["root", "-g"] },
+  pnpm: { args: ["root", "-g"] },
+  // `yarn global dir` prints the directory ABOVE its node_modules.
+  yarn: { args: ["global", "dir"], suffix: "node_modules" },
+};
+
+/**
+ * Asks each global manager where its global `node_modules` is, and returns a
+ * global install for each one that holds a copy of the package. A manager that
+ * is not installed (exit 127), exits non-zero or prints nothing is skipped. Two
+ * managers naming the same copy (by real path) count once, under the first.
+ */
+export async function findGlobalInstalls(run: CommandRunner): Promise<GlobalInstallInfo[]> {
+  const installs: GlobalInstallInfo[] = [];
+  for (const manager of GLOBAL_MANAGERS) {
+    const root = await globalRoot(manager, run);
+    if (root === undefined) continue;
+    const location = path.join(root, ...PACKAGE_NAME.split("/"));
+    const pkg = readPackageJson(location);
+    if (pkg?.name !== PACKAGE_NAME) continue;
+    const realPath = realpathOr(location);
+    if (installs.some((install) => install.realPath === realPath)) continue;
+    installs.push({ manager, location, realPath, installed: versionOf(pkg) });
+  }
+  return installs;
+}
+
+/** One manager's global `node_modules`, or undefined when it cannot say. */
+async function globalRoot(manager: GlobalManager, run: CommandRunner): Promise<string | undefined> {
+  const query = GLOBAL_ROOT_QUERIES[manager];
+  let output: string;
+  try {
+    const result = await run(manager, query.args, {});
+    if (result.code !== 0) return undefined;
+    output = result.stdout.trim().split(/\r?\n/).pop()?.trim() ?? "";
+  } catch {
+    return undefined;
+  }
+  if (output.length === 0) return undefined;
+  return query.suffix === undefined ? output : path.join(output, query.suffix);
+}
+
+/**
+ * What the running copy at `ownRoot` is: the project install or a global one
+ * when its real path is theirs, otherwise read from where it lives.
+ */
+export function classifyRunning(
+  ownRoot: string,
+  project: ProjectInstallInfo | undefined,
+  globals: readonly GlobalInstallInfo[]
+): RunningInstall {
+  const realPath = realpathOr(ownRoot);
+  const pkg = readPackageJson(ownRoot);
+  const installed = pkg === undefined ? UNKNOWN_VERSION : versionOf(pkg);
+  if (project !== undefined && (project.realPath === realPath || isPnpCopy(project, realPath))) {
+    return { kind: "project", realPath, installed };
+  }
+  const global = globals.find((install) => install.realPath === realPath);
+  if (global !== undefined) return { kind: "global", manager: global.manager, realPath, installed };
+  const slashed = realPath.split(path.sep).join("/");
+  if (slashed.includes("/_npx/")) return { kind: "npx", realPath, installed };
+  if (slashed.includes("/.volta/")) return { kind: "volta", realPath, installed };
+  return { kind: "unknown", realPath, installed };
+}
+
+/**
+ * Whether `realPath` is the Plug'n'Play project's own copy, unpacked by Yarn
+ * into `<pnpRoot>/.yarn/unplugged/` (a copy still inside Yarn's zip cache
+ * cannot run sous at all).
+ */
+function isPnpCopy(project: ProjectInstallInfo, realPath: string): boolean {
+  if (project.pnpRoot === undefined) return false;
+  const unplugged = path.join(realpathOr(project.pnpRoot), ".yarn", "unplugged");
+  const relative = path.relative(unplugged, realPath);
+  return relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+/** The `version` a package.json names, or `UNKNOWN_VERSION`. */
+function versionOf(pkg: Record<string, unknown>): string {
+  return typeof pkg.version === "string" ? pkg.version : UNKNOWN_VERSION;
+}

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

@@ -0,0 +1,126 @@
+/**
+ * The command each package manager needs to install a version of sous.
+ *
+ * The commands come from package-manager-detector's table (`resolveCommand`),
+ * so sous spells nothing a manager already publishes; this module adds the
+ * flags an update needs on top (an exact pin, the dependency section, the
+ * workspace root) and runs nothing.
+ */
+
+import { resolveCommand } from "package-manager-detector/commands";
+import type { Agent } from "package-manager-detector";
+import { PACKAGE_NAME } from "../project-install.mjs";
+
+/** The managers that can update a project's own install. */
+export const PROJECT_MANAGERS = ["npm", "pnpm", "yarn", "yarn@berry"] as const;
+
+/** The managers that can update a global install (Yarn Berry has no global installs). */
+export const GLOBAL_MANAGERS = ["npm", "pnpm", "yarn"] as const;
+
+/** A manager that can update a project install; `yarn` is Yarn classic (1.x). */
+export type ProjectManager = (typeof PROJECT_MANAGERS)[number];
+
+/** A manager that can update a global install; `yarn` is Yarn classic (1.x). */
+export type GlobalManager = (typeof GLOBAL_MANAGERS)[number];
+
+/** A command and its arguments, not yet run. */
+export type ManagerCommand = { command: string; args: string[] };
+
+/** The section of package.json a project declares sous in. */
+export type DependencySection = "devDependencies" | "dependencies";
+
+/** Options for `projectAdd`. */
+export type ProjectAddOptions = {
+  /** The section the dependency is declared in; it stays there. */
+  section: DependencySection;
+  /**
+   * Whether the project is a workspace root, as its manager reads one (see
+   * `isWorkspaceRoot` in installs.ts). pnpm and Yarn classic then need a flag
+   * to add a dependency there at all.
+   */
+  workspaceRoot: boolean;
+};
+
+/** Whether `agent` is one of `PROJECT_MANAGERS`. */
+export function isProjectManager(agent: string): agent is ProjectManager {
+  return (PROJECT_MANAGERS as readonly string[]).includes(agent);
+}
+
+/** Whether `agent` is one of `GLOBAL_MANAGERS`. */
+export function isGlobalManager(agent: string): agent is GlobalManager {
+  return (GLOBAL_MANAGERS as readonly string[]).includes(agent);
+}
+
+/**
+ * The package spec an install names: `@sous-io/sous@<version>`.
+ *
+ * packageSpec("0.2.34") -> "@sous-io/sous@0.2.34"
+ */
+export function packageSpec(version: string): string {
+  return `${PACKAGE_NAME}@${version}`;
+}
+
+/**
+ * The command that installs `version` globally with `manager`.
+ *
+ * globalInstall("pnpm", "0.2.34")
+ * // -> { command: "pnpm", args: ["add", "-g", "@sous-io/sous@0.2.34"] }
+ */
+export function globalInstall(manager: GlobalManager, version: string): ManagerCommand {
+  return resolve(manager, "global", [packageSpec(version)]);
+}
+
+/**
+ * The command that pins a project's dependency on sous to exactly `version`
+ * and updates its lockfile, run in the project root.
+ *
+ * `-E` pins the exact version with every supported manager; `-D` is added only
+ * for a devDependency, so a dependency declared under `dependencies` stays
+ * there. At a workspace root, pnpm gets `-w` and Yarn classic `-W`; npm adds
+ * to the root package.json when run there, and Yarn Berry needs no flag.
+ *
+ * projectAdd("pnpm", "0.2.34", { section: "devDependencies", workspaceRoot: true })
+ * // -> { command: "pnpm", args: ["add", "-D", "-E", "-w", "@sous-io/sous@0.2.34"] }
+ */
+export function projectAdd(
+  manager: ProjectManager,
+  version: string,
+  options: ProjectAddOptions
+): ManagerCommand {
+  const flags: string[] = [];
+  if (options.section === "devDependencies") flags.push("-D");
+  flags.push("-E");
+  if (options.workspaceRoot) {
+    if (manager === "pnpm") flags.push("-w");
+    if (manager === "yarn") flags.push("-W");
+  }
+  return resolve(manager, "add", [...flags, packageSpec(version)]);
+}
+
+/**
+ * The command a person would run by hand to pin a project's dependency with a
+ * manager sous does not drive (bun, deno), or undefined when
+ * package-manager-detector knows no `add` command for it.
+ */
+export function manualProjectAdd(
+  agent: string,
+  version: string,
+  section: DependencySection
+): ManagerCommand | undefined {
+  const flags = section === "devDependencies" ? ["-D"] : [];
+  try {
+    return resolveCommand(agent as Agent, "add", [...flags, packageSpec(version)]) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Resolves a command the table is known to hold for every supported manager. */
+function resolve(agent: Agent, command: "add" | "global", args: string[]): ManagerCommand {
+  const resolved = resolveCommand(agent, command, args);
+  /* c8 ignore next 3 */
+  if (resolved === null) {
+    throw new Error(`package-manager-detector has no '${command}' command for ${agent}.`);
+  }
+  return { command: resolved.command, args: resolved.args };
+}