@edspencer/paddock 0.82.0 → 0.82.1

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 };

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

@@ -1,67 +1,44 @@
-/**
- * The small semver `update` needs, and no more (CLI contract SPEC §5 step 4).
- *
- * Three questions are asked of versions in this contract: is the target newer
- * than what we have, is it a prerelease, and does the target's `engines.node`
- * accept the Node running the update. That is it — so this is ~120 lines of
- * Node built-ins rather than a dependency, which is what SPEC §5 asks for and
- * what keeps `update` runnable from a CLI that must not load the server.
- *
- * **What it deliberately does not do.** No `semver` package behaviours beyond
- * the above: no ranges with hyphens (`1.2 - 2.3`), no `x`-ranges (`1.x`), no
- * build metadata ordering. An `engines.node` we cannot parse is reported as
- * "cannot tell" rather than as "fails", because refusing an update on the
- * strength of a range this file does not understand would be the worse error of
- * the two — see {@link satisfiesEngines}.
- *
- * Generic: wave C4 lifts this into `reference/` with the rest of `update`.
- */
 export interface Version {
     major: number;
     minor: number;
     patch: number;
-    /** The dot-separated identifiers after `-`, empty for a release. */
+    /** The dot-separated identifiers after `-`; empty for a release. */
     prerelease: (string | number)[];
 }
-/** `1.2.3-rc.1` → a {@link Version}, or undefined if it is not a version. */
+/** `1.2.3-rc.1` as a `Version`, or undefined if it isn't one. */
 export declare function parseVersion(raw: string): Version | undefined;
-/** Is this a prerelease? SPEC §5: prereleases count only when `--to` names them. */
+/** SPEC §5: prereleases count only when `--to` names them. */
 export declare function isPrerelease(raw: string): boolean;
 /**
- * -1, 0 or 1, by the semver rules — including the prerelease ones, which are
- * the only interesting part: `1.0.0-rc.1` is LOWER than `1.0.0`, numeric
- * identifiers compare numerically and sort below alphanumeric ones, and a
- * longer run of identifiers wins when every shared one is equal.
- *
- * Build metadata is ignored, as semver says it must be.
+ * -1, 0 or 1, by semver's rules: `1.0.0-rc.1` is lower than `1.0.0`, numeric identifiers compare as numbers and sort
+ * below alphanumeric ones, and a longer run of identifiers wins when the shared ones are equal. Build metadata is
+ * ignored. Something that isn't a version compares as equal rather than throwing.
  */
 export declare function compareVersions(a: string, b: string): number;
-/** Is `a` strictly newer than `b`? */
+/** Whether `a` is strictly newer than `b`. */
 export declare const isNewer: (a: string, b: string) => boolean;
-/** The highest of a list, ignoring anything unparseable. Undefined if none parse. */
+/** The highest of a list, ignoring anything that isn't a version. */
 export declare function maxVersion(versions: readonly string[]): string | undefined;
+/** `0.82.0` → `0.83.0` (`minor`), or `0.82.1` (`patch`). A prerelease's suffix is dropped. */
+export declare function bumpVersion(raw: string, part: 'major' | 'minor' | 'patch'): string;
 /**
- * Does `version` satisfy `range`? Undefined means "this file cannot tell".
+ * Whether `version` satisfies `range`; undefined when this file can't tell.
  *
- * Supports the forms an `engines.node` actually uses: `>=22`, `>=22.0.0`,
- * `^22.1.0`, `~22.1`, `22`, `22.x`, `>=20 <23`, and `||` between any of those.
- * `*` and an empty range accept everything.
+ * Reads what `engines.node` uses in practice: `>=22`, `>=22.0.0`, `^22.1.0`, `~22.1`, `22`, `22.x`, `>=20 <23`, and
+ * `||` between them. `*` and an empty range accept everything. Alternatives it can't read are ignored; if it can read
+ * none of them, the answer is undefined.
  */
 export declare function satisfies(version: string, range: string): boolean | undefined;
 export interface EnginesVerdict {
-    /** True pass, false genuine fail, undefined when the range could not be read. */
+    /** true passes, false fails, undefined when the range couldn't be read. */
     ok: boolean | undefined;
     /** The range as published, for the message. */
     range: string | undefined;
 }
 /**
- * Will the target version run on this Node? (SPEC §5 step 4.)
- *
- * The three-way answer is the point. A target with no `engines.node` at all, or
- * one whose range this file cannot parse, must NOT block an update: the cost of
- * a false refusal is a tool that cannot update itself and says something the
- * user cannot act on, while the cost of letting an incompatible Node through is
- * the failure `engines` would have produced anyway, with a rollback behind it.
+ * Will the target run on this Node? (SPEC §5 step 4.) No `engines.node`, or one this file can't read, doesn't block
+ * an update: callers treat `ok: undefined` as a pass. A false refusal leaves a tool that can't update itself, saying
+ * something nobody can act on; letting an unsuitable Node through fails the install, and the rollback runs.
  */
 export declare function satisfiesEngines(nodeVersion: string, engines: {
     node?: string;