Version update history for plugins & themes — a proposal

use Grav\Common\Filesystem\Folder;
use Grav\Common\Grav;
use Grav\Common\Utils;
+use Grav\Common\File\CompiledYamlFile;
+use Grav\Installer\Versions;
use RuntimeException;

        self::$error = self::OK;

+       // Record version history for freshly installed / updated plugins and
+       // themes. Core payloads install under system/ so they never match the
+       // plugins|themes path below and stay recorded exclusively by
+       // Install::finalize().
+       self::recordVersionHistory($install_path);

        return true;

    /**
     * Record a freshly installed / updated plugin or theme in
     * user/config/versions.yaml (the same store core/grav history is written
     * to by Install::finalize(), via VersionUpdater).
     *
     * @param string $install_path Fully resolved install destination.
     */
    private static function recordVersionHistory(string $install_path): void
    {
        if (!preg_match('|/(plugins|themes)/([^/]+)$|u', $install_path, $m)) {
            return; // System, binary, or root payload: core recording applies.
        }

        $type = $m[1];
        $slug = $m[2];

        $blueprints = $install_path . '/blueprints.yaml';
        if (!is_file($blueprints) || !is_readable($blueprints)) {
            return; // Best-effort metadata; never fail an otherwise good install.
        }

        $data = CompiledYamlFile::instance($blueprints)->content();
        $version = is_array($data) ? $data['version'] ?? null : null;
        if (!$version) {
            return;
        }

        Versions::instance()->updateVersion("{$type}/{$slug}", (string)$version)->save();
    }

        $r->addRoute('POST', '/gpm/upgrade', [GpmController::class, 'upgrade']);
+       $r->addRoute('GET', '/gpm/versions', [GpmController::class, 'versions']);

use Grav\Installer\Versions;

    /**
     * GET /gpm/versions - Installed versions and their recorded update history.
     *
     * Source: user/config/versions.yaml. History entries only exist for
     * updates made after the recording feature was released; there is no
     * backfill. Dates are UTC, Y-m-d H:i:s.
     */
    public function versions(ServerRequestInterface $request): ResponseInterface
    {
        $this->requirePermission($request, self::PERMISSION_READ);

        $versions = Versions::instance();
        $data = [
            'grav' => [
                'version' => $versions->getVersion('core/grav') ?? GRAV_VERSION,
                'history' => $versions->getHistory('core/grav'),
            ],
            'plugins' => [],
            'themes' => [],
        ];

        foreach ($versions->getPlugins() as $slug => $section) {
            $data['plugins'][$slug] = [
                'version' => $section['version'] ?? null,
                'history' => $section['history'] ?? [],
            ];
        }
        foreach ($versions->getThemes() as $slug => $section) {
            $data['themes'][$slug] = [
                'version' => $section['version'] ?? null,
                'history' => $section['history'] ?? [],
            ];
        }

        return $this->respondWithEtag($data);
    }

  /gpm/versions:
    get:
      operationId: getVersions
      tags: [GPM]
      summary: Installed versions and recorded update history
      description: |
        Installed version and recorded {version, date} history for Grav core,
        all installed plugins and all installed themes, sourced from
        user/config/versions.yaml. History starts accumulating at the release
        that introduced recording; there is no backfill. Requires
        `api.gpm.read` permission.
      responses:
        "200":
          description: Version map.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VersionsMap"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"

    VersionsMap:
      type: object
      properties:
        grav:
          $ref: "#/components/schemas/VersionedPackage"
        plugins:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/VersionedPackage"
        themes:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/VersionedPackage"
    VersionedPackage:
      type: object
      properties:
        version:
          type: string
          nullable: true
        history:
          $ref: "#/components/schemas/VersionHistory"
    VersionHistory:
      type: array
      items:
        type: object
        properties:
          version:
            type: string
          date:
            type: string
            description: UTC, Y-m-d H:i:s.

export interface VersionEntry {
	version: string;
	date: string;
}

export interface VersionedPackage {
	version: string | null;
	history: VersionEntry[];
}

export interface VersionsResponse {
	grav: VersionedPackage;
	plugins: Record<string, VersionedPackage>;
	themes: Record<string, VersionedPackage>;
}

/**
 * Installed versions and their recorded update history (source:
 * user/config/versions.yaml on the server).
 */
export async function getVersions(): Promise<VersionsResponse> {
	return api.get<VersionsResponse>('/gpm/versions');
}

const versions = await getVersions();
const versionHistory = versions.plugins[slug]?.history ?? [];

<section class="mt-6">
	<h2 class="text-sm font-semibold text-foreground">{i18n.t('ADMIN_NEXT.PLUGINS.VERSION_HISTORY')}</h2>
	{#if versionHistory.length > 0}
		<ul class="mt-2 space-y-1 text-sm text-muted-foreground">
			{#each versionHistory as entry}
				<li>v{entry.version} — {entry.date} UTC</li>
			{/each}
		</ul>
	{:else}
		<p class="mt-2 text-sm text-muted-foreground">{i18n.t('ADMIN_NEXT.PLUGINS.NO_VERSION_HISTORY')}</p>
	{/if}
</section>

      CHANGELOG: Changelog
      VERSION_HISTORY: Version history
      NO_VERSION_HISTORY: No version history recorded yet.