@coywolf/emdash 0.35.14 → 0.35.15

package/README.md

@@ -47,13 +47,13 @@ Coywolf Pack is a native (trusted) EmDash plugin: you add it to your site's code
 
 ### 1. Install the package
 
-From the site's folder, install the latest release. Releases are listed under [Tags](https://github.com/coywolf-llc/coywolf-pack/tags); replace `v0.35.13` with the newest one:
+From the site's folder:
 
 ```bash
-npm install https://codeload.github.com/coywolf-llc/coywolf-pack/tar.gz/refs/tags/v0.35.13
+npm install @coywolf/emdash
 ```
 
-The package is named `@coywolf/emdash`. Use the tarball URL rather than `github:coywolf-llc/coywolf-pack`: npm records `github:` installs as SSH Git URLs, which CI runners without an SSH key can't fetch.
+The package is [`@coywolf/emdash` on npm](https://www.npmjs.com/package/@coywolf/emdash). Each version links to the GitHub commit and workflow run that built it (npm provenance). What changed in each release is under [Releases](https://github.com/coywolf-llc/coywolf-pack/releases).
 
 ### 2. Add the plugin to `astro.config.mjs`
 
@@ -156,7 +156,15 @@ A good first set for most sites:
 
 ### Updating
 
-Install the newer release's tarball (step 1 with the new tag), then deploy. Updates never turn features on by themselves: new features start off.
+Install the latest version, then deploy:
+
+```bash
+npm install @coywolf/emdash@latest
+```
+
+If your `package.json` points at a GitHub tarball URL from before the pack was on npm (0.35.13 and earlier), this command replaces it with the npm version. Updates never turn features on by themselves: new features start off.
+
+**Update notices:** once a day, the pack asks npm for its newest version. When there's an update, a **Coywolf Pack update** card on the EmDash dashboard and a notice at the top of the pack's pages show the command above, with a **Copy command** button. **Dismiss** hides both for everyone on the site until the next version. The check sends nothing about your site and never updates anything by itself. Like every feature, it starts off: turn on **Update check** at the top of **Plugins → Coywolf Pack → Features**.
 
 ### Local development
 

package/docs/releasing.md

@@ -13,9 +13,9 @@ Each release is a version tag, a GitHub release and an npm version of `@coywolf/
 
 The workflow uses npm trusted publishing: npm accepts publishes from this repository's workflow without any stored token.
 
-1. The npm organization `coywolf` owns the `@coywolf` scope.
-2. The first version is published by hand, because npm sets up a trusted publisher only for a package that exists. From a clean checkout of the release tag, signed in to npm with an account in the `coywolf` organization: `npm publish --access public` (npm asks for the two-factor code).
-3. On npmjs.com, open `@coywolf/emdash` → **Settings** → **Trusted publishing**, choose **GitHub Actions**, and enter organization `coywolf-llc`, repository `coywolf-pack`, workflow `publish.yml` (no environment).
+1. The npm account `coywolf` owns the `@coywolf` scope (a user's scope; no organization needed).
+2. The first version is published by hand, because npm sets up a trusted publisher only for a package that exists. From a clean checkout of the release tag, signed in to npm as `coywolf`: `npm publish --access public` (npm asks for the two-factor code).
+3. On npmjs.com, open `@coywolf/emdash` → **Settings** → **Trusted publishing**, choose **GitHub Actions**, and enter organization `coywolf-llc`, repository `coywolf-pack`, workflow `publish.yml` (no environment). Done for 0.35.13; 0.35.14 was the first version the workflow published.
 4. Optional, recommended: in the package's **Settings → Publishing access**, choose **Require two-factor authentication and disallow tokens**. Trusted publishing keeps working.
 
 npm reviews a new package's first versions before they're public: until then `npm view` reports the package as not found and the package page shows a "Temporary Holding Version". A new trusted publisher shows **Pending validation** until the workflow publishes through it once.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@coywolf/emdash",
-	"version": "0.35.14",
+	"version": "0.35.15",
 	"description": "Coywolf Pack for EmDash: one plugin with Coywolf's features for EmDash sites on Cloudflare. Full backups and restore, a redirect manager, and more to come.",
 	"license": "MIT",
 	"author": "Coywolf LLC (https://coywolf.com)",

package/src/admin/features.tsx

@@ -6,6 +6,8 @@ import { useQueryClient } from "@tanstack/react-query";
 import { apiFetch, parseApiResponse } from "emdash/plugin-utils";
 import * as React from "react";
 
+import { resetUpdateStatus } from "./update-notice.js";
+
 
 const API = "/_emdash/api/plugins/coywolf-pack/features";
 
@@ -65,6 +67,8 @@ export function FeaturesPage() {
 			setModules((current) =>
 				current?.map((m) => ({ ...m, features: m.features.map((f) => ({ ...f, enabled: features[f.id] ?? f.enabled })) })) ?? null,
 			);
+			// The update notices ask again whether to show (the dashboard card follows the manifest below).
+			if (id === "updates") resetUpdateStatus();
 			// A module's pages show in the sidebar only while it's on: refresh the admin manifest.
 			if (!id.includes(".")) {
 				if (queryClient) void queryClient.invalidateQueries({ queryKey: ["manifest"] });

package/src/admin/index.tsx

@@ -2,6 +2,7 @@ import type { PluginAdminExports } from "emdash";
 
 import { injectAdminCss } from "./admin-css.js";
 import { mountTrashPrompt } from "./trash-prompt.js";
+import { UpdateWidget, withUpdateNotice } from "./update-notice.js";
 
 import { AiPage } from "./ai.js";
 import { BackupStatusWidget, BackupsPage } from "./backups.js";
@@ -30,7 +31,7 @@ injectAdminCss();
 // Asks what a trashed or unpublished entry's old URL should do (Redirects → Removed content).
 mountTrashPrompt();
 
-export const pages: PluginAdminExports["pages"] = {
+const PAGES: PluginAdminExports["pages"] = {
 	"/features": FeaturesPage,
 	"/performance": PerformancePage,
 	"/backups": BackupsPage,
@@ -55,8 +56,13 @@ export const pages: PluginAdminExports["pages"] = {
 	"/images": ImagesPage,
 };
 
+// Every pack page shows the update notice at the top when a newer Coywolf Pack is out.
+export const pages: PluginAdminExports["pages"] = Object.fromEntries(Object.entries(PAGES).map(([path, Page]) => [path, withUpdateNotice(Page)]));
+
 export const widgets: PluginAdminExports["widgets"] = {
 	"backup-status": BackupStatusWidget,
 	"links-status": LinksWidget,
 	"cloudflare-usage": UsageWidget,
+	// Listed by the server only while a Coywolf Pack update is waiting.
+	update: UpdateWidget,
 };

package/src/admin/update-notice.tsx

@@ -0,0 +1,198 @@
+/**
+ * "Coywolf Pack x.y.z is available": a card on EmDash's dashboard (listed by
+ * the server only while an update is waiting) and a notice at the top of
+ * every pack page, each with the command to install it. The server asks npm
+ * at most once a day; the pages read the answer once per admin visit.
+ * Dismissing hides both for everyone on the site until a newer version.
+ */
+import { Banner, Button } from "@cloudflare/kumo";
+import { useQueryClient } from "@tanstack/react-query";
+import { apiFetch, parseApiResponse } from "emdash/plugin-utils";
+import * as React from "react";
+
+import type { UpdateStatus } from "../updates/check.js";
+
+const API = "/_emdash/api/plugins/coywolf-pack/updates";
+const CHANGED_EVENT = "coywolf-pack:update-changed";
+
+type Available = Extract<UpdateStatus, { enabled: true }> & { latest: string };
+
+/** One request per admin visit (the admin is a single-page app). */
+let pending: Promise<UpdateStatus | null> | null = null;
+function loadStatus(): Promise<UpdateStatus | null> {
+	// Not an admin, the module left out, or offline: no notice for this visit.
+	pending ??= apiFetch(`${API}/status`)
+		.then((response) => parseApiResponse<UpdateStatus>(response, "Couldn't check for updates"))
+		.catch(() => null);
+	return pending;
+}
+
+/** Ask again (after Update check is switched on or off): the notices on the page refresh. */
+export function resetUpdateStatus(): void {
+	pending = null;
+	window.dispatchEvent(new Event(CHANGED_EVENT));
+}
+
+/** The EmDash admin's query client, to refresh the dashboard after a dismissal (null if unavailable). */
+function useAdminQueryClient() {
+	try {
+		return useQueryClient();
+	} catch {
+		return null;
+	}
+}
+
+function useUpdate(options: { reloadAfterDismiss?: boolean } = {}): { status: UpdateStatus | null; loaded: boolean; update: Available | null; dismiss: () => Promise<void>; error: string | null } {
+	const queryClient = useAdminQueryClient();
+	const [status, setStatus] = React.useState<UpdateStatus | null>(null);
+	const [loaded, setLoaded] = React.useState(false);
+	const [error, setError] = React.useState<string | null>(null);
+	React.useEffect(() => {
+		let live = true;
+		const read = () =>
+			void loadStatus().then((s) => {
+				if (!live) return;
+				setStatus(s);
+				setLoaded(true);
+			});
+		read();
+		// A dismissal in one notice hides the others on the page.
+		window.addEventListener(CHANGED_EVENT, read);
+		return () => {
+			live = false;
+			window.removeEventListener(CHANGED_EVENT, read);
+		};
+	}, []);
+	const update = status?.enabled && status.available && !status.dismissed && status.latest ? (status as Available) : null;
+	const dismiss = async () => {
+		if (!update) return;
+		setError(null);
+		try {
+			const response = await apiFetch(`${API}/dismiss`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ version: update.latest }),
+			});
+			await parseApiResponse(response, "Couldn't dismiss the notice");
+			pending = Promise.resolve({ ...update, dismissed: true });
+			window.dispatchEvent(new Event(CHANGED_EVENT));
+			// The dashboard card is listed by the admin manifest: refresh it so the card goes. EmDash's admin
+			// keeps its own copy of React Query, so its client may be out of reach: then reload, like the Features page.
+			if (queryClient) void queryClient.invalidateQueries({ queryKey: ["manifest"] });
+			else if (options.reloadAfterDismiss) window.location.reload();
+		} catch (cause) {
+			setError(cause instanceof Error && cause.message ? cause.message : "Couldn't dismiss the notice");
+		}
+	};
+	return { status, loaded, update, dismiss, error };
+}
+
+/** Copies the command; if the browser refuses, selects it so ⌘C or Ctrl+C copies it. */
+function useCopyCommand(): [string, React.RefObject<HTMLElement | null>, (text: string) => void] {
+	const [status, setStatus] = React.useState("");
+	const ref = React.useRef<HTMLElement | null>(null);
+	const timer = React.useRef<number | undefined>(undefined);
+	React.useEffect(() => () => window.clearTimeout(timer.current), []);
+	const copy = (text: string) => {
+		const done = (message: string) => {
+			setStatus(message);
+			window.clearTimeout(timer.current);
+			timer.current = window.setTimeout(() => setStatus(""), 4000);
+		};
+		const select = () => {
+			const selection = window.getSelection();
+			if (ref.current && selection) {
+				selection.selectAllChildren(ref.current);
+				done("Couldn't copy: the command is selected, press ⌘C or Ctrl+C");
+			} else done("Couldn't copy");
+		};
+		if (!navigator.clipboard?.writeText) return select();
+		navigator.clipboard.writeText(text).then(() => done("Copied"), select);
+	};
+	return [status, ref, copy];
+}
+
+/** The command and actions, shared by the dashboard card and the page notice. */
+function UpdateDetails(props: { update: Available; dismiss: () => Promise<void>; error: string | null }) {
+	const { update } = props;
+	const [copied, commandRef, copy] = useCopyCommand();
+	const [dismissing, setDismissing] = React.useState(false);
+	return (
+		<div className="space-y-3">
+			<p>
+				This site runs {update.current}. In the site's folder, run this command, then deploy. Updating never turns features on by
+				itself.
+			</p>
+			<pre className="cw-overflow-auto rounded-md border border-kumo-line px-3 py-2 font-mono text-sm">
+				<code ref={commandRef}>{update.command}</code>
+			</pre>
+			<div className="flex flex-wrap items-center gap-2">
+				<Button variant="secondary" size="sm" onClick={() => copy(update.command)}>
+					Copy command
+				</Button>
+				<a className="text-kumo-link hover:underline" href={update.releasesUrl} target="_blank" rel="noopener noreferrer">
+					What's new<span className="sr-only"> (opens in a new tab)</span>
+				</a>
+				<Button
+					variant="ghost"
+					size="sm"
+					disabled={dismissing}
+					onClick={() => {
+						setDismissing(true);
+						void props.dismiss().finally(() => setDismissing(false));
+					}}
+				>
+					Dismiss
+				</Button>
+				<span role="status" aria-live="polite" className="text-sm text-kumo-subtle">
+					{props.error ?? copied}
+				</span>
+			</div>
+		</div>
+	);
+}
+
+/** The notice at the top of a pack page. */
+export function UpdateNotice() {
+	const { update, dismiss, error } = useUpdate();
+	if (!update) return null;
+	return (
+		<div style={{ marginBottom: "1.5rem" }}>
+			<Banner title={`Coywolf Pack ${update.latest} is available`} description={<UpdateDetails update={update} dismiss={dismiss} error={error} />} />
+		</div>
+	);
+}
+
+/** The dashboard card (EmDash lists it only while an update is waiting). */
+export function UpdateWidget() {
+	const { status, loaded, update, dismiss, error } = useUpdate({ reloadAfterDismiss: true });
+	if (!loaded) return null;
+	if (!update) {
+		// Listed only while an update is waiting: an editor can't read the details (admins only); an admin just dismissed it.
+		return (
+			<p className="text-sm text-kumo-subtle">
+				{status ? "Dismissed. This card goes away the next time the dashboard loads." : "A Coywolf Pack update is waiting. An administrator can install it."}
+			</p>
+		);
+	}
+	return (
+		<div className="space-y-3 text-sm">
+			<h3 className="text-base font-semibold">Coywolf Pack {update.latest} is available</h3>
+			<UpdateDetails update={update} dismiss={dismiss} error={error} />
+		</div>
+	);
+}
+
+/** A pack page with the notice above it. */
+export function withUpdateNotice(Page: React.ComponentType): React.ComponentType {
+	function PageWithUpdateNotice() {
+		return (
+			<>
+				<UpdateNotice />
+				<Page />
+			</>
+		);
+	}
+	PageWithUpdateNotice.displayName = `WithUpdateNotice(${Page.displayName ?? Page.name ?? "Page"})`;
+	return PageWithUpdateNotice;
+}

package/src/core/features.ts

@@ -374,6 +374,16 @@ export async function readSiteSetting<T = unknown>(key: string, database: Databa
 	return settings ? { value: (settings.get(key) as T | undefined) ?? null } : null;
 }
 
+/**
+ * A registered setting as this isolate last read it, synchronously (undefined before any read),
+ * for EmDash's admin manifest like knownFeatures. The middleware reads the settings afresh for
+ * every manifest request, so it's current there.
+ */
+export function knownSiteSetting<T>(key: string): T | null | undefined {
+	if (!cached?.keys?.has(key)) return undefined;
+	return (cached.settings?.get(key) as T | undefined) ?? null;
+}
+
 /** Update a registered setting in this isolate's cache after writing it (other isolates see it within FEATURES_TTL_MS). */
 export function rememberSiteSetting(key: string, value: unknown): void {
 	cached?.settings?.set(key, value);

package/src/core/module.ts

@@ -35,6 +35,8 @@ export interface WidgetDef {
 	id: string;
 	title: string;
 	size: "full" | "half" | "third";
+	/** Listed on the dashboard only while this returns true (read on every admin manifest request; must be synchronous). */
+	when?: () => boolean;
 }
 
 /** A scheduled job. `schedule` is cron syntax or @hourly/@daily/@weekly. */

package/src/index.ts

@@ -17,7 +17,7 @@ import { composeHooks, hookCapabilities } from "./core/compose.js";
 import { configureContentUrls } from "./core/content-url.js";
 import { PLUGIN_ID, isOn, knownFeatures } from "./core/features.js";
 import { featuresRoutes } from "./core/features-module.js";
-import type { AdminPageDef, PackModule } from "./core/module.js";
+import type { AdminPageDef, PackModule, WidgetDef } from "./core/module.js";
 import { secretSettingsSchema } from "./core/secrets.js";
 import { MODULES } from "./modules.js";
 import type { CoywolfOptions } from "./options.js";
@@ -56,10 +56,13 @@ function buildModules(options: CoywolfOptions): PackModule[] {
 	return MODULES.map((factory) => factory(options)).filter((m): m is PackModule => m !== null);
 }
 
+/** A widget as EmDash lists it (without the pack's `when`). */
+const widgetEntry = ({ when: _when, ...widget }: WidgetDef) => widget;
+
 function surfaces(modules: PackModule[]) {
 	return {
 		pages: sidebar(modules),
-		widgets: modules.flatMap((m) => m.widgets ?? []),
+		widgets: modules.flatMap((m) => m.widgets ?? []).map(widgetEntry),
 		blocks: modules.flatMap((m) => m.portableTextBlocks ?? []),
 		settingsSchema: secretSettingsSchema(modules.map((m) => m.settingsSchema)),
 		storage: Object.assign({}, ...modules.map((m) => m.storage ?? {})),
@@ -113,7 +116,12 @@ function liveAdmin<T extends object>(modules: PackModule[], base: T) {
 		},
 		widgets: {
 			enumerable: true,
-			get: () => modules.filter(on).flatMap((m) => m.widgets ?? []),
+			get: () =>
+				modules
+					.filter(on)
+					.flatMap((m) => m.widgets ?? [])
+					.filter((w) => !w.when || w.when())
+					.map(widgetEntry),
 		},
 	}) as T & { pages: PackModule["adminPages"]; widgets: PackModule["widgets"] };
 }

package/src/modules.ts

@@ -23,11 +23,14 @@ import { robotsMiddleware, robotsPack } from "./robots/pack.js";
 import { reviewsPack } from "./reviews/pack.js";
 import type { CoywolfOptions } from "./options.js";
 import { videosCaptionsMiddleware, videosPack, videosSitemapMiddleware } from "./videos/pack.js";
+import { updatesPack } from "./updates/pack.js";
 import { wpImportPack } from "./wpImport/pack.js";
 
 type Factory = (options: CoywolfOptions) => PackModule | null;
 
 export const MODULES: Factory[] = [
+	// First on the Features page, where it's easy to find (no hooks or middleware, so its place changes nothing else).
+	(o) => (o.updates === false ? null : updatesPack()),
 	(o) => (o.backups ? backupsPack(o.backups) : null),
 	(o) => (o.redirects === false ? null : redirectsPack(o.redirects ?? {})),
 	// Before Headings & TOC: imported heading ids must be in place when anchors are stamped.

package/src/options.ts

@@ -42,6 +42,8 @@ export interface CoywolfOptions {
 	images?: import("./images/pack.js").ImagesOptions | false;
 	/** Page cache upkeep for Cloudflare Workers Cache (no options yet). `false` leaves the module out. */
 	pageCache?: Record<string, never> | false;
+	/** The daily check for a newer Coywolf Pack on npm (off until turned on on the Features page). `false` leaves the module out. */
+	updates?: Record<string, never> | false;
 	/** @deprecated Until 0.12.0 the Custom Blocks module was called Content Blocks; `contentBlocks: false` still leaves it out. */
 	contentBlocks?: Record<string, never> | false;
 	/** WordPress import tools (no options yet). `false` leaves the module out. */

package/src/pageCache/lib.ts

@@ -21,10 +21,12 @@ export const VERSION_OPTION = "plugin:coywolf-pack:pageCache:version";
  */
 const PUBLIC_ROUTE = /^\/_emdash\/api\/plugins\/coywolf-pack\/(search\/|discovery\/public\/|videos\/(like|play|caption|embed|sitemap)(\/|$))/;
 const PACK_API = "/_emdash/api/plugins/coywolf-pack/";
+/** Admin writes that change nothing a page or a cache shows: no purge and no new settings generation. */
+const NO_SETTINGS_CHANGE = /^\/_emdash\/api\/plugins\/coywolf-pack\/updates\//;
 
 /** True when a request is a pack admin write whose success should purge the cache. */
 export function purgesAfter(method: string, pathname: string): boolean {
-	return method === "POST" && pathname.startsWith(PACK_API) && !PUBLIC_ROUTE.test(pathname);
+	return method === "POST" && pathname.startsWith(PACK_API) && !PUBLIC_ROUTE.test(pathname) && !NO_SETTINGS_CHANGE.test(pathname);
 }
 
 export type PurgeScope = { purgeEverything: true } | { pathPrefixes: string[] } | { tags: string[] };
@@ -70,7 +72,7 @@ export function keepOffEdge(context: unknown): void {
 export function purgeScope(pathname: string): PurgeScope | null {
 	const route = pathname.slice(PACK_API.length);
 	if (/^redirects\/(?!(list|test|removed)$)|^backups\/(rewind|undo)$/.test(route)) return { tags: [REDIRECTS_TAG] };
-	if (/^(redirects|backups|links)\//.test(route) || /^cache\/(media|warm|purge)(\/|$)/.test(route)) return null;
+	if (/^(redirects|backups|links|updates)\//.test(route) || /^cache\/(media|warm|purge)(\/|$)/.test(route)) return null;
 	// Stored image sizes: new uploads and crops are picked up after a short stopgap lifetime; a backfill run clears the cache itself once when it is done.
 	if (/^images\/variants\/(settings|run|bulk|estimate)$/.test(route)) return null;
 	// Videos admin reads (library, details, status, storage, settings, captions list) change nothing.

package/src/updates/check.ts

@@ -0,0 +1,135 @@
+/**
+ * Update check: once a day, ask npm which version of Coywolf Pack is the
+ * latest, and tell the admin when it's newer than the one this site runs.
+ * The request is npm's public dist-tags for the package; it carries nothing
+ * about the site.
+ *
+ * The answer is a plugin setting (an option row), registered with the
+ * switches' query, so EmDash's admin manifest can list the dashboard card
+ * only while an update is waiting (see updateCardVisible). A daily task
+ * keeps it current; the pack pages' notice also checks when it's a day old.
+ */
+import { isOn, knownFeatures, knownSiteSetting, registerSiteSetting, rememberSiteSetting } from "../core/features.js";
+import { VERSION } from "../version.js";
+import { DIST_TAGS_URL, RELEASES_URL, UPDATE_COMMAND, isNewer, parseVersion } from "./core.js";
+
+export const UPDATE_STATE_SETTING = "updateState";
+registerSiteSetting(UPDATE_STATE_SETTING);
+
+const CHECK_EVERY_MS = 24 * 60 * 60_000;
+/** After a failed check, wait this long before asking npm again. */
+const RETRY_AFTER_MS = 6 * 60 * 60_000;
+const TIMEOUT_MS = 5_000;
+
+export interface UpdateState {
+	/** When npm last answered. */
+	checkedAt: string | null;
+	latest: string | null;
+	/** When the last check failed (cleared by a successful one). */
+	failedAt?: string | null;
+	/** The version an admin dismissed the notice for (site-wide; a newer version shows again). */
+	dismissed?: string | null;
+}
+
+export type UpdateStatus =
+	| { enabled: false; current: string }
+	| { enabled: true; current: string; latest: string | null; available: boolean; dismissed: boolean; checkedAt: string | null; releasesUrl: string; command: string };
+
+type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
+interface Ctx {
+	settings: { get<T>(key: string): Promise<T | null | undefined>; set(key: string, value: unknown): Promise<void> };
+	log: { warn(message: string, data?: unknown): void };
+	http?: { fetch: Fetch } | null;
+}
+
+const age = (at: string | null | undefined, now: number) => (at ? now - Date.parse(at) : Number.POSITIVE_INFINITY);
+const EMPTY: UpdateState = { checkedAt: null, latest: null };
+
+/** True when the state has an update the site hasn't dismissed. */
+export function showsUpdate(state: UpdateState | null | undefined, current = VERSION): boolean {
+	return Boolean(state && isNewer(state.latest, current) && state.dismissed !== state.latest);
+}
+
+/**
+ * For the admin manifest (synchronous): list the dashboard card only while the check is on and an
+ * undismissed update is waiting, as this isolate last read them (afresh for every manifest request).
+ */
+export function updateCardVisible(): boolean {
+	const features = knownFeatures();
+	if (!features || !isOn(features, "updates")) return false;
+	return showsUpdate(knownSiteSetting<UpdateState>(UPDATE_STATE_SETTING));
+}
+
+async function readState(ctx: Ctx): Promise<UpdateState> {
+	return (await ctx.settings.get<UpdateState>(UPDATE_STATE_SETTING).catch(() => null)) ?? { ...EMPTY };
+}
+
+async function writeState(ctx: Ctx, state: UpdateState): Promise<void> {
+	await ctx.settings.set(UPDATE_STATE_SETTING, state);
+	rememberSiteSetting(UPDATE_STATE_SETTING, state);
+}
+
+async function askNpm(ctx: Ctx): Promise<string> {
+	const doFetch = (ctx.http ? ctx.http.fetch.bind(ctx.http) : fetch) as Fetch;
+	const timeout = typeof AbortSignal !== "undefined" && "timeout" in AbortSignal ? AbortSignal.timeout(TIMEOUT_MS) : undefined;
+	const res = await doFetch(DIST_TAGS_URL, { headers: { Accept: "application/json" }, ...(timeout ? { signal: timeout } : {}) });
+	if (!res.ok) throw new Error(`npm answered ${res.status}`);
+	const tags = (await res.json()) as { latest?: unknown };
+	if (!parseVersion(tags.latest)) throw new Error("npm's answer had no latest version");
+	return String(tags.latest).trim();
+}
+
+let checking: Promise<UpdateState> | null = null;
+
+/** The saved answer, or a new one when it's a day old (or six hours after a failure). */
+export async function checkForUpdate(ctx: Ctx, now = Date.now()): Promise<UpdateState> {
+	const saved = await readState(ctx);
+	if (age(saved.checkedAt, now) < CHECK_EVERY_MS || age(saved.failedAt, now) < RETRY_AFTER_MS) return saved;
+	if (checking) return checking;
+	checking = (async () => {
+		let latest: string;
+		try {
+			latest = await askNpm(ctx);
+		} catch (error) {
+			ctx.log.warn("Update check: couldn't ask npm", { error: error instanceof Error ? error.message : String(error) });
+			// Keep the last answer (re-read, so a dismissal made meanwhile isn't lost); try again later.
+			const current = await readState(ctx);
+			const state: UpdateState = { ...current, failedAt: new Date(now).toISOString() };
+			await writeState(ctx, state).catch(() => undefined);
+			return state;
+		}
+		// Re-read before writing, so a dismissal made while npm answered isn't lost.
+		const current = await readState(ctx);
+		const state: UpdateState = { ...current, checkedAt: new Date(now).toISOString(), latest, failedAt: null };
+		await writeState(ctx, state);
+		return state;
+	})().finally(() => {
+		checking = null;
+	});
+	return checking;
+}
+
+/** Whether a newer Coywolf Pack is on npm. Nothing is asked while the check is off. */
+export async function updateStatus(ctx: Ctx, enabled: boolean, now = Date.now()): Promise<UpdateStatus> {
+	if (!enabled) return { enabled: false, current: VERSION };
+	const state = await checkForUpdate(ctx, now);
+	const available = isNewer(state.latest, VERSION);
+	return {
+		enabled: true,
+		current: VERSION,
+		latest: state.latest,
+		available,
+		dismissed: available && state.dismissed === state.latest,
+		checkedAt: state.checkedAt,
+		releasesUrl: RELEASES_URL,
+		command: UPDATE_COMMAND,
+	};
+}
+
+/** Hide the notice (pack pages and the dashboard card) for this version, for everyone on the site. */
+export async function dismissUpdate(ctx: Ctx, version: string): Promise<UpdateState> {
+	const state = await readState(ctx);
+	const next: UpdateState = { ...state, dismissed: version };
+	await writeState(ctx, next);
+	return next;
+}

package/src/updates/core.ts

@@ -0,0 +1,56 @@
+/**
+ * Update check (pure part): version comparison and the notice's fixed text.
+ * No imports, so `node --test` can load this file.
+ */
+
+export const PACKAGE_NAME = "@coywolf/emdash";
+export const NPM_HOST = "registry.npmjs.org";
+/** npm's dist-tags for the package: a few bytes (`{"latest":"0.35.14"}`). */
+export const DIST_TAGS_URL = `https://${NPM_HOST}/-/package/%40coywolf%2Femdash/dist-tags`;
+export const RELEASES_URL = "https://github.com/coywolf-llc/coywolf-pack/releases";
+export const UPDATE_COMMAND = `npm install ${PACKAGE_NAME}@latest`;
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** A version npm could have given (x.y.z, optionally -prerelease and +build), or null. */
+export function parseVersion(value: unknown): { core: [number, number, number]; pre: string | null } | null {
+	if (typeof value !== "string") return null;
+	const m = SEMVER.exec(value.trim());
+	if (!m) return null;
+	return { core: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null };
+}
+
+function comparePre(a: string, b: string): number {
+	const x = a.split(".");
+	const y = b.split(".");
+	for (let i = 0; i < Math.max(x.length, y.length); i++) {
+		if (x[i] === undefined) return -1;
+		if (y[i] === undefined) return 1;
+		const nx = /^\d+$/.test(x[i]) ? Number(x[i]) : null;
+		const ny = /^\d+$/.test(y[i]) ? Number(y[i]) : null;
+		if (nx !== null && ny !== null) {
+			if (nx !== ny) return nx < ny ? -1 : 1;
+		} else if (nx !== null) return -1;
+		else if (ny !== null) return 1;
+		else if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+	}
+	return 0;
+}
+
+/** Semver order: -1, 0 or 1. Null when either isn't a version. */
+export function compareVersions(a: string, b: string): number | null {
+	const x = parseVersion(a);
+	const y = parseVersion(b);
+	if (!x || !y) return null;
+	for (let i = 0; i < 3; i++) if (x.core[i] !== y.core[i]) return x.core[i] < y.core[i] ? -1 : 1;
+	if (x.pre === y.pre) return 0;
+	// A release is newer than its prereleases.
+	if (x.pre === null) return 1;
+	if (y.pre === null) return -1;
+	return comparePre(x.pre, y.pre);
+}
+
+/** True when `latest` is a newer version than `current`. */
+export function isNewer(latest: string | null | undefined, current: string): boolean {
+	return typeof latest === "string" && compareVersions(latest, current) === 1;
+}

package/src/updates/pack.ts

@@ -0,0 +1,54 @@
+import { definePluginRoute } from "emdash";
+import { z } from "zod";
+
+import { ctxFeatures, isOn, registerFeatures } from "../core/features.js";
+import type { PackModule } from "../core/module.js";
+import { parseInput } from "../shared.js";
+import { NPM_HOST, parseVersion } from "./core.js";
+import { checkForUpdate, dismissUpdate, updateCardVisible, updateStatus } from "./check.js";
+
+/** Off by default, like every feature: nothing asks npm until the site turns it on. */
+const FEATURES = [
+	{
+		id: "updates",
+		label: "Update check",
+		description:
+			"Once a day, asks npm for the newest version of Coywolf Pack. When there's an update, a card on the dashboard and a notice on the pack's pages show the command to install it. It sends nothing about your site and never updates anything by itself.",
+		default: false,
+	},
+];
+registerFeatures(FEATURES);
+
+export const UPDATES_CHECK_TASK = "updates-check";
+
+export function updatesPack(): PackModule {
+	return {
+		id: "updates",
+		label: "Update check",
+		features: FEATURES,
+		routes: {
+			/** The running version and npm's latest (asked at most once a day). */
+			"updates/status": {
+				permission: "plugins:manage" as const,
+				// biome-ignore lint/suspicious/noExplicitAny: plugin context.
+				handler: async (ctx: any) => updateStatus(ctx, isOn(await ctxFeatures(ctx), "updates")),
+			},
+			/** Hide the notice for this version, for everyone on the site (a newer version shows again). */
+			"updates/dismiss": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					const { version } = parseInput(z.object({ version: z.string().refine((v) => parseVersion(v) !== null, "Not a version") }), ctx.input);
+					const state = await dismissUpdate(ctx, version.trim());
+					return { dismissed: state.dismissed };
+				},
+			}),
+		},
+		tasks: [{ name: UPDATES_CHECK_TASK, schedule: "@daily", handler: async (ctx) => void (await checkForUpdate(ctx)) }],
+		// Listed on the dashboard only while an update is waiting (see updateCardVisible).
+		widgets: [{ id: "update", title: "Coywolf Pack update", size: "full", when: updateCardVisible }],
+		capabilities: ["network:request"],
+		allowedHosts: [NPM_HOST],
+	};
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 /** The pack's version (keep in step with package.json). */
-export const VERSION = "0.35.14";
+export const VERSION = "0.35.15";