@shardflux/cli 0.15.0 → 0.15.2

package/dist/menubar.js

@@ -1,9 +1,10 @@
-import { execFile } from 'node:child_process';
-import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { execFile, spawn } from 'node:child_process';
+import { chmodSync, closeSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
+import { compareVersions } from '@shardflux/sdk';
 import { AgentStateStore } from "./agent-state.js";
 import { UsageError } from "./errors.js";
 import { json } from "./format.js";
@@ -27,6 +28,61 @@ export function compareBundleVersions(left, right) {
     }
     return 0;
 }
+/**
+ * Marketing versions (CFBundleShortVersionString) compare as semver: 0.3.10 > 0.3.9, 0.4.0-rc.1 < 0.4.0. A version that
+ * is not semver compares as a numeric bundle version.
+ */
+export function compareAppVersions(left, right) {
+    return compareVersions(left, right) ?? compareBundleVersions(left, right);
+}
+/**
+ * The first app that swaps itself in when the npm package next to the CLI carries a newer one (it knows when no window
+ * is open and nothing is in progress). The CLI leaves a running app of this version or later to do that itself.
+ */
+export const SELF_UPDATING_APP = '0.3.2';
+/** CFBundleShortVersionString of a Shardflux app from its XML Info.plist, read without any tool (null: not readable). */
+export function plistVersion(app) {
+    try {
+        const text = readFileSync(join(app, 'Contents', 'Info.plist'), 'utf8');
+        const value = (key) => new RegExp(`<key>${key}</key>\\s*<string>([^<]+)</string>`).exec(text)?.[1]?.trim() ?? null;
+        if (value('CFBundleIdentifier') !== BUNDLE_ID)
+            return null;
+        const version = value('CFBundleShortVersionString') ?? value('CFBundleVersion');
+        return version && compareVersions(version, version) !== null ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+const WINDOW_PROBE = `ObjC.import('CoreGraphics');
+function run(argv) {
+  const pids = argv.map(Number);
+  const list = ObjC.deepUnwrap(ObjC.castRefToObject($.CGWindowListCopyWindowInfo($.kCGWindowListOptionOnScreenOnly, $.kCGNullWindowID))) || [];
+  return JSON.stringify(list.filter(w => pids.includes(w.kCGWindowOwnerPID)).map(w => ({ pid: w.kCGWindowOwnerPID, layer: w.kCGWindowLayer,
+    x: w.kCGWindowBounds.X, y: w.kCGWindowBounds.Y, width: w.kCGWindowBounds.Width, height: w.kCGWindowBounds.Height, alpha: w.kCGWindowAlpha })));
+}`;
+/**
+ * Whether any of these processes shows a window: the menu, the launcher, Settings, onboarding, an approval. The status
+ * item itself (a strip at the top of the screen on the status layer, owned by the app before macOS 26) does not count.
+ * Null when the probe could not answer: then nothing may be replaced.
+ */
+export function windowsOpen(text) {
+    let rows;
+    try {
+        rows = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(rows))
+        return null;
+    const windows = rows;
+    if (!windows.every(w => w && typeof w === 'object' && ['layer', 'y', 'width', 'height'].every(k => typeof w[k] === 'number')))
+        return null;
+    // A status item is a strip on the status layer at the top of the screen (39 pt high on a notched display).
+    const statusItem = (w) => w.layer === 25 && w.y <= 0 && w.height <= 50;
+    return windows.some(w => w.layer >= 0 && !statusItem(w) && (w.alpha ?? 1) > 0 && w.width > 1 && w.height > 1);
+}
 export function parseNativeStatus(text) {
     const value = JSON.parse(text);
     if (!value || typeof value !== 'object')
@@ -68,12 +124,10 @@ export class MenubarManager {
         this.#platform = options.platform ?? process.platform;
         this.#run = options.run ?? ((tool, args) => nativeTools.run(tool, args, options.signal));
         this.#packageApp = options.packageApp ?? (() => {
-            try {
-                return join(dirname(createRequire(import.meta.url).resolve('@shardflux/menubar-darwin/package.json')), 'Shardflux.app');
-            }
-            catch {
+            const app = packagedAppPath();
+            if (!app)
                 throw new UsageError('The macOS app package is missing. Reinstall shard with optional dependencies enabled, then run shard menubar start.');
-            }
+            return app;
         });
     }
     get platform() { return this.#platform; }
@@ -86,10 +140,25 @@ export class MenubarManager {
         const id = (await this.#run('/usr/bin/plutil', ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', file])).trim();
         if (id !== BUNDLE_ID || lstatSync(app).isSymbolicLink())
             throw new UsageError(`Refusing to replace an unrelated app at ${app}.`);
+        // The marketing version (0.15.2+), compared as semver; an app without one has its numeric bundle version.
+        const marketing = await this.#run('/usr/bin/plutil', ['-extract', 'CFBundleShortVersionString', 'raw', '-o', '-', file]).then(v => v.trim(), () => '');
+        if (marketing && compareVersions(marketing, marketing) !== null)
+            return marketing;
         const version = (await this.#run('/usr/bin/plutil', ['-extract', 'CFBundleVersion', 'raw', '-o', '-', file])).trim();
         compareBundleVersions(version, version);
         return version;
     }
+    /** Whether the app shows any window (see windowsOpen); null when that could not be read. */
+    async windowsOpen(pids) {
+        if (!pids.length)
+            return false;
+        try {
+            return windowsOpen(await this.#run('/usr/bin/osascript', ['-l', 'JavaScript', '-e', WINDOW_PROBE, ...pids.map(String)]));
+        }
+        catch {
+            return null;
+        }
+    }
     async #control(action, ...args) {
         makeExecutable(this.app);
         return parseNativeStatus(await this.#run(join(this.app, 'Contents', 'MacOS', 'ShardfluxMenuBar'), ['--control', action, ...args]));
@@ -125,46 +194,49 @@ export class MenubarManager {
         await this.#control('login', value);
         return this.status();
     }
-    async start(configDir, apiUrl) {
-        this.#requireMac();
-        const source = this.#packageApp(), sourceVersion = await this.#version(source);
-        const current = await this.status();
-        if (!current.installed || compareBundleVersions(current.version, sourceVersion) < 0) {
-            // Verify the source before stopping or replacing any existing app.
-            await this.#run('/usr/bin/codesign', ['--verify', '--deep', '--strict', source]);
-            mkdirSync(dirname(this.app), { recursive: true });
-            const stage = mkdtempSync(join(dirname(this.app), '.Shardflux-install-'));
-            const staged = join(stage, 'Shardflux.app'), backup = join(stage, 'previous.app');
-            let committed = false, restored = false;
+    /** Replaces the installed app with `source` (verified first), stopping it while it is swapped. */
+    async #install(source, current) {
+        // Verify the source before stopping or replacing any existing app.
+        await this.#run('/usr/bin/codesign', ['--verify', '--deep', '--strict', source]);
+        mkdirSync(dirname(this.app), { recursive: true });
+        const stage = mkdtempSync(join(dirname(this.app), '.Shardflux-install-'));
+        const staged = join(stage, 'Shardflux.app'), backup = join(stage, 'previous.app');
+        let committed = false, restored = false;
+        try {
+            cpSync(source, staged, { recursive: true, dereference: false });
+            if (current.running)
+                await this.stop();
+            if (current.installed)
+                renameSync(this.app, backup);
+            makeExecutable(staged);
             try {
-                cpSync(source, staged, { recursive: true, dereference: false });
-                if (current.running)
-                    await this.stop();
-                if (current.installed)
-                    renameSync(this.app, backup);
-                makeExecutable(staged);
-                try {
-                    renameSync(staged, this.app);
-                    committed = true;
-                }
-                catch (error) {
-                    if (existsSync(backup)) {
-                        try {
-                            renameSync(backup, this.app);
-                            restored = true;
-                        }
-                        catch {
-                            throw new UsageError(`Could not restore the previous app. It is preserved at ${backup}.`);
-                        }
+                renameSync(staged, this.app);
+                committed = true;
+            }
+            catch (error) {
+                if (existsSync(backup)) {
+                    try {
+                        renameSync(backup, this.app);
+                        restored = true;
+                    }
+                    catch {
+                        throw new UsageError(`Could not restore the previous app. It is preserved at ${backup}.`);
                     }
-                    throw error;
                 }
+                throw error;
             }
-            finally {
-                if (committed || restored || !existsSync(backup))
-                    rmSync(stage, { recursive: true, force: true });
-            }
         }
+        finally {
+            if (committed || restored || !existsSync(backup))
+                rmSync(stage, { recursive: true, force: true });
+        }
+    }
+    async start(configDir, apiUrl) {
+        this.#requireMac();
+        const source = this.#packageApp(), sourceVersion = await this.#version(source);
+        const current = await this.status();
+        if (!current.installed || compareAppVersions(current.version, sourceVersion) < 0)
+            await this.#install(source, current);
         await this.#stripQuarantine();
         if (!(await this.status()).running) {
             mkdirSync(configDir, { recursive: true, mode: 0o700 });
@@ -179,6 +251,45 @@ export class MenubarManager {
         }
         throw new UsageError(`Shardflux did not start. Check ${join(configDir, 'menubar.log')}.`);
     }
+    /**
+     * Brings an installed app up to the one this CLI's npm package carries, without disturbing the person: nothing when
+     * the versions are equal (each swap of an ad-hoc signed app costs its privacy grants), the copy on disk alone when it
+     * is not running, and a running app only when it shows no window and no `shard update` runs. A running app that
+     * swaps itself in (SELF_UPDATING_APP or later) is left to do so: it also knows when it is in the middle of something.
+     */
+    async refresh(configDir, apiUrl) {
+        this.#requireMac();
+        const current = await this.status();
+        if (!current.installed || !current.version)
+            return { result: 'not_installed', from: null, to: null };
+        const to = await this.packagedVersion(), from = current.version;
+        if (compareAppVersions(from, to) >= 0)
+            return { result: 'current', from, to };
+        if (current.running) {
+            if (compareAppVersions(from, SELF_UPDATING_APP) >= 0)
+                return { result: 'deferred', from, to };
+            if (updateRunning(configDir) || (await this.windowsOpen(current.pids)) !== false)
+                return { result: 'busy', from, to };
+            await this.start(configDir, apiUrl);
+            return { result: 'restarted', from, to };
+        }
+        await this.#install(this.#packageApp(), current);
+        await this.#stripQuarantine();
+        return { result: 'installed', from, to };
+    }
+}
+/** A `shard update` holds update.lock while it runs (update.ts); a lock of a process that is gone does not count. */
+function updateRunning(dir) {
+    try {
+        const pid = Number(readFileSync(join(dir, 'update.lock'), 'utf8'));
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 /** On macOS, `shard` brings the menu bar up by itself (with launch at login) unless the user ran `shard menubar stop`.
  *  It never fails the command center: a missing optional package or a refused start just leaves it off. */
@@ -190,8 +301,9 @@ export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(),
         return undefined;
     try {
         const status = await manager.status();
-        // A running app stays unless this CLI carries a newer one (after `npm i -g shardflux`): then it is replaced.
-        if (status.running && !(status.version && compareBundleVersions(status.version, await manager.packagedVersion()) < 0))
+        // A running app is brought up to the one this CLI carries (after `npm i -g shardflux`) by the background refresh
+        // every command starts (refreshMenubarInBackground), at a moment when it shows no window.
+        if (status.running)
             return undefined;
         const started = await manager.start(dir, apiUrl);
         if (!started.running)
@@ -204,7 +316,114 @@ export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(),
         return undefined;
     }
 }
-export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].map(action => {
+const REFRESH_MARK = 'menubar-refresh.json';
+const REFRESH_LOCK = 'menubar-refresh.lock';
+/** How often a command may start a background refresh while the app is busy (a window open). */
+export const REFRESH_RETRY_MS = 5 * 60_000;
+/** Where this CLI's npm package keeps the app it carries, or null when the optional package is missing. */
+export function packagedAppPath() {
+    try {
+        return join(dirname(createRequire(import.meta.url).resolve('@shardflux/menubar-darwin/package.json')), 'Shardflux.app');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Every `shard` command (0.15.2+): when the npm package carries a newer app than the installed one (two Info.plist
+ * reads, no network, no tool), `shard menubar refresh` runs detached, so the command never waits for it. It is started
+ * at most every 5 minutes while the app is busy, and not at all after `shard menubar stop`. Returns whether it started.
+ */
+export function refreshMenubarInBackground(o) {
+    try {
+        if ((o.platform ?? process.platform) !== 'darwin')
+            return false;
+        const installed = plistVersion(join(o.home, 'Applications', 'Shardflux.app'));
+        const source = (o.packageApp ?? packagedAppPath)();
+        const packaged = source ? plistVersion(source) : null;
+        if (!installed || !packaged || compareAppVersions(installed, packaged) >= 0)
+            return false;
+        if (new AgentStateStore(o.dir).read().menubar_stopped === true)
+            return false;
+        const now = (o.now ?? Date.now)(), mark = join(o.dir, REFRESH_MARK);
+        try {
+            const last = JSON.parse(readFileSync(mark, 'utf8'));
+            if (last.to === packaged && typeof last.at === 'number' && now - last.at < REFRESH_RETRY_MS && last.at <= now)
+                return false;
+        }
+        catch { /* never started */ }
+        mkdirSync(o.dir, { recursive: true, mode: 0o700 });
+        const fd = openSync(mark, 'w', 0o600);
+        try {
+            writeSync(fd, `${JSON.stringify({ at: now, from: installed, to: packaged })}\n`);
+        }
+        finally {
+            closeSync(fd);
+        }
+        const env = { ...o.env, SHARDFLUX_CONFIG_DIR: o.dir, SHARDFLUX_NO_UPDATE_CHECK: '1' };
+        (o.spawn ?? spawnDetached)(o.runtime.node, [o.runtime.script, 'menubar', 'refresh'], env);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function spawnDetached(node, args, env) {
+    const child = spawn(node, args, { detached: true, stdio: 'ignore', env });
+    child.on('error', () => undefined);
+    child.unref();
+}
+/** One refresh at a time per config directory; the lock of a process that is gone is taken over. */
+function refreshLock(dir) {
+    const file = join(dir, REFRESH_LOCK);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(file, 'wx', 0o600);
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => rmSync(file, { force: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                return null;
+            let alive = false;
+            try {
+                const pid = Number(readFileSync(file, 'utf8'));
+                if (Number.isInteger(pid) && pid > 0) {
+                    process.kill(pid, 0);
+                    alive = true;
+                }
+            }
+            catch { /* gone */ }
+            if (alive)
+                return null;
+            rmSync(file, { force: true });
+        }
+    }
+    return null;
+}
+/** `shard menubar refresh` (not listed in help, so not in HANDLERS): what refreshMenubarInBackground starts. */
+export const runMenubarRefresh = async (ctx) => {
+    const manager = new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal });
+    let outcome;
+    if (new AgentStateStore(ctx.store.dir).read().menubar_stopped === true)
+        outcome = { result: 'off', from: null, to: null };
+    else {
+        const unlock = refreshLock(ctx.store.dir);
+        if (!unlock)
+            outcome = { result: 'locked', from: null, to: null };
+        else
+            try {
+                outcome = await manager.refresh(ctx.store.dir, ctx.apiUrl);
+            }
+            finally {
+                unlock();
+            }
+    }
+    ctx.io.stdout.write(ctx.json ? json(outcome) : `Menu bar: ${outcome.result}${outcome.from ? ` · app ${outcome.from}${outcome.to && outcome.to !== outcome.from ? ` → ${outcome.to}` : ''}` : ''}\n`);
+    return 0;
+};
+export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].map((action) => {
     const handler = async (ctx, values) => {
         if (values.login !== undefined && !['on', 'off'].includes(String(values.login)))
             throw new UsageError('--login must be on or off.');

package/dist/registry.d.ts

@@ -0,0 +1,48 @@
+export declare const NPM_REGISTRY = "https://registry.npmjs.org";
+/** Each registry request's timeout (ms). */
+export declare const REGISTRY_TIMEOUT_MS = 3000;
+/** The npm packages whose versions `shard update` compares. */
+export declare const NPM_CLIENTS: readonly ["shardflux", "@shardflux/cli", "@shardflux/sdk", "@shardflux/mcp", "@shardflux/menubar-darwin"];
+export interface RegistryAnswer {
+    latest: string | null;
+    /** The registry's validator for the next request (npm's dist-tags endpoint sends none today). */
+    etag: string | null;
+    /** 304: what the caller cached under `etag` is still current. */
+    notModified: boolean;
+}
+export interface RegistryOptions {
+    fetch: typeof fetch;
+    /** Default https://registry.npmjs.org (SHARDFLUX_NPM_REGISTRY overrides it for the CLI). */
+    registry?: string;
+    etag?: string | null;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    userAgent?: string;
+}
+/** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
+export declare function npmRegistry(env: Record<string, string | undefined>): string;
+/** `latest` of an npm package from `<registry>/-/package/<name>/dist-tags`, or null when the registry did not answer. */
+export declare function npmLatest(pkg: string, opts: RegistryOptions): Promise<RegistryAnswer | null>;
+/** `latest` of every package in `packages`, asked in parallel; a package the registry did not answer is absent. */
+export declare function npmLatestAll(packages: readonly string[], opts: RegistryOptions): Promise<Record<string, string>>;
+export interface CatalogEntry {
+    package: string;
+    ecosystem: string;
+    latest: string | null;
+    minimum_supported: string | null;
+    upgrade_command: string | null;
+    release_notes_url: string | null;
+    hold?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * A GET /v1/client-versions body whose npm entries carry the registry's `latest` (`registry`: package -> version; an
+ * absent package keeps the catalog's). Works with every catalog shape the API has served: no `hold` field, `latest`
+ * null, a package missing from the list, or no catalog at all (`catalog` null: the API did not answer).
+ *
+ * `hold`: when the registry's latest is that version, it is not recommended; the catalog's own `latest` is, when it is
+ * older, else `minimum_supported` (so "no longer supported" still works and nobody is told to update).
+ */
+export declare function withRegistryLatest(catalog: unknown, registry: Record<string, string | null | undefined>): {
+    clients: CatalogEntry[];
+};

package/dist/registry.js

@@ -0,0 +1,102 @@
+/**
+ * The latest version of each Shardflux client comes from its registry (0.15.2+), so a release is known the moment it
+ * is published: npm's `latest` dist-tag, which is what `npm i -g shardflux` and `shard update` install. (`stable` is an
+ * opt-in tag for installs behind a release-age gate, docs/progress/packaging.md; it never drives the update notice.)
+ *
+ * The API catalog (GET /v1/client-versions) still says which versions it serves (`minimum_supported`) and may name a
+ * version to stop recommending (`hold`, an emergency brake). Its `latest` is only the fallback when the registry does
+ * not answer. Every request here is bounded and never throws: offline means "no answer".
+ */
+import { compareVersions } from '@shardflux/sdk';
+export const NPM_REGISTRY = 'https://registry.npmjs.org';
+/** Each registry request's timeout (ms). */
+export const REGISTRY_TIMEOUT_MS = 3_000;
+/** The npm packages whose versions `shard update` compares. */
+export const NPM_CLIENTS = ['shardflux', '@shardflux/cli', '@shardflux/sdk', '@shardflux/mcp', '@shardflux/menubar-darwin'];
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
+export function npmRegistry(env) {
+    const own = env.SHARDFLUX_NPM_REGISTRY?.trim();
+    return own ? own.replace(/\/+$/, '') : NPM_REGISTRY;
+}
+/** `latest` of an npm package from `<registry>/-/package/<name>/dist-tags`, or null when the registry did not answer. */
+export async function npmLatest(pkg, opts) {
+    try {
+        const timeout = AbortSignal.timeout(opts.timeoutMs ?? REGISTRY_TIMEOUT_MS);
+        const headers = { accept: 'application/json' };
+        if (opts.userAgent)
+            headers['user-agent'] = opts.userAgent;
+        if (opts.etag)
+            headers['if-none-match'] = opts.etag;
+        const res = await opts.fetch(`${(opts.registry ?? NPM_REGISTRY).replace(/\/+$/, '')}/-/package/${encodeURIComponent(pkg)}/dist-tags`, {
+            method: 'GET',
+            headers,
+            signal: opts.signal ? AbortSignal.any([timeout, opts.signal]) : timeout,
+        });
+        const etag = res.headers.get('etag');
+        if (res.status === 304) {
+            await res.body?.cancel().catch(() => undefined);
+            return { latest: null, etag: etag ?? opts.etag ?? null, notModified: true };
+        }
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => undefined);
+            return null;
+        }
+        const body = JSON.parse(await res.text());
+        const latest = isObj(body) ? str(body.latest) : null;
+        // A tag that is not a version (a broken registry mirror) is no answer.
+        if (latest === null || compareVersions(latest, latest) === null)
+            return null;
+        return { latest, etag, notModified: false };
+    }
+    catch {
+        return null;
+    }
+}
+/** `latest` of every package in `packages`, asked in parallel; a package the registry did not answer is absent. */
+export async function npmLatestAll(packages, opts) {
+    const answers = await Promise.all(packages.map(async (pkg) => [pkg, await npmLatest(pkg, { ...opts, etag: null })]));
+    return Object.fromEntries(answers.flatMap(([pkg, a]) => (a?.latest ? [[pkg, a.latest]] : [])));
+}
+const DEFAULT_UPGRADE = {
+    shardflux: 'npm i -g shardflux',
+    '@shardflux/cli': 'npm i -g shardflux',
+    '@shardflux/menubar-darwin': 'shard update',
+};
+/**
+ * A GET /v1/client-versions body whose npm entries carry the registry's `latest` (`registry`: package -> version; an
+ * absent package keeps the catalog's). Works with every catalog shape the API has served: no `hold` field, `latest`
+ * null, a package missing from the list, or no catalog at all (`catalog` null: the API did not answer).
+ *
+ * `hold`: when the registry's latest is that version, it is not recommended; the catalog's own `latest` is, when it is
+ * older, else `minimum_supported` (so "no longer supported" still works and nobody is told to update).
+ */
+export function withRegistryLatest(catalog, registry) {
+    const listed = isObj(catalog) && Array.isArray(catalog.clients) ? catalog.clients.filter(isObj) : [];
+    const entries = listed.map((c) => ({
+        ...c,
+        package: String(c.package),
+        ecosystem: String(c.ecosystem),
+        latest: str(c.latest),
+        minimum_supported: str(c.minimum_supported),
+        upgrade_command: str(c.upgrade_command),
+        release_notes_url: str(c.release_notes_url),
+        hold: str(c.hold),
+    }));
+    for (const pkg of Object.keys(registry)) {
+        if (!entries.some((e) => e.ecosystem === 'npm' && e.package === pkg)) {
+            entries.push({ package: pkg, ecosystem: 'npm', latest: null, minimum_supported: null, upgrade_command: DEFAULT_UPGRADE[pkg] ?? null, release_notes_url: `https://www.npmjs.com/package/${pkg}?activeTab=versions`, hold: null });
+        }
+    }
+    return {
+        clients: entries.map((e) => {
+            const fromRegistry = e.ecosystem === 'npm' ? str(registry[e.package]) : null;
+            let latest = fromRegistry ?? e.latest;
+            if (latest !== null && e.hold && compareVersions(latest, e.hold) === 0) {
+                latest = e.latest !== null && compareVersions(e.latest, e.hold) === -1 ? e.latest : e.minimum_supported;
+            }
+            return { ...e, latest };
+        }),
+    };
+}

package/dist/update-check.d.ts

@@ -11,10 +11,16 @@ export interface Distribution {
 export declare const CLI_DISTRIBUTION: Distribution;
 interface CacheEntry {
     checked_at: string;
+    /** What the notice compares with: the registry's latest, unless the catalog holds it (registry.ts). */
     latest: string | null;
     minimum_supported: string | null;
     upgrade_command: string | null;
     release_notes_url: string | null;
+    /** The catalog's own `latest` and `hold`, and the registry's answer with its ETag (0.15.2+). */
+    catalog_latest?: string | null;
+    hold?: string | null;
+    registry_latest?: string | null;
+    registry_etag?: string | null;
 }
 /** The `update` object of `shard version --json`. */
 export interface UpdateView {
@@ -37,6 +43,8 @@ export interface UpdateCheckOptions {
     distribution: Distribution;
     fetch: typeof fetch;
     userAgent: string;
+    /** The npm registry (default https://registry.npmjs.org). */
+    registry?: string;
     now?: () => number;
 }
 /**
@@ -51,7 +59,7 @@ export declare class UpdateCheck {
         status: ClientVersionStatus;
         checkedAt: string | null;
     } | null;
-    /** Starts the check: from the cache when it is younger than 24 h (unless `force`), else one request. */
+    /** Starts the check: from the cache when it is younger than 12 h (unless `force`), else the registry and the API. */
     start(force?: boolean): void;
     /** The status (with when it was fetched), or null when not started or still running after `waitMs`. */
     result(waitMs: number): Promise<{