@gavin-hu/my-pi-agent 0.11.4 → 0.13.0

package/extensions/bytefly/picker/runtime.ts

@@ -7,8 +7,15 @@
  * reads `items()` on every render, so it stays a derived view of this state.
  */
 
-import { getPackageResourcePattern, getResourcePattern } from "./resources.ts";
-import { nextGlobalPackages, nextProjectPackages, nextProjectTopLevelList, nextTopLevelList } from "./toggle.ts";
+import { getDisplayName, getPackageResourcePattern, getResourcePattern } from "./resources.ts";
+import {
+	clearProjectPackages,
+	clearProjectTopLevelList,
+	nextGlobalPackages,
+	nextProjectPackages,
+	nextProjectTopLevelList,
+	nextTopLevelList,
+} from "./toggle.ts";
 import type { Discovery, ResourceItem, SettingsStore, WriteScope } from "./types.ts";
 
 export interface RuntimeDeps {
@@ -26,6 +33,8 @@ export interface ExtensionsPickerRuntime {
 	projectAvailable(): boolean;
 	isDirty(): boolean;
 	toggle(item: ResourceItem): Promise<void>;
+	/** Drop `item`'s project override in Project scope; a no-op when it has none. */
+	clearOverride(item: ResourceItem): Promise<void>;
 	onChange(listener: () => void): () => void;
 }
 
@@ -34,6 +43,11 @@ function storeFor(discovery: Discovery, scope: WriteScope): SettingsStore {
 	return scope === "global" ? discovery.stores.global : discovery.stores.project;
 }
 
+/** Whether two rows name the same resource, for an inherited-state lookup. */
+function sameResource(left: ResourceItem, right: ResourceItem): boolean {
+	return left.metadata.source === right.metadata.source && left.path === right.path;
+}
+
 export function createExtensionsPickerRuntime(deps: RuntimeDeps): ExtensionsPickerRuntime {
 	const { discovery, cwd, agentDir } = deps;
 	let scope: WriteScope = "global";
@@ -72,6 +86,27 @@ export function createExtensionsPickerRuntime(deps: RuntimeDeps): ExtensionsPick
 		store.setProjectPackages(nextProjectPackages(store.packages(), item, enabled, cwd, agentDir));
 	};
 
+	/**
+	 * Drop `item`'s project override, reporting whether anything was written. An
+	 * absent override returns `false` without touching the store, so a stray key
+	 * press cannot dirty the file.
+	 */
+	const clearFromStore = (item: ResourceItem): boolean => {
+		const store = storeFor(discovery, "project");
+		if (item.metadata.origin === "top-level") {
+			const paths = store.projectSettings().extensions ?? [];
+			const next = clearProjectTopLevelList(paths, item, cwd, agentDir);
+			if (next === paths) return false;
+			store.setProjectExtensionPaths(next);
+			return true;
+		}
+		const packages = store.packages();
+		const next = clearProjectPackages(packages, item, cwd, agentDir);
+		if (next === packages) return false;
+		store.setProjectPackages(next);
+		return true;
+	};
+
 	return {
 		scope: () => scope,
 		setScope: (next) => {
@@ -100,6 +135,30 @@ export function createExtensionsPickerRuntime(deps: RuntimeDeps): ExtensionsPick
 			dirty = true;
 			emit();
 		},
+		clearOverride: async (item) => {
+			if (scope !== "project") {
+				deps.onError?.("Overrides are cleared in Project scope; switch with Tab.");
+				return;
+			}
+			const store = storeFor(discovery, "project");
+			try {
+				if (!clearFromStore(item)) {
+					deps.onError?.(`No project override for ${getDisplayName(item)}.`);
+					return;
+				}
+				await store.flush();
+				for (const error of store.drainErrors()) deps.onError?.(error.error.message);
+			} catch (error) {
+				deps.onError?.(error instanceof Error ? error.message : String(error));
+				return;
+			}
+			// With the override gone the row shows the inherited state again; a
+			// project-only resource has no global twin and keeps its value.
+			const inherited = views.global.find((entry) => sameResource(entry, item));
+			if (inherited) item.enabled = inherited.enabled;
+			dirty = true;
+			emit();
+		},
 		onChange: (listener) => {
 			listeners.add(listener);
 			return () => listeners.delete(listener);

package/extensions/bytefly/picker/toggle.ts

@@ -143,3 +143,59 @@ export function nextProjectPackages(
 	}
 	return updated;
 }
+
+/**
+ * Remove the project top-level override a toggle wrote for `item`.
+ *
+ * Drops the `+`/`-` entry for the item's target patterns, and the bare path
+ * entry {@link nextProjectTopLevelList} adds beside it for an inherited personal
+ * resource. Returns `current` unchanged — the same array — when no override is
+ * present, so a caller can tell "nothing to clear" without comparing contents.
+ */
+export function clearProjectTopLevelList(
+	current: string[],
+	item: ResourceItem,
+	cwd: string,
+	agentDir: string,
+): string[] {
+	const inherited = getItemScope(item) === "user";
+	const pattern = inherited ? item.path : getResourcePatternForScope(item, "project", cwd, agentDir);
+	const patterns = getTopLevelOverridePatterns(item, "project", cwd, agentDir);
+	const isOverride = (entry: string): boolean =>
+		(entry.startsWith("!") || entry.startsWith("+") || entry.startsWith("-")) &&
+		patterns.has(getPatternEntryTarget(entry));
+	if (!current.some(isOverride)) return current;
+	return current.filter((entry) => !isOverride(entry) && !(inherited && entry === pattern));
+}
+
+/**
+ * Remove the project package filter a toggle wrote for `item`.
+ *
+ * An entry the toggle created with `autoload: false` is dropped once it holds no
+ * filters, and one that predates the toggle collapses back to its plain source,
+ * mirroring {@link nextProjectPackages}. Returns `packages` unchanged — the same
+ * array — when the item has no project filter.
+ */
+export function clearProjectPackages(
+	packages: PackageSource[],
+	item: ResourceItem,
+	cwd: string,
+	agentDir: string,
+): PackageSource[] {
+	const index = packages.findIndex((entry) =>
+		packageSourceMatches(item, typeof entry === "string" ? entry : entry.source, "project", cwd, agentDir),
+	);
+	const entry = index === -1 ? undefined : packages[index];
+	if (entry === undefined || typeof entry === "string") return packages;
+
+	const pattern = getPackageResourcePattern(item);
+	const filters = entry.extensions ?? [];
+	if (!filters.some((filter) => getPatternEntryTarget(filter) === pattern)) return packages;
+
+	const updated = [...packages];
+	const remaining = filters.filter((filter) => getPatternEntryTarget(filter) !== pattern);
+	if (remaining.length > 0) updated[index] = { ...entry, extensions: remaining };
+	else if (entry.autoload === false) updated.splice(index, 1);
+	else updated[index] = entry.source;
+	return updated;
+}

package/extensions/bytefly/update/cache.ts

@@ -0,0 +1,73 @@
+/**
+ * The published-version answer, cached on disk with the time it was read.
+ *
+ * The check already fires once per session, which leaves two gaps: a session open
+ * for days never re-reads npm, and every new session pays for a request it made
+ * minutes earlier. A timestamp is what fixes the second, so the cache lives in the
+ * agent directory rather than in memory — one entry, one window, shared by every
+ * session that starts inside it.
+ *
+ * A cache can only ever be a miss. An absent, unreadable, or wrong-typed file
+ * reads as `undefined` and the caller fetches; nothing here throws, because a
+ * stale file must never become a session error.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeConfigFile } from "../../../lib/config.ts";
+import { parseVersion } from "./version.ts";
+
+/** The file name under `<agentDir>/bytefly/`. */
+export const UPDATE_CACHE_FILE = "update.json";
+
+/** How long a cached answer is reused before the next session re-reads npm. */
+export const UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** One cached answer: the newest published version and when it was read. */
+export interface UpdateCacheEntry {
+	/** The version npm's `latest` tag pointed at. */
+	latest: string;
+	/** Epoch milliseconds of the read that produced `latest`. */
+	checkedAt: number;
+}
+
+/** Where the cache lives for an agent directory. */
+export function updateCachePath(agentDir: string): string {
+	return join(agentDir, "bytefly", UPDATE_CACHE_FILE);
+}
+
+/** Read the cache; a missing, corrupt, or mistyped entry is `undefined`. */
+export function readUpdateCache(path: string): UpdateCacheEntry | undefined {
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown> | undefined;
+		if (!raw || typeof raw !== "object") return undefined;
+		const latest = typeof raw.latest === "string" ? raw.latest.trim() : "";
+		const checkedAt = typeof raw.checkedAt === "number" && Number.isFinite(raw.checkedAt) ? raw.checkedAt : 0;
+		if (!parseVersion(latest) || checkedAt <= 0) return undefined;
+		return { latest, checkedAt };
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Write the cache atomically (a sibling temp file, then a rename). The caller
+ * treats a throw as a miss: a read-only agent directory must not break a session.
+ */
+export function writeUpdateCache(path: string, entry: UpdateCacheEntry): void {
+	writeConfigFile(path, { latest: entry.latest, checkedAt: entry.checkedAt });
+}
+
+/**
+ * Whether an entry is still inside the window. The boundary is inclusive: an
+ * entry read exactly `ttlMs` ago is reused, so the window never flickers.
+ */
+export function isFresh(
+	entry: UpdateCacheEntry | undefined,
+	now: number,
+	ttlMs: number = UPDATE_CACHE_TTL_MS,
+): boolean {
+	if (!entry) return false;
+	const age = now - entry.checkedAt;
+	return age >= 0 && age <= ttlMs;
+}

package/extensions/bytefly/update/check.ts

@@ -0,0 +1,59 @@
+/**
+ * The one registry read the update check makes.
+ *
+ * A fixed, unauthenticated GET of the published `latest` document for this
+ * package. It is deliberately not `web-access`'s page runner: there are no
+ * redirects to follow, no HTML to extract, and no cache shared with a tool, and
+ * extensions may not import one another. Every failure mode — a non-ok status, a
+ * body that is not JSON, a payload without a real version, a network error, an
+ * abort — resolves to `undefined`, so the caller has one branch and the session
+ * never sees an error from a check nobody asked for.
+ */
+
+import { parseVersion } from "./version.ts";
+
+/** The published document holding the version npm's `latest` tag points at. */
+export const LATEST_VERSION_URL = "https://registry.npmjs.org/@gavin-hu%2Fmy-pi-agent/latest";
+
+/** How long the request may take before it is abandoned. */
+export const UPDATE_TIMEOUT_MS = 5_000;
+
+/** The subset of a `fetch` response this check reads. */
+export interface LatestResponse {
+	readonly ok: boolean;
+	json(): Promise<unknown>;
+}
+
+/** The fetch seam: narrow enough that a test needs no real response object. */
+export type FetchLike = (
+	url: string,
+	init: { signal: AbortSignal; headers: Record<string, string> },
+) => Promise<LatestResponse>;
+
+export interface UpdateCheckDeps {
+	/** Replace the network call; defaults to the platform `fetch`. */
+	fetch?: FetchLike;
+	/** Override {@link UPDATE_TIMEOUT_MS}. */
+	timeoutMs?: number;
+}
+
+/** The latest published version, or `undefined` when it cannot be read. */
+export async function fetchLatestVersion(deps: UpdateCheckDeps = {}): Promise<string | undefined> {
+	const request: FetchLike = deps.fetch ?? ((url, init) => globalThis.fetch(url, init));
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), deps.timeoutMs ?? UPDATE_TIMEOUT_MS);
+	try {
+		const response = await request(LATEST_VERSION_URL, {
+			signal: controller.signal,
+			headers: { accept: "application/json" },
+		});
+		if (!response.ok) return undefined;
+		const body = (await response.json()) as { version?: unknown } | undefined;
+		const version = typeof body?.version === "string" ? body.version.trim() : "";
+		return parseVersion(version) ? version : undefined;
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/extensions/bytefly/update/format.ts

@@ -0,0 +1,87 @@
+/**
+ * Wording for the update check: the header marker, the one transcript notice, and
+ * the answer an explicit re-check prints.
+ *
+ * All three read the same two facts — the version this session loaded and the
+ * version the registry publishes — and none adds a third. The marker is the
+ * shortest honest form (`↑0.12.0`); the notice names the command and the release
+ * URL as text, because the notice renderer has no link support; and the re-check
+ * says what it just found, including the two cases it cannot answer (offline, and
+ * a registry it could not read).
+ */
+
+import pkg from "../../../package.json";
+import { noticeMessage, type NoticeMessage } from "../../../lib/notice.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import type { UpdateOutcome } from "./state.ts";
+
+/** The header marker: an up arrow and the newest version, e.g. `↑0.12.0`. */
+export function updateMarker(latest: string): string {
+	return `${GLYPHS.update}${latest}`;
+}
+
+/**
+ * The release page for a version, or `undefined` when this checkout does not name
+ * a GitHub repository. Derived from `package.json` so a rename cannot leave a dead
+ * link behind in the notice.
+ */
+export function releaseUrl(version: string): string | undefined {
+	const url = (pkg.repository as { url?: string } | undefined)?.url ?? "";
+	const base = url.replace(/\.git$/, "");
+	if (!/^https:\/\/github\.com\/[^/]+\/[^/]+$/.test(base)) return undefined;
+	return `${base}/releases/tag/v${version}`;
+}
+
+/** The single notice a session posts when a newer version is published. */
+export function updateNotice(current: string, latest: string): NoticeMessage {
+	const release = releaseUrl(latest);
+	const command = "pi update --extensions";
+	return noticeMessage({
+		content:
+			`bytefly ${latest} is available (current ${current}). Run \`${command}\` to update.` +
+			(release ? ` Release notes: ${release}` : ""),
+		details: {
+			source: "bytefly",
+			title: `${latest} is available`,
+			severity: "info",
+			items: release
+				? [
+						{ label: "current", detail: `v${current}` },
+						{ label: "update", detail: command },
+						{ label: "release", detail: release },
+					]
+				: [
+						{ label: "current", detail: `v${current}` },
+						{ label: "update", detail: command },
+					],
+		},
+	});
+}
+
+/**
+ * What `/bytefly update` prints. The background check is silent because nobody
+ * asked; here someone did, so a skip and a failed read are answers too.
+ */
+export function updateOutcomeText(
+	outcome: UpdateOutcome,
+	current: string,
+): { text: string; severity: "info" | "warning" } {
+	switch (outcome.kind) {
+		case "offline":
+			return { text: "bytefly: the update check was skipped (PI_OFFLINE is set).", severity: "info" };
+		case "failed":
+			return {
+				text: "bytefly: could not read the published version — check the network and try again.",
+				severity: "warning",
+			};
+		case "current":
+			return { text: `bytefly: up to date — v${outcome.latest} is the newest published version.`, severity: "info" };
+		case "available": {
+			const release = releaseUrl(outcome.latest);
+			return {
+				text: `bytefly: v${outcome.latest} is available (current ${current}).${release ? ` ${release}` : ""}`,
+				severity: "info",
+			};
+		}
+	}
+}

package/extensions/bytefly/update/register.ts

@@ -0,0 +1,158 @@
+/**
+ * The update check's lifecycle: reuse the cached answer or read the registry once
+ * per interactive session, record a newer version, and announce it once per load.
+ *
+ * The request is fired without awaiting. Pi awaits `session_start` handlers, so
+ * a slow registry would otherwise hold the first prompt; Pi's own version check
+ * is asynchronous for the same reason. Every result that is not a strictly newer
+ * version is silent, and a generation counter keeps a request that resolves
+ * after shutdown from writing into the next session's state.
+ *
+ * A cached answer with a timestamp is what makes a long-lived session different
+ * from a fresh one: a session that starts inside the window reuses the last read
+ * instead of repeating it, and `recheck()` ignores the window so `/bytefly update`
+ * can look again without a restart. `/bytefly` and `doctor` do not report the
+ * version: an available update is not a prerequisite problem.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import pkg from "../../../package.json";
+import { isOffline } from "../../../lib/env.ts";
+import { isFresh, readUpdateCache, updateCachePath, writeUpdateCache, type UpdateCacheEntry } from "./cache.ts";
+import { fetchLatestVersion } from "./check.ts";
+import { updateNotice } from "./format.ts";
+import type { UpdateOutcome, UpdateSource } from "./state.ts";
+import { isNewerVersion } from "./version.ts";
+
+/** The cache, as the lifecycle sees it: read on start, written after a read. */
+export interface UpdateCache {
+	/** The last recorded answer, or `undefined` for a miss. */
+	read(): UpdateCacheEntry | undefined;
+	/** Record an answer; a throw is treated as a miss. */
+	write(entry: UpdateCacheEntry): void;
+}
+
+/** What `registerUpdate` returns, so the panel can re-run the check on demand. */
+export interface UpdateHandle {
+	/** Read the registry now, ignoring the cache window. Never throws. */
+	recheck(): Promise<UpdateOutcome>;
+}
+
+/** Test seams; production uses the registry read, `PI_OFFLINE`, and the agent dir. */
+export interface UpdateDeps {
+	/** Replace the registry read; a rejection counts as no answer. */
+	fetchLatest?: () => Promise<string | undefined>;
+	/** Replace the `PI_OFFLINE` check. */
+	isOffline?: () => boolean;
+	/** Replace the disk cache. */
+	cache?: UpdateCache;
+	/** Replace the clock the cache timestamp is read from. */
+	now?: () => number;
+	/** Called once a newer version is recorded, so a mounted surface repaints. */
+	onUpdate?: () => void;
+}
+
+/** The on-disk cache under the agent directory, built lazily so it is per call. */
+function diskCache(): UpdateCache {
+	return {
+		read: () => readUpdateCache(updateCachePath(getAgentDir())),
+		write: (entry) => {
+			try {
+				writeUpdateCache(updateCachePath(getAgentDir()), entry);
+			} catch {
+				// A read-only agent directory costs the next session one request, nothing more.
+			}
+		},
+	};
+}
+
+/**
+ * Register the check. `updates` is the same store the header reads, so recording
+ * a version and calling `onUpdate` is what puts the marker on screen.
+ */
+export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: UpdateDeps = {}): UpdateHandle {
+	const readLatest = deps.fetchLatest ?? (() => fetchLatestVersion());
+	const offline = deps.isOffline ?? isOffline;
+	const cache = deps.cache ?? diskCache();
+	const now = deps.now ?? Date.now;
+	// A session is announced at most once per load, even if `session_start` fires
+	// again after a resume or a session replacement.
+	let announced = false;
+	let generation = 0;
+
+	/** Record a newer version and repaint the marker. */
+	const paint = (latest: string): void => {
+		if (!isNewerVersion(latest, pkg.version)) return;
+		updates.set(latest);
+		deps.onUpdate?.();
+	};
+
+	/** The once-per-load transcript notice, posted only for a strictly newer version. */
+	const announce = (latest: string): void => {
+		if (announced || !isNewerVersion(latest, pkg.version)) return;
+		announced = true;
+		pi.sendMessage(updateNotice(pkg.version, latest));
+	};
+
+	/** One answer, from the cache or the registry: paint the marker, announce it once. */
+	const record = (entry: UpdateCacheEntry): void => {
+		paint(entry.latest);
+		announce(entry.latest);
+	};
+
+	const check = async (token: number): Promise<void> => {
+		try {
+			const latest = await readLatest();
+			if (latest === undefined || token !== generation) return;
+			const entry = { latest, checkedAt: now() };
+			cache.write(entry);
+			record(entry);
+		} catch {
+			// A background check never surfaces an error: the session does not know it ran.
+		}
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		// The marker lives in bytefly's header and the notice in a transcript, so a
+		// non-interactive run has nothing to draw and makes no request.
+		if (ctx.mode !== "tui") return;
+		if (offline()) {
+			// No request, so the window does not matter: the cached answer is the best
+			// one available, and the marker is advisory.
+			const cached = cache.read();
+			if (cached) record(cached);
+			return;
+		}
+		const cached = cache.read();
+		if (cached && isFresh(cached, now())) {
+			record(cached);
+			return;
+		}
+		if (announced) return;
+		void check(generation);
+	});
+
+	pi.on("session_shutdown", () => {
+		// Invalidate any request still in flight and drop what this session found.
+		generation++;
+		updates.set();
+	});
+
+	return {
+		async recheck() {
+			if (offline()) return { kind: "offline" };
+			let latest: string | undefined;
+			try {
+				latest = await readLatest();
+			} catch {
+				return { kind: "failed" };
+			}
+			if (latest === undefined) return { kind: "failed" };
+			cache.write({ latest, checkedAt: now() });
+			// The caller prints the answer, so this path never posts a notice.
+			paint(latest);
+			return isNewerVersion(latest, pkg.version) ? { kind: "available", latest } : { kind: "current", latest };
+		},
+	};
+}

package/extensions/bytefly/update/state.ts

@@ -0,0 +1,40 @@
+/**
+ * Where a surface reads the newest published version this load found, and what an
+ * explicit re-check reported.
+ *
+ * The check resolves after the session started, so the header cannot be handed
+ * the value up front: it reads through this store on every apply, and the
+ * update registration re-installs the header once the value arrives. The store
+ * is created once per load by the composition root — no module state — and
+ * cleared on shutdown, so a reload starts from nothing.
+ */
+
+/** The store the header reads and the update lifecycle writes. */
+export interface UpdateSource {
+	/** The newer published version, or `undefined` when none is known. */
+	latest(): string | undefined;
+	/** Record a version, or clear it with no argument. */
+	set(latest?: string): void;
+}
+
+/**
+ * What one explicit re-check found. The background check reports nothing — nobody
+ * asked — so this vocabulary exists only for `/bytefly update`, where a failure or
+ * a skip is an answer rather than silence.
+ */
+export type UpdateOutcome =
+	| { kind: "offline" }
+	| { kind: "failed" }
+	| { kind: "current"; latest: string }
+	| { kind: "available"; latest: string };
+
+/** A store holding at most one version. */
+export function createUpdateState(): UpdateSource {
+	let latest: string | undefined;
+	return {
+		latest: () => latest,
+		set(next) {
+			latest = next || undefined;
+		},
+	};
+}

package/extensions/bytefly/update/version.ts

@@ -0,0 +1,83 @@
+/**
+ * Version comparison for the update check.
+ *
+ * The registry answers with whatever string the published manifest carries, so
+ * both sides of the comparison are untrusted input: a payload that does not
+ * parse is never an upgrade. Only the parts that decide ordering are read — the
+ * numeric core and the prerelease identifiers — and build metadata is ignored,
+ * as semver says it must be for precedence.
+ */
+
+/** A version split into the parts that decide precedence. */
+export interface ParsedVersion {
+	/** Major, minor, and patch; a missing segment is 0. */
+	readonly core: readonly [number, number, number];
+	/** Prerelease identifiers, empty for a release version. */
+	readonly pre: readonly string[];
+}
+
+/** `[v]X[.Y[.Z]][-pre][+build]`, with no leading zeros left to interpretation. */
+const VERSION_SHAPE = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** Whether a prerelease identifier is a dot-separated, non-empty semver identifier run. */
+function isPrerelease(value: string): boolean {
+	return value.split(".").every((identifier) => identifier.length > 0 && /^[0-9A-Za-z-]+$/.test(identifier));
+}
+
+/** Parse a version string, or `undefined` when it is not one. */
+export function parseVersion(value: string): ParsedVersion | undefined {
+	const match = VERSION_SHAPE.exec(value.trim());
+	if (!match) return undefined;
+	const prerelease = match[4];
+	if (prerelease !== undefined && !isPrerelease(prerelease)) return undefined;
+	return {
+		core: [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)],
+		pre: prerelease === undefined ? [] : prerelease.split("."),
+	};
+}
+
+/** `a`'s precedence relative to `b`: negative, zero, or positive. */
+function compareCore(a: ParsedVersion, b: ParsedVersion): number {
+	for (const index of [0, 1, 2] as const) {
+		const difference = a.core[index] - b.core[index];
+		if (difference !== 0) return difference;
+	}
+	return 0;
+}
+
+/**
+ * Prerelease precedence, per semver: identifiers are compared left to right,
+ * numeric ones numerically and below alphanumeric ones, a longer set wins over
+ * its own prefix, and any prerelease sits below the release it leads to.
+ */
+function comparePre(a: ParsedVersion, b: ParsedVersion): number {
+	if (a.pre.length === 0 || b.pre.length === 0) {
+		return b.pre.length - a.pre.length;
+	}
+	for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index++) {
+		const left = a.pre[index];
+		const right = b.pre[index];
+		if (left === undefined) return -1;
+		if (right === undefined) return 1;
+		const leftNumeric = /^\d+$/.test(left);
+		const rightNumeric = /^\d+$/.test(right);
+		if (leftNumeric && rightNumeric) {
+			const difference = Number(left) - Number(right);
+			if (difference !== 0) return difference;
+			continue;
+		}
+		if (leftNumeric) return -1;
+		if (rightNumeric) return 1;
+		if (left !== right) return left < right ? -1 : 1;
+	}
+	return 0;
+}
+
+/** Whether `candidate` is a strictly newer version than `current`; false when either does not parse. */
+export function isNewerVersion(candidate: string, current: string): boolean {
+	const next = parseVersion(candidate);
+	const loaded = parseVersion(current);
+	if (!next || !loaded) return false;
+	const core = compareCore(next, loaded);
+	return core !== 0 ? core > 0 : comparePre(next, loaded) > 0;
+}