Serve plugin updates from tagged Gitea releases

Closes #65

Declare an Update URI header and answer core's update_plugins_{hostname}
filter from a new Update\UpdateChecker that offers the latest published
Gitea release's zip asset when it is newer than the installed version,
with transient caching and silent degradation on API failures.

Add a release workflow that fires on v* tag pushes: verifies the tag
matches the plugin Version header, runs the tests, builds the plugin zip,
and attaches it to the release (reusing a UI-created release, flagging
hyphenated versions as pre-release so /releases/latest skips them).

Co-Authored-By: Claude Fable 5 <[email protected]>

src/Plugin.php

@@ -29,6 +29,7 @@ use Unsupervised\Schedular\Policy\PolicyVersionRepository;
 use Unsupervised\Schedular\Registration\AnswerRepository;
 use Unsupervised\Schedular\Registration\QuestionRepository;
 use Unsupervised\Schedular\Registration\RegistrationGate;
+use Unsupervised\Schedular\Update\UpdateChecker;
 
 class Plugin {
 
@@ -74,6 +75,7 @@ class Plugin {
 		$registrationPage = new RegistrationPage( $invites, $policies, $policyVersions, $acceptances, $settings, $registrationMailer );
 		$groupClassPage   = new GroupClassPage();
 
+		( new UpdateChecker() )->register();
 		( new RoleManager() )->register();
 		( new RegistrationLoginGate() )->register();
 		( new EmailConfirmationHandler( $settings, $registrationMailer ) )->register();

src/Update/UpdateChecker.php

@@ -0,0 +1,146 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Update;
+
+use Unsupervised\Schedular\Val;
+
+/**
+ * Serves plugin updates from the Gitea repository's releases.
+ *
+ * Core reads the plugin's `Update URI` header and, during every update
+ * check, fires the `update_plugins_{hostname}` filter for that host. This
+ * class answers the filter by fetching the latest published release from
+ * the Gitea API and returning its zip asset when it is newer than the
+ * installed version. Everything downstream — the Plugins-screen notice,
+ * one-click updates, and opt-in auto-updates — is handled by core.
+ *
+ * Drafts and releases marked "pre-release" in Gitea are never offered:
+ * the `/releases/latest` endpoint excludes both.
+ */
+class UpdateChecker {
+
+	public const HOSTNAME = 'git.unsupervised.ca';
+	public const REPO_URL = 'https://git.unsupervised.ca/Unsupervised/unsupervised-scheduler';
+	public const API_URL  = 'https://git.unsupervised.ca/api/v1/repos/Unsupervised/unsupervised-scheduler/releases/latest';
+
+	public const TRANSIENT = 'us_schedular_latest_release';
+
+	/**
+	 * How long a release lookup (including a failed one) is cached. Core
+	 * runs update checks on admin page loads as well as twice-daily cron,
+	 * so the cache keeps the plugin from hammering the Gitea API.
+	 */
+	private const CACHE_TTL = 6 * 3600;
+
+	public function register(): void {
+		add_filter( 'update_plugins_' . self::HOSTNAME, [ $this, 'provideUpdate' ], 10, 3 );
+	}
+
+	/**
+	 * `update_plugins_{hostname}` filter callback. Returns the incoming
+	 * value untouched unless a newer release with a zip asset exists, in
+	 * which case it returns the update array core expects.
+	 */
+	public function provideUpdate( mixed $update, mixed $plugin_data, mixed $plugin_file ): mixed {
+		if ( plugin_basename( USC_PLUGIN_FILE ) !== $plugin_file ) {
+			return $update;
+		}
+
+		$release = $this->latestRelease();
+
+		if ( '' === $release['version'] || '' === $release['package'] ) {
+			return $update;
+		}
+
+		if ( version_compare( $release['version'], USC_VERSION, '<=' ) ) {
+			return $update;
+		}
+
+		return [
+			'slug'    => 'unsupervised-schedular',
+			'version' => $release['version'],
+			'url'     => self::REPO_URL,
+			'package' => $release['package'],
+		];
+	}
+
+	/**
+	 * The latest published release, from the transient cache when fresh.
+	 *
+	 * @return array{version: string, package: string} Empty strings when no
+	 *                                                 usable release exists.
+	 */
+	private function latestRelease(): array {
+		$cached = get_transient( self::TRANSIENT );
+		if ( is_array( $cached ) ) {
+			return [
+				'version' => Val::string( $cached['version'] ?? '' ),
+				'package' => Val::string( $cached['package'] ?? '' ),
+			];
+		}
+
+		$release = $this->fetchLatestRelease();
+		set_transient( self::TRANSIENT, $release, self::CACHE_TTL );
+
+		return $release;
+	}
+
+	/**
+	 * Ask the Gitea API for the latest published release's version and zip asset.
+	 *
+	 * @return array{version: string, package: string}
+	 */
+	private function fetchLatestRelease(): array {
+		$none = [
+			'version' => '',
+			'package' => '',
+		];
+
+		$response = wp_remote_get(
+			self::API_URL,
+			[
+				'timeout' => 10,
+				'headers' => [ 'Accept' => 'application/json' ],
+			]
+		);
+
+		if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
+			return $none;
+		}
+
+		$body = json_decode( wp_remote_retrieve_body( $response ), true );
+		if ( ! is_array( $body ) ) {
+			return $none;
+		}
+
+		// Release tags are named v1.2.3; the plugin header carries the bare version.
+		$version = preg_replace( '/^v/i', '', Val::string( $body['tag_name'] ?? '' ) ) ?? '';
+
+		// The release workflow attaches the built plugin zip (top-level
+		// unsupervised-schedular/ folder, production autoloader) as an asset.
+		// Gitea's auto-generated source archives are not usable packages.
+		$package = '';
+		$assets  = $body['assets'] ?? null;
+		if ( is_array( $assets ) ) {
+			foreach ( $assets as $asset ) {
+				if ( ! is_array( $asset ) ) {
+					continue;
+				}
+				if ( str_ends_with( strtolower( Val::string( $asset['name'] ?? '' ) ), '.zip' ) ) {
+					$package = Val::string( $asset['browser_download_url'] ?? '' );
+					break;
+				}
+			}
+		}
+
+		if ( '' === $version || '' === $package ) {
+			return $none;
+		}
+
+		return [
+			'version' => $version,
+			'package' => $package,
+		];
+	}
+}