@edspencer/paddock 0.82.0 → 0.83.0

package/packages/server/dist/cli/update/package-manager.js

@@ -1,107 +1,95 @@
-/**
- * Running the package manager (CLI contract SPEC §5 steps 8 and 10, §6, §7).
- *
- * Three jobs, all of them small and all of them easy to get subtly wrong:
- *
- * - **Find npm.** SPEC §6 and §10 both say the `npm` next to
- *   `process.execPath`, not whatever is on PATH. Under nvm, fnm or volta those
- *   are routinely different npms belonging to different Nodes, and asking the
- *   wrong one `npm root -g` gets a global folder this install is not in — which
- *   would report a perfectly ordinary global install as a `dependency` and
- *   refuse to update it.
- * - **No shell.** `spawnSync(npm, args)` with the default `shell: false`, so a
- *   package name or a path with a space in it cannot become two arguments.
- *   Windows is the exception and has to be: `npm` there is `npm.cmd`, which
- *   Node refuses to spawn without a shell since its fix for CVE-2024-27980
- *   (SPEC §7). That path quotes its arguments itself.
- * - **Can we write there?** SPEC §5 step 5. Asked before anything is stopped,
- *   and answered by actually creating a file rather than by `access()` alone —
- *   see {@link isWritable}.
- *
- * Generic: wave C4 lifts this into `reference/`. Node built-ins only.
- */
-import { spawnSync } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
+// From edspencer/cli-contract reference/package-manager.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
+// Running the package manager (SPEC §5 steps 5, 8 and 10, §6, §7). Node built-ins only.
+//
+// - **npm is the one beside `process.execPath`**, run as `node <npm-cli.js>`, never whichever `npm` is first on PATH.
+//   Under nvm, fnm or volta those are different npms for different Nodes, and the wrong one's `npm root -g` is a
+//   global folder this install isn't in: an ordinary global install would read as a dependency and refuse to update.
+//   Running `npm-cli.js` with this Node also needs no shell on Windows, where `npm.cmd` would (CVE-2024-27980).
+// - **No shell otherwise**, so a path or a name with a space in it can't become two arguments. pnpm, bun and volta on
+//   Windows are `.cmd` files and do need one; their arguments are quoted for `cmd.exe` here.
+// - **Writable means a file can be created**, not just that `access()` says yes (`isWritable`).
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 export const spawnSyncRunner = (cmd, args, opts = {}) => {
     const r = spawnSync(cmd, args, {
-        encoding: "utf8",
+        encoding: 'utf8',
         ...(opts.env !== undefined ? { env: opts.env } : {}),
         ...(opts.shell === true ? { shell: true } : {}),
         ...(opts.timeoutMs !== undefined ? { timeout: opts.timeoutMs } : {}),
         maxBuffer: 32 * 1024 * 1024,
+        windowsHide: true,
     });
-    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+    return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? (r.error ? String(r.error.message) : '') };
 };
+/** How long an install may take. */
+export const INSTALL_TIMEOUT_MS = 15 * 60 * 1000;
 /**
- * The npm that belongs to the Node running us.
- *
- * `<dirname(execPath)>/npm` on POSIX; on Windows the sibling is `npm.cmd`.
- * Falls back to the bare name — if the sibling is not there (a distro that
- * splits node and npm into separate packages), PATH is the only answer left and
- * is better than failing.
+ * How to run the npm that belongs to this Node: `[execPath, npm-cli.js]`, found beside it (`<dir>/npm` is a symlink
+ * to it on POSIX; on Windows it's `<dir>/node_modules/npm/bin/npm-cli.js`). Falls back to `npm` on the PATH, for a
+ * distribution that packages npm separately.
  */
-export function npmBeside(execPath = process.execPath, platform = process.platform) {
+export function npmCommand(ctx = {}) {
+    const execPath = ctx.execPath ?? process.execPath;
+    const platform = ctx.platform ?? process.platform;
+    const exists = ctx.exists ?? ((p) => fs.existsSync(p));
+    const realpath = ctx.realpath ?? ((p) => fs.realpathSync(p));
     const dir = path.dirname(execPath);
-    const candidate = path.join(dir, platform === "win32" ? "npm.cmd" : "npm");
-    try {
-        if (fs.existsSync(candidate))
-            return candidate;
+    const candidates = platform === 'win32'
+        ? [path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js')]
+        : [path.join(dir, 'npm'), path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')];
+    for (const c of candidates) {
+        if (!exists(c))
+            continue;
+        let real = c;
+        try {
+            real = realpath(c);
+        }
+        catch {
+            // keep the candidate
+        }
+        if (real.endsWith('.js'))
+            return { cmd: execPath, pre: [real], shell: false };
     }
-    catch {
-        /* fall through */
-    }
-    return platform === "win32" ? "npm.cmd" : "npm";
+    return platform === 'win32' ? { cmd: 'npm.cmd', pre: [], shell: true } : { cmd: 'npm', pre: [], shell: false };
 }
-/** Run npm with no shell (except on Windows, where `npm.cmd` needs one). */
-export function runNpm(args, ctx = {}) {
-    const platform = ctx.platform ?? process.platform;
-    const cmd = npmBeside(ctx.execPath ?? process.execPath, platform);
+/** Quotes each word for `cmd.exe`, for the one case that needs a shell. */
+function cmdLine(cmd, args) {
+    const q = (a) => (/^[\w@./:=+-]+$/.test(a) ? a : `"${a.replace(/"/g, '""')}"`);
+    return { cmd: [cmd, ...args].map(q).join(' '), args: [] };
+}
+function runWith(cmd, args, shell, ctx, timeoutMs) {
     const run = ctx.spawn ?? spawnSyncRunner;
-    return run(cmd, args, {
-        ...(ctx.env !== undefined ? { env: ctx.env } : {}),
-        // The ONE place a shell is used, and only where Node leaves no choice. The
-        // arguments passed through here are package specs and npm flags we build
-        // ourselves, never user text.
-        ...(platform === "win32" ? { shell: true } : {}),
-        timeoutMs: 15 * 60 * 1000,
-    });
+    const line = shell ? cmdLine(cmd, args) : { cmd, args };
+    return run(line.cmd, line.args, { ...(ctx.env !== undefined ? { env: ctx.env } : {}), ...(shell ? { shell: true } : {}), timeoutMs });
 }
-/** `npm root -g`, or undefined when npm could not answer. */
-export function npmGlobalRoot(ctx = {}) {
-    const r = runNpm(["root", "-g"], ctx);
+/** Runs this Node's npm. */
+export function runNpm(args, ctx = {}, timeoutMs = INSTALL_TIMEOUT_MS) {
+    const { cmd, pre, shell } = npmCommand(ctx);
+    return runWith(cmd, [...pre, ...args], shell, ctx, timeoutMs);
+}
+const lastLine = (r) => {
     if (r.status !== 0)
         return undefined;
-    const out = r.stdout.trim().split("\n").at(-1)?.trim();
-    return out !== undefined && out !== "" ? out : undefined;
+    const out = r.stdout.trim().split(/\r?\n/).at(-1)?.trim();
+    return out !== undefined && out !== '' && out !== 'undefined' && out !== 'null' ? out : undefined;
+};
+/** `npm root -g`, or undefined when npm can't answer. */
+export function npmGlobalRoot(ctx = {}) {
+    return lastLine(runNpm(['root', '-g'], ctx, 60_000));
 }
-/** `npm config get <key>`, or undefined. Used to resolve the registry (SPEC §5 step 3). */
+/** `npm config get <key>`, or undefined. */
 export function npmConfigGet(key, ctx = {}) {
-    const r = runNpm(["config", "get", key], ctx);
-    if (r.status !== 0)
-        return undefined;
-    const out = r.stdout.trim().split("\n").at(-1)?.trim();
-    return out !== undefined && out !== "" && out !== "undefined" && out !== "null" ? out : undefined;
+    return lastLine(runNpm(['config', 'get', key], ctx, 60_000));
 }
 /**
- * Really writable? (SPEC §5 step 5.)
- *
- * `access(W_OK)` alone is not enough and the difference is the whole point of
- * this check. It consults the mode bits, which say yes for root and say
- * nothing about a read-only mount, an immutable flag, or an ACL — the usual
- * shapes of "npm install -g needs sudo". So the directory is probed by
- * CREATING something in it and removing it again, which is the same syscall
- * npm is about to make.
- *
- * A missing directory walks up to its nearest existing parent: npm would create
- * it, and whether it can is the parent's question.
+ * Whether `dir` is really writable (SPEC §5 step 5): a folder is created in it and removed again, the same call npm
+ * is about to make. `access(W_OK)` alone says yes to root on a read-only mount, and nothing about ACLs or immutable
+ * flags. A folder that doesn't exist yet asks its nearest existing parent, since npm would create it.
  */
 export function isWritable(dir) {
     let probe = dir;
-    for (;;) {
-        if (fs.existsSync(probe))
-            break;
+    while (!fs.existsSync(probe)) {
         const parent = path.dirname(probe);
         if (parent === probe)
             return false;
@@ -109,13 +97,7 @@ export function isWritable(dir) {
     }
     try {
         fs.accessSync(probe, fs.constants.W_OK);
-    }
-    catch {
-        return false;
-    }
-    try {
-        const tmp = fs.mkdtempSync(path.join(probe, ".update-probe-"));
-        fs.rmSync(tmp, { recursive: true, force: true });
+        fs.rmSync(fs.mkdtempSync(path.join(probe, '.update-probe-')), { recursive: true, force: true });
         return true;
     }
     catch {
@@ -123,99 +105,52 @@ export function isWritable(dir) {
     }
 }
 /**
- * Where a package manager would put the package, so {@link isWritable} has a
- * directory to ask about.
- *
- * Only npm can be asked properly (`npm root -g`). For the others the install
- * command's own target is a good enough proxy — and if it is wrong, the install
- * fails with that manager's own message and the rollback runs, which is a worse
- * experience than the sudo hint but not a worse outcome.
+ * Where a manager would install, for `isWritable` to ask about. Only npm can be asked (`npm root -g`). For the others
+ * there's no answer, and an install that can't write fails with that manager's own message, and rolls back.
  */
 export function globalRootFor(manager, ctx = {}) {
-    if (manager === "npm")
-        return npmGlobalRoot(ctx);
-    return undefined;
+    return manager === 'npm' ? npmGlobalRoot(ctx) : undefined;
 }
-/** The argv for a global install, per SPEC §6's last column. */
+/** The global install command, per SPEC §6's last column. */
 export function installArgs(manager, spec) {
     switch (manager) {
-        case "npm":
-            // `--no-audit --no-fund` keeps the output to the point; `--global` is
-            // spelled out rather than `-g` so a log of what ran reads plainly.
-            return { cmd: "npm", args: ["install", "--global", "--no-audit", "--no-fund", spec] };
-        case "pnpm":
-            return { cmd: "pnpm", args: ["add", "-g", spec] };
-        case "bun":
-            return { cmd: "bun", args: ["add", "-g", spec] };
-        case "volta":
-            return { cmd: "volta", args: ["install", spec] };
+        case 'npm':
+            return { cmd: 'npm', args: ['install', '--global', '--no-audit', '--no-fund', spec] };
+        case 'pnpm':
+            return { cmd: 'pnpm', args: ['add', '-g', spec] };
+        case 'bun':
+            return { cmd: 'bun', args: ['add', '-g', spec] };
+        case 'volta':
+            return { cmd: 'volta', args: ['install', spec] };
     }
 }
-/**
- * Install `<name>@<version>` with the manager this install came from.
- *
- * npm goes through {@link runNpm}, so it is the npm beside this Node. The other
- * three are looked up on PATH, which is the only place they are: pnpm, bun and
- * volta are not installed beside node.
- */
+/** Installs `<name>@<version>` with the manager this install came from. pnpm, bun and volta come from the PATH. */
 export function installPackage(o) {
-    const spec = `${o.packageName}@${o.version}`;
-    const { cmd, args } = installArgs(o.manager, spec);
-    if (o.manager === "npm") {
-        return runNpm(args, {
-            ...(o.spawn !== undefined ? { spawn: o.spawn } : {}),
-            ...(o.env !== undefined ? { env: o.env } : {}),
-            ...(o.execPath !== undefined ? { execPath: o.execPath } : {}),
-            ...(o.platform !== undefined ? { platform: o.platform } : {}),
-        });
-    }
-    const run = o.spawn ?? spawnSyncRunner;
-    return run(cmd, args, {
-        ...(o.env !== undefined ? { env: o.env } : {}),
-        ...((o.platform ?? process.platform) === "win32" ? { shell: true } : {}),
-        timeoutMs: 15 * 60 * 1000,
-    });
+    const { cmd, args } = installArgs(o.manager, `${o.packageName}@${o.version}`);
+    if (o.manager === 'npm')
+        return runNpm(args, o);
+    return runWith(cmd, args, (o.platform ?? process.platform) === 'win32', o, INSTALL_TIMEOUT_MS);
 }
 /**
- * `npm cache add <name>@<version>` — fetch before stopping anything
- * (SPEC §5 step 8).
- *
- * Both the target and the CURRENT version are cached, and caching the current
- * one is the half that is easy to leave out and expensive to miss: it is what
- * gives the rollback a package to reinstall when the reason the update failed
- * was the network. Done while the old version is still serving, so a failure
- * here costs nothing but a message.
- *
- * `npm cache add` is used whatever the manager is, because every one of these
- * layouts has an npm available (it ships with Node) and the point is only to
- * have the tarball on the machine. A failure is reported and not fatal — the
- * install below may still succeed from the network.
+ * `npm cache add <name>@<version>` (SPEC §5 step 8), for the target and for the current version, while the old one
+ * still serves. Caching the current one is what lets a rollback reinstall it when the network is what failed. npm
+ * is used whatever the manager: it ships with Node, and the point is only to have the tarball on the machine.
  */
 export function cacheAdd(packageName, version, ctx = {}) {
-    return runNpm(["cache", "add", `${packageName}@${version}`], ctx);
+    return runNpm(['cache', 'add', `${packageName}@${version}`], ctx);
 }
 /**
- * Ask a CLI what version it is, by running it (`node <cli> --version`).
- *
- * This is how `update` proves that the install actually replaced the files
- * before it hands over to the new CLI. The alternative — reading the
- * `package.json` next to it — answers a different question: npm writes the
- * manifest and the files in one operation, but a partially-updated global
- * folder, a stale symlink, or a pnpm layout whose versioned realpath moved all
- * show up here and not there.
+ * A CLI's version, by running it: `node <cli> --version`. This is how `update` shows the install replaced the files
+ * before it hands over. A `package.json` beside it answers a different question: a stale symlink, or a pnpm layout
+ * whose versioned path moved, shows up here and not there.
  */
 export function cliVersion(cliPath, ctx = {}) {
-    const run = ctx.spawn ?? spawnSyncRunner;
-    const r = run(ctx.execPath ?? process.execPath, [cliPath, "--version"], {
+    const r = (ctx.spawn ?? spawnSyncRunner)(ctx.execPath ?? process.execPath, [cliPath, '--version'], {
         ...(ctx.env !== undefined ? { env: ctx.env } : {}),
         timeoutMs: 60_000,
     });
     if (r.status !== 0)
         return undefined;
-    const line = r.stdout.trim().split("\n")[0]?.trim();
+    const line = r.stdout.trim().split(/\r?\n/)[0]?.trim();
     return line !== undefined && /^\d+\.\d+\.\d+/.test(line) ? line : undefined;
 }
-/** A throwaway directory, for callers that need one (the writability probe's sibling). */
-export function tmpDir(prefix) {
-    return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
-}

package/packages/server/dist/cli/update/registry.d.ts

@@ -1,55 +1,24 @@
-/**
- * The npm registry, as `update` asks it (CLI contract SPEC §5 step 3).
- *
- * Two requests, both with `fetch` and a 10-second abort, and nothing else:
- *
- *   GET <registry>/-/package/<name>/dist-tags   which version is `latest`
- *   GET <registry>/<name>/<version>             that version's `engines`
- *
- * Deliberately NOT `npm view`: spawning npm to read two small JSON documents
- * costs a second of process start-up, needs npm to be on PATH at all, and puts
- * the registry's answer through a program whose output format is not a
- * contract. `fetch` is in Node 22 and the registry's REST surface has been
- * stable for a decade.
- *
- * **Nothing here is called except by a person.** SPEC §3: only `update`,
- * `update --check` and `doctor` contact the registry, and only when someone
- * runs them. There is no background check and no check at startup, which is why
- * this module is reachable from the CLI and from nowhere in the server.
- *
- * Generic: wave C4 lifts it into `reference/registry.ts`.
- */
-/** SPEC §5: 10 seconds, and it is the budget for each request rather than the pair. */
+/** SPEC §5: 10 seconds for each request. */
 export declare const REGISTRY_TIMEOUT_MS = 10000;
 export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
 export interface RegistryOptions {
     packageName: string;
-    /** Base URL, no trailing slash required — {@link registryUrl} normalises it. */
+    /** The base URL; a trailing slash is fine. */
     registry: string;
     fetch?: typeof globalThis.fetch;
     timeoutMs?: number;
 }
 /**
- * Which registry to ask: `npm_config_registry`, else `npm config get registry`,
- * else the public one (SPEC §5 step 3).
- *
- * The first is what makes the fake-registry tests possible without touching a
- * global npm config — an `npm_config_registry` in the environment is how npm
- * itself takes the same setting, so a test and a real `.npmrc` arrive by the
- * same door.
+ * Which registry to ask: `npm_config_registry`, else `npm config get registry`, else the public one (SPEC §5 step 3).
+ * The variable comes first because it's how npm itself takes the setting, so a test and a real `.npmrc` arrive the
+ * same way.
  */
 export declare function resolveRegistry(env: NodeJS.ProcessEnv, npmConfigGet?: (key: string) => string | undefined): string;
-/**
- * Join a path onto the registry base.
- *
- * A scoped name's `/` is written `%2f` (SPEC §5 step 3). That is required by
- * the dist-tags route and accepted by the manifest route, so both are built the
- * same way — one rule instead of two, and no chance of only one of them being
- * right for `@scope/name`.
- */
+/** Joins path parts onto the registry, writing a scoped name's `/` as `%2f` (SPEC §5 step 3). Both routes take it. */
 export declare function registryUrl(registry: string, ...parts: string[]): string;
-/** Everything that went wrong talking to the registry, as one reportable error. */
+/** Anything that went wrong talking to the registry, with the URL, as one reportable error. */
 export declare class RegistryError extends Error {
+    name: string;
     readonly url: string;
     constructor(url: string, message: string);
 }
@@ -62,28 +31,22 @@ export interface PackageManifest {
         node?: string;
     };
 }
-/** One version's manifest — read for `engines` (SPEC §5 step 3). */
+/** One version's manifest, read for `engines`. */
 export declare function fetchManifest(o: RegistryOptions & {
     version: string;
 }): Promise<PackageManifest>;
-export interface ResolveTargetInput extends RegistryOptions {
-    /** `--to <version|tag>`, or undefined for `latest`. */
-    to?: string;
-}
 export interface ResolvedTarget {
     version: string;
-    /** The dist-tag asked for, or null when `--to` named a version (schema field). */
+    /** The dist-tag asked for, or null when `--to` named a version. */
     tag: string | null;
+    /** The target's `engines.node`. */
     engines: string | null;
 }
 /**
- * Turn `--to` (or its absence) into one concrete version, plus its `engines`.
- *
- * `--to` is a version or a dist-tag and the two are told apart by shape, not by
- * asking: anything that parses as a version is a version, everything else is a
- * tag. That ordering matters because a registry will happily serve a manifest
- * for a tag name as well, and resolving `--to next` as a literal version would
- * silently install whatever `next` pointed at while REPORTING the target as
- * "next".
+ * `--to` (or `latest` without it) as one version, with its `engines`. A version and a tag are told apart by shape:
+ * anything that looks like a version is one. Asking first would be wrong, since a registry may serve a manifest for a
+ * tag's name too, and `--to next` would then install `next` while reporting it as a version called "next".
  */
-export declare function resolveTarget(o: ResolveTargetInput): Promise<ResolvedTarget>;
+export declare function resolveTarget(o: RegistryOptions & {
+    to?: string;
+}): Promise<ResolvedTarget>;

package/packages/server/dist/cli/update/registry.js

@@ -1,60 +1,36 @@
-/**
- * The npm registry, as `update` asks it (CLI contract SPEC §5 step 3).
- *
- * Two requests, both with `fetch` and a 10-second abort, and nothing else:
- *
- *   GET <registry>/-/package/<name>/dist-tags   which version is `latest`
- *   GET <registry>/<name>/<version>             that version's `engines`
- *
- * Deliberately NOT `npm view`: spawning npm to read two small JSON documents
- * costs a second of process start-up, needs npm to be on PATH at all, and puts
- * the registry's answer through a program whose output format is not a
- * contract. `fetch` is in Node 22 and the registry's REST surface has been
- * stable for a decade.
- *
- * **Nothing here is called except by a person.** SPEC §3: only `update`,
- * `update --check` and `doctor` contact the registry, and only when someone
- * runs them. There is no background check and no check at startup, which is why
- * this module is reachable from the CLI and from nowhere in the server.
- *
- * Generic: wave C4 lifts it into `reference/registry.ts`.
- */
-/** SPEC §5: 10 seconds, and it is the budget for each request rather than the pair. */
+// From edspencer/cli-contract reference/registry.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// The npm registry, as `update` asks it (SPEC §5 step 3): two requests with `fetch` and a 10-second abort.
+//
+//   GET <registry>/-/package/<name>/dist-tags   which version `latest` (or `--to <tag>`) is
+//   GET <registry>/<name>/<version>             that version's `engines`
+//
+// Not `npm view`: that's a second of start-up to read two small documents, through a program whose output isn't a
+// contract. Only `update`, `update --check` and `doctor` call this, and only when a person runs them (SPEC §3).
+// Node built-ins only.
+/** SPEC §5: 10 seconds for each request. */
 export const REGISTRY_TIMEOUT_MS = 10_000;
-export const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
 /**
- * Which registry to ask: `npm_config_registry`, else `npm config get registry`,
- * else the public one (SPEC §5 step 3).
- *
- * The first is what makes the fake-registry tests possible without touching a
- * global npm config — an `npm_config_registry` in the environment is how npm
- * itself takes the same setting, so a test and a real `.npmrc` arrive by the
- * same door.
+ * Which registry to ask: `npm_config_registry`, else `npm config get registry`, else the public one (SPEC §5 step 3).
+ * The variable comes first because it's how npm itself takes the setting, so a test and a real `.npmrc` arrive the
+ * same way.
  */
 export function resolveRegistry(env, npmConfigGet) {
     const fromEnv = env.npm_config_registry ?? env.NPM_CONFIG_REGISTRY;
-    if (fromEnv !== undefined && fromEnv.trim() !== "")
+    if (fromEnv !== undefined && fromEnv.trim() !== '')
         return fromEnv.trim();
-    const fromNpm = npmConfigGet?.("registry");
-    if (fromNpm !== undefined && fromNpm.trim() !== "" && fromNpm.trim() !== "undefined") {
-        return fromNpm.trim();
-    }
+    const fromNpm = npmConfigGet?.('registry')?.trim();
+    if (fromNpm !== undefined && fromNpm !== '' && fromNpm !== 'undefined')
+        return fromNpm;
     return DEFAULT_REGISTRY;
 }
-/**
- * Join a path onto the registry base.
- *
- * A scoped name's `/` is written `%2f` (SPEC §5 step 3). That is required by
- * the dist-tags route and accepted by the manifest route, so both are built the
- * same way — one rule instead of two, and no chance of only one of them being
- * right for `@scope/name`.
- */
+/** Joins path parts onto the registry, writing a scoped name's `/` as `%2f` (SPEC §5 step 3). Both routes take it. */
 export function registryUrl(registry, ...parts) {
-    const base = registry.replace(/\/+$/, "");
-    return `${base}/${parts.map((p) => p.replace(/\//g, "%2f")).join("/")}`;
+    return `${registry.replace(/\/+$/, '')}/${parts.map((p) => p.replace(/\//g, '%2f')).join('/')}`;
 }
-/** Everything that went wrong talking to the registry, as one reportable error. */
+/** Anything that went wrong talking to the registry, with the URL, as one reportable error. */
 export class RegistryError extends Error {
+    name = 'RegistryError';
     url;
     constructor(url, message) {
         super(message);
@@ -62,83 +38,64 @@ export class RegistryError extends Error {
     }
 }
 async function getJson(url, o) {
-    const doFetch = o.fetch ?? globalThis.fetch;
+    const timeoutMs = o.timeoutMs ?? REGISTRY_TIMEOUT_MS;
     let res;
     try {
-        res = await doFetch(url, {
-            signal: AbortSignal.timeout(o.timeoutMs ?? REGISTRY_TIMEOUT_MS),
-            headers: { accept: "application/json" },
-        });
+        res = await (o.fetch ?? globalThis.fetch)(url, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: 'application/json' } });
     }
     catch (err) {
-        const why = err.name === "TimeoutError" || err.name === "AbortError"
-            ? `no answer within ${(o.timeoutMs ?? REGISTRY_TIMEOUT_MS) / 1000} seconds`
-            : (err.message ?? String(err));
-        throw new RegistryError(url, `could not reach the registry: ${why}`);
+        const name = err.name;
+        const why = name === 'TimeoutError' || name === 'AbortError' ? `no answer within ${timeoutMs / 1000} seconds` : (err.message ?? String(err));
+        throw new RegistryError(url, `couldn't reach the registry: ${why}`);
     }
     if (res.status === 404)
-        throw new RegistryError(url, "the registry has no such package or version");
+        throw new RegistryError(url, 'the registry has no such package or version');
     if (!res.ok)
         throw new RegistryError(url, `the registry answered HTTP ${res.status}`);
     try {
         return (await res.json());
     }
     catch {
-        throw new RegistryError(url, "the registry's answer was not JSON");
+        throw new RegistryError(url, "the registry's answer isn't JSON");
     }
 }
 /** `{ latest: "0.81.0", next: "0.82.0-rc.1" }`. */
 export async function fetchDistTags(o) {
-    const url = registryUrl(o.registry, "-", "package", o.packageName, "dist-tags");
-    const body = await getJson(url, o);
+    const url = registryUrl(o.registry, '-', 'package', o.packageName, 'dist-tags');
     const tags = {};
-    for (const [k, v] of Object.entries(body))
-        if (typeof v === "string")
+    for (const [k, v] of Object.entries(await getJson(url, o)))
+        if (typeof v === 'string')
             tags[k] = v;
     if (Object.keys(tags).length === 0)
-        throw new RegistryError(url, "the registry listed no dist-tags");
+        throw new RegistryError(url, 'the registry lists no dist-tags');
     return tags;
 }
-/** One version's manifest — read for `engines` (SPEC §5 step 3). */
-export async function fetchManifest(o) {
-    const url = registryUrl(o.registry, o.packageName, o.version);
-    return getJson(url, o);
+/** One version's manifest, read for `engines`. */
+export function fetchManifest(o) {
+    return getJson(registryUrl(o.registry, o.packageName, o.version), o);
 }
 /**
- * Turn `--to` (or its absence) into one concrete version, plus its `engines`.
- *
- * `--to` is a version or a dist-tag and the two are told apart by shape, not by
- * asking: anything that parses as a version is a version, everything else is a
- * tag. That ordering matters because a registry will happily serve a manifest
- * for a tag name as well, and resolving `--to next` as a literal version would
- * silently install whatever `next` pointed at while REPORTING the target as
- * "next".
+ * `--to` (or `latest` without it) as one version, with its `engines`. A version and a tag are told apart by shape:
+ * anything that looks like a version is one. Asking first would be wrong, since a registry may serve a manifest for a
+ * tag's name too, and `--to next` would then install `next` while reporting it as a version called "next".
  */
 export async function resolveTarget(o) {
-    const { to } = o;
+    const to = o.to?.trim();
     let version;
     let tag;
-    if (to === undefined) {
-        const tags = await fetchDistTags(o);
-        const latest = tags.latest;
-        if (latest === undefined) {
-            throw new RegistryError(registryUrl(o.registry, "-", "package", o.packageName, "dist-tags"), "the registry has no `latest` dist-tag for this package");
-        }
-        version = latest;
-        tag = "latest";
-    }
-    else if (/^v?\d+\.\d+\.\d+/.test(to.trim())) {
-        version = to.trim().replace(/^v/, "");
+    if (to !== undefined && /^v?\d+\.\d+\.\d+/.test(to)) {
+        version = to.replace(/^v/, '');
         tag = null;
     }
     else {
+        tag = to ?? 'latest';
         const tags = await fetchDistTags(o);
-        const resolved = tags[to];
+        const resolved = tags[tag];
         if (resolved === undefined) {
-            throw new RegistryError(registryUrl(o.registry, "-", "package", o.packageName, "dist-tags"), `no dist-tag \`${to}\` (the registry has: ${Object.keys(tags).sort().join(", ")})`);
+            const url = registryUrl(o.registry, '-', 'package', o.packageName, 'dist-tags');
+            throw new RegistryError(url, `no dist-tag \`${tag}\` (the registry has: ${Object.keys(tags).sort().join(', ')})`);
         }
         version = resolved;
-        tag = to;
     }
     const manifest = await fetchManifest({ ...o, version });
     return { version, tag, engines: manifest.engines?.node ?? null };