@edspencer/paddock 0.82.0 → 0.83.0

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;

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

@@ -1,53 +1,37 @@
-/**
- * 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`.
- */
+// From edspencer/cli-contract reference/semver.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// The small semver `update` needs (SPEC §5 step 4): is the target newer, is it a prerelease, and does its
+// `engines.node` accept this Node. Node built-ins only.
+//
+// It deliberately leaves out hyphen ranges (`1.2 - 2.3`) and build-metadata ordering. A range it can't read is
+// "can't tell" (undefined), not "fails": refusing an update over a range this file doesn't understand would be the
+// worse mistake of the two (`satisfiesEngines`).
 const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/;
-/** `1.2.3-rc.1` → a {@link Version}, or undefined if it is not a version. */
+const identifiers = (s) => s.split('.').map((id) => (/^\d+$/.test(id) ? Number(id) : id));
+/** `1.2.3-rc.1` as a `Version`, or undefined if it isn't one. */
 export function parseVersion(raw) {
     const m = VERSION_RE.exec(raw.trim());
     if (m === null)
         return undefined;
-    const prerelease = m[4] === undefined
-        ? []
-        : m[4].split(".").map((id) => (/^\d+$/.test(id) ? Number(id) : id));
-    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), prerelease };
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), prerelease: m[4] === undefined ? [] : identifiers(m[4]) };
 }
-/** Is this a prerelease? SPEC §5: prereleases count only when `--to` names them. */
+/** SPEC §5: prereleases count only when `--to` names them. */
 export function isPrerelease(raw) {
     return (parseVersion(raw)?.prerelease.length ?? 0) > 0;
 }
 /**
- * -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 function compareVersions(a, b) {
     const va = parseVersion(a);
     const vb = parseVersion(b);
-    // Unparseable compares as equal rather than throwing: the callers all have a
-    // better answer for "I cannot tell" than a crash (`update` says the registry
-    // gave it something it did not understand, and stops).
     if (va === undefined || vb === undefined)
         return 0;
-    for (const k of ["major", "minor", "patch"]) {
+    return compare(va, vb);
+}
+function compare(va, vb) {
+    for (const k of ['major', 'minor', 'patch']) {
         if (va[k] !== vb[k])
             return va[k] < vb[k] ? -1 : 1;
     }
@@ -67,137 +51,109 @@ export function compareVersions(a, b) {
             return 1;
         if (x === y)
             continue;
-        const xNum = typeof x === "number";
-        const yNum = typeof y === "number";
-        if (xNum && yNum)
+        if (typeof x === 'number' && typeof y === 'number')
             return x < y ? -1 : 1;
-        if (xNum)
+        if (typeof x === 'number')
             return -1;
-        if (yNum)
+        if (typeof y === 'number')
             return 1;
-        return String(x) < String(y) ? -1 : 1;
+        return x < y ? -1 : 1;
     }
     return 0;
 }
-/** Is `a` strictly newer than `b`? */
+/** Whether `a` is strictly newer than `b`. */
 export const isNewer = (a, b) => compareVersions(a, b) > 0;
-/** 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 function maxVersion(versions) {
     let best;
     for (const v of versions) {
-        if (parseVersion(v) === undefined)
-            continue;
-        if (best === undefined || isNewer(v, best))
+        if (parseVersion(v) !== undefined && (best === undefined || isNewer(v, best)))
             best = v;
     }
     return best;
 }
+/** `0.82.0` → `0.83.0` (`minor`), or `0.82.1` (`patch`). A prerelease's suffix is dropped. */
+export function bumpVersion(raw, part) {
+    const v = parseVersion(raw);
+    if (v === undefined)
+        throw new Error(`not a version: ${raw}`);
+    if (part === 'major')
+        return `${v.major + 1}.0.0`;
+    if (part === 'minor')
+        return `${v.major}.${v.minor + 1}.0`;
+    return `${v.major}.${v.minor}.${v.patch + 1}`;
+}
 const COMPARATOR_RE = /^(>=|<=|>|<|=|\^|~)?\s*v?(\d+)(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-([0-9A-Za-z.-]+))?$/;
 /**
- * Expand one range atom into the comparators it means.
- *
- * `^22.1.0` is `>=22.1.0 <23.0.0`; `~22.1.0` is `>=22.1.0 <22.2.0`; a bare
- * `22` is `>=22.0.0 <23.0.0` (npm's partial-version semantics, which is what
- * `engines: { node: "22" }` means in the wild). Returns undefined for anything
- * this file does not understand, which propagates up as "cannot tell".
+ * One range atom as the comparators it means: `^22.1.0` is `>=22.1.0 <23.0.0`, `~22.1.0` is `>=22.1.0 <22.2.0`, and
+ * a bare `22` is `>=22.0.0 <23.0.0` (npm's partial versions). Undefined for anything else.
  */
 function comparatorsFor(atom) {
     const m = COMPARATOR_RE.exec(atom);
     if (m === null)
         return undefined;
-    const op = m[1] ?? "=";
+    const op = m[1] ?? '=';
+    const wild = (s) => s === undefined || s === 'x' || s === 'X' || s === '*';
     const major = Number(m[2]);
-    const wild = (s) => s === undefined || s === "x" || s === "X" || s === "*";
     const minorWild = wild(m[3]);
     const patchWild = wild(m[4]);
     const minor = minorWild ? 0 : Number(m[3]);
     const patch = patchWild ? 0 : Number(m[4]);
-    const prerelease = m[5] === undefined ? [] : m[5].split(".").map((id) => (/^\d+$/.test(id) ? Number(id) : id));
-    const at = (ma, mi, pa) => ({
-        major: ma,
-        minor: mi,
-        patch: pa,
-        prerelease: [],
-    });
-    const lower = { major, minor, patch, prerelease };
-    if (op === "^") {
-        // `^0.x` tightens: ^0.2.3 is >=0.2.3 <0.3.0, ^0.0.3 is >=0.0.3 <0.0.4.
-        const upper = major > 0
-            ? at(major + 1, 0, 0)
-            : minor > 0 || !minorWild
-                ? at(0, minor + 1, 0)
-                : at(1, 0, 0);
-        return [
-            { op: ">=", version: lower },
-            { op: "<", version: upper },
-        ];
-    }
-    if (op === "~") {
-        const upper = minorWild ? at(major + 1, 0, 0) : at(major, minor + 1, 0);
-        return [
-            { op: ">=", version: lower },
-            { op: "<", version: upper },
-        ];
-    }
-    if (op === "=" && (minorWild || patchWild)) {
-        // A partial version with no operator is a range, not an equality: `22`
-        // means the whole 22 line, and `22.1` means the whole 22.1 line.
-        const upper = minorWild ? at(major + 1, 0, 0) : at(major, minor + 1, 0);
-        return [
-            { op: ">=", version: lower },
-            { op: "<", version: upper },
-        ];
-    }
-    if (minorWild || patchWild) {
-        // `>=22` / `<23`: fill the missing parts with zero, which is what the
-        // comparison wants in both directions.
-        return [{ op: op, version: lower }];
+    const at = (ma, mi, pa) => ({ major: ma, minor: mi, patch: pa, prerelease: [] });
+    const lower = { major, minor, patch, prerelease: m[5] === undefined ? [] : identifiers(m[5]) };
+    const between = (upper) => [
+        { op: '>=', version: lower },
+        { op: '<', version: upper },
+    ];
+    // `^0.x` tightens: ^0.2.3 is >=0.2.3 <0.3.0, ^0.0.3 is >=0.0.3 <0.0.4, ^0.0 is <0.1.0 and ^0 is <1.0.0.
+    if (op === '^') {
+        if (major > 0 || minorWild)
+            return between(at(major + 1, 0, 0));
+        if (minor > 0 || patchWild)
+            return between(at(0, minor + 1, 0));
+        return between(at(0, 0, patch + 1));
     }
+    if (op === '~')
+        return between(minorWild ? at(major + 1, 0, 0) : at(major, minor + 1, 0));
+    // A partial version with no operator is a range: `22` is the whole 22 line, `22.1` the whole 22.1 line.
+    if (op === '=' && (minorWild || patchWild))
+        return between(minorWild ? at(major + 1, 0, 0) : at(major, minor + 1, 0));
     return [{ op: op, version: lower }];
 }
 function satisfiesComparator(v, c) {
     const cmp = compare(v, c.version);
     switch (c.op) {
-        case ">=":
+        case '>=':
             return cmp >= 0;
-        case "<=":
+        case '<=':
             return cmp <= 0;
-        case ">":
+        case '>':
             return cmp > 0;
-        case "<":
+        case '<':
             return cmp < 0;
-        case "=":
+        case '=':
             return cmp === 0;
     }
 }
-function compare(a, b) {
-    return compareVersions(stringify(a), stringify(b));
-}
-function stringify(v) {
-    const base = `${v.major}.${v.minor}.${v.patch}`;
-    return v.prerelease.length === 0 ? base : `${base}-${v.prerelease.join(".")}`;
-}
 /**
- * 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 function satisfies(version, range) {
     const v = parseVersion(version);
     if (v === undefined)
         return undefined;
     const trimmed = range.trim();
-    if (trimmed === "" || trimmed === "*" || trimmed === "x")
+    if (trimmed === '' || trimmed === '*' || trimmed === 'x')
         return true;
-    const alternatives = trimmed.split("||");
     let known = false;
-    for (const alt of alternatives) {
-        const atoms = alt.trim().split(/\s+/).filter(Boolean);
+    for (const alt of trimmed.split('||')) {
         const comparators = [];
         let parsed = true;
-        for (const atom of atoms) {
+        for (const atom of alt.trim().split(/\s+/).filter(Boolean)) {
             const cs = comparatorsFor(atom);
             if (cs === undefined) {
                 parsed = false;
@@ -211,22 +167,16 @@ export function satisfies(version, range) {
         if (comparators.every((c) => satisfiesComparator(v, c)))
             return true;
     }
-    // Every alternative we could read said no. If we could read none of them, say
-    // so rather than claiming a refusal.
     return known ? false : 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 function satisfiesEngines(nodeVersion, engines) {
     const range = engines?.node;
-    if (range === undefined || range.trim() === "")
+    if (range === undefined || range.trim() === '')
         return { ok: true, range: undefined };
     return { ok: satisfies(nodeVersion, range), range };
 }

package/packages/server/dist/cli/update/update-check.d.ts

@@ -1,7 +1,7 @@
-import type { InstallMethod } from "./install-method.js";
+import type { InstallMethod } from './install-method.js';
 export declare const UPDATE_CHECK_FILE = "update-check.json";
 export declare function updateCheckPath(home: string): string;
-/** `update --check --json`, and the cached copy. Matches `schemas/update-check.schema.json`. */
+/** `update --check --json`, and the cached copy. */
 export interface UpdateCheck {
     name: string;
     current: string;
@@ -11,7 +11,7 @@ export interface UpdateCheck {
     updateAvailable: boolean;
     installMethod: InstallMethod;
     canUpdate: boolean;
-    /** `<tool> update`, or the command this install needs instead. */
+    /** `<tool> update`, or the command this install needs instead; null once there's nothing to do. */
     command: string | null;
     engines: string | null;
     nodeOk: boolean;
@@ -19,62 +19,51 @@ export interface UpdateCheck {
     /** ISO 8601. */
     checkedAt: string;
 }
-/** What `service status --json` carries (`schemas/service-status.schema.json`). */
+/** `service status --json`'s `update` (`schemas/service-status.schema.json`). */
 export interface UpdateSummary {
     latest: string;
     updateAvailable: boolean;
     checkedAt: string;
 }
 /**
- * Write the cache atomically.
- *
- * Atomic because `service status` reads it on a path where a torn read has no
- * recovery worth having — it would report `updateAvailable` as absent and say
- * nothing, which is indistinguishable from "never checked". Best-effort:
- * failing to write a cache must never fail an update, so this throws nothing.
+ * Writes the cache atomically, so `status` never reads half a file and says nothing. It never throws: a cache that
+ * couldn't be written isn't a failed update.
  */
 export declare function writeUpdateCheck(home: string, check: UpdateCheck): void;
 /** The cache, or null when there isn't one (or it isn't one). */
 export declare function readUpdateCheck(home: string): UpdateCheck | null;
 /**
- * How long a cached answer is worth repeating.
- *
- * `status` says "0.81.0 is available" on the strength of a file, so the file
- * has to be recent enough that the claim is still likely true. A week is long
- * enough to cover "I checked on Monday, it is Friday" and short enough that a
- * months-old file does not have `status` advertising a version that has since
- * been superseded twice.
+ * How long a cached answer is worth repeating: long enough for "I checked on Monday, it's Friday", short enough that
+ * `status` doesn't advertise a version that's since been superseded twice.
  */
 export declare const UPDATE_CHECK_MAX_AGE_MS: number;
 /**
- * The summary `service status` shows, or undefined when there is nothing worth
- * repeating: no cache, a cache from a different install, or one too old.
+ * What `service status` repeats, or undefined when there's nothing worth repeating: no cache, a cache for another
+ * version than this one, or one that's too old. Leave `update` out of `status --json` then: the schema types it as an
+ * object, so it's absent, never null.
  */
 export declare function updateSummary(home: string, o?: {
     now?: number;
     maxAgeMs?: number;
+    currentVersion?: string;
 }): UpdateSummary | undefined;
 export interface NoticeInput {
     name: string;
     current: string;
     target: string;
-    /** `paddock update`, or the command this install needs instead (SPEC §3, §6). */
+    /** `<tool> update`, or the command this install needs instead. */
     command: string;
-    /** The parenthetical after the command: `the global folder isn't writable`. */
+    /** What goes in brackets after it: `the global folder isn't writable`. */
     note?: string;
     changelog?: string | null;
 }
 /**
- * SPEC §3's update notice, verbatim in shape:
+ * SPEC §3's notice, for the caller to put on stderr:
  *
  * ```
  * Paddock 0.80.0 is available (you have 0.79.1).
  *   Run: paddock update
  *   Changes: https://github.com/edspencer/paddock/releases/tag/v0.80.0
  * ```
- *
- * Returned as a string rather than printed, because the caller decides the
- * stream: §3 puts this on **stderr**, always, so that a `--json` document on
- * stdout stays the only thing on stdout.
  */
 export declare function updateNotice(o: NoticeInput): string;

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

@@ -1,33 +1,17 @@
-/**
- * `<home>/update-check.json` — what the last registry question found
- * (CLI contract SPEC §3).
- *
- * The contract's rule is that **nothing contacts the registry by itself**: only
- * `update`, `update --check` and `doctor` ask, and only when a person runs
- * them. But `service status` should still be able to mention a newer version,
- * because that is where someone looks. The cache is how both hold: the three
- * commands that ask write what they found here, and `status` reads the file and
- * never opens a socket.
- *
- * The document is the one `schemas/update-check.schema.json` describes, so
- * `update --check --json` and this file are the same shape — one less thing to
- * keep in step, and `status --json`'s `update` object is a projection of it.
- *
- * Generic: wave C4 lifts this into `reference/`. Node built-ins only.
- */
-import fs from "node:fs";
-import path from "node:path";
-export const UPDATE_CHECK_FILE = "update-check.json";
+// From edspencer/cli-contract reference/update-check.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
+// `<home>/update-check.json`: what the last registry question found (SPEC §3). Only `update`, `update --check` and
+// `doctor` ask the registry; they write the answer here, and `service status` repeats it without opening a socket.
+// It's the document `update --check --json` prints (`schemas/update-check.schema.json`), and `service status --json`'s
+// `update` is a projection of it. Node built-ins only.
+import fs from 'node:fs';
+import path from 'node:path';
+export const UPDATE_CHECK_FILE = 'update-check.json';
 export function updateCheckPath(home) {
     return path.join(home, UPDATE_CHECK_FILE);
 }
 /**
- * Write the cache atomically.
- *
- * Atomic because `service status` reads it on a path where a torn read has no
- * recovery worth having — it would report `updateAvailable` as absent and say
- * nothing, which is indistinguishable from "never checked". Best-effort:
- * failing to write a cache must never fail an update, so this throws nothing.
+ * Writes the cache atomically, so `status` never reads half a file and says nothing. It never throws: a cache that
+ * couldn't be written isn't a failed update.
  */
 export function writeUpdateCheck(home, check) {
     try {
@@ -44,73 +28,59 @@ export function writeUpdateCheck(home, check) {
         }
     }
     catch {
-        /* a cache that could not be written is not a failed update */
+        // best effort
     }
 }
 /** The cache, or null when there isn't one (or it isn't one). */
 export function readUpdateCheck(home) {
     try {
-        const raw = JSON.parse(fs.readFileSync(updateCheckPath(home), "utf8"));
-        if (typeof raw.name === "string" &&
-            typeof raw.current === "string" &&
-            typeof raw.target === "string" &&
-            typeof raw.updateAvailable === "boolean" &&
-            typeof raw.checkedAt === "string") {
+        const raw = JSON.parse(fs.readFileSync(updateCheckPath(home), 'utf8'));
+        if (typeof raw.name === 'string' &&
+            typeof raw.current === 'string' &&
+            typeof raw.target === 'string' &&
+            typeof raw.updateAvailable === 'boolean' &&
+            typeof raw.checkedAt === 'string') {
             return raw;
         }
     }
     catch {
-        /* missing, half-written, or from something else */
+        // missing, half-written, or something else's
     }
     return null;
 }
 /**
- * How long a cached answer is worth repeating.
- *
- * `status` says "0.81.0 is available" on the strength of a file, so the file
- * has to be recent enough that the claim is still likely true. A week is long
- * enough to cover "I checked on Monday, it is Friday" and short enough that a
- * months-old file does not have `status` advertising a version that has since
- * been superseded twice.
+ * How long a cached answer is worth repeating: long enough for "I checked on Monday, it's Friday", short enough that
+ * `status` doesn't advertise a version that's since been superseded twice.
  */
 export const UPDATE_CHECK_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 /**
- * The summary `service status` shows, or undefined when there is nothing worth
- * repeating: no cache, a cache from a different install, or one too old.
+ * What `service status` repeats, or undefined when there's nothing worth repeating: no cache, a cache for another
+ * version than this one, or one that's too old. Leave `update` out of `status --json` then: the schema types it as an
+ * object, so it's absent, never null.
  */
 export function updateSummary(home, o = {}) {
     const check = readUpdateCheck(home);
     if (check === null)
         return undefined;
-    const at = Date.parse(check.checkedAt);
-    if (!Number.isFinite(at))
+    if (o.currentVersion !== undefined && check.current !== o.currentVersion)
         return undefined;
-    const age = (o.now ?? Date.now()) - at;
-    if (age > (o.maxAgeMs ?? UPDATE_CHECK_MAX_AGE_MS))
+    const at = Date.parse(check.checkedAt);
+    if (!Number.isFinite(at) || (o.now ?? Date.now()) - at > (o.maxAgeMs ?? UPDATE_CHECK_MAX_AGE_MS))
         return undefined;
-    return {
-        latest: check.target,
-        updateAvailable: check.updateAvailable,
-        checkedAt: check.checkedAt,
-    };
+    return { latest: check.target, updateAvailable: check.updateAvailable, checkedAt: check.checkedAt };
 }
 /**
- * SPEC §3's update notice, verbatim in shape:
+ * SPEC §3's notice, for the caller to put on stderr:
  *
  * ```
  * Paddock 0.80.0 is available (you have 0.79.1).
  *   Run: paddock update
  *   Changes: https://github.com/edspencer/paddock/releases/tag/v0.80.0
  * ```
- *
- * Returned as a string rather than printed, because the caller decides the
- * stream: §3 puts this on **stderr**, always, so that a `--json` document on
- * stdout stays the only thing on stdout.
  */
 export function updateNotice(o) {
-    const lines = [`${o.name} ${o.target} is available (you have ${o.current}).`];
-    lines.push(`  Run: ${o.command}${o.note !== undefined ? `    (${o.note})` : ""}`);
+    const lines = [`${o.name} ${o.target} is available (you have ${o.current}).`, `  Run: ${o.command}${o.note !== undefined ? `    (${o.note})` : ''}`];
     if (o.changelog !== undefined && o.changelog !== null)
         lines.push(`  Changes: ${o.changelog}`);
-    return lines.join("\n");
+    return lines.join('\n');
 }