From d2d290f9293b81fab03198652ede21fcacfd1eb0 Mon Sep 17 00:00:00 2001
From: strandedturtle <strandedtourtle@gmail.com>
Date: Fri, 26 Jun 2026 07:14:10 +0000
Subject: [PATCH] Phase 4: best-effort changelog "what's changed" panel

New changelog.js resolves release notes for a container's image:
- if the image's OCI source label points at GitHub, fetch recent releases
  and show those newer than the running version (heuristic walk, capped);
- otherwise link out to the source, Docker Hub tags, or GHCR repo.

Parsing/selection helpers (parseGitHubRepo, selectNewerReleases,
buildRegistryLink) are pure and unit-tested; only the GitHub fetch hits the
network. GET /api/changelog/:name resolves the container's image + version +
source via a new docker.getContainerImageMeta and caches per image+version
(10 min). Each update card gains a lazy "What's changed" panel rendering
release notes (as escaped plain text) or a link-out.

Server tests 73/73; client builds clean.
---
 client/src/api.js                    |   4 +
 client/src/components/UpdateCard.jsx |  98 ++++++++++++++++++-
 client/src/styles/app.css            |  58 +++++++++++
 server/src/changelog.js              | 138 +++++++++++++++++++++++++++
 server/src/docker.js                 |  15 +++
 server/src/routes/api.js             |  32 ++++++-
 server/test/changelog.test.js        |  53 ++++++++++
 7 files changed, 393 insertions(+), 5 deletions(-)
 create mode 100644 server/src/changelog.js
 create mode 100644 server/test/changelog.test.js

diff --git a/client/src/api.js b/client/src/api.js
index cc58bb5..29c9244 100644
--- a/client/src/api.js
+++ b/client/src/api.js
@@ -125,4 +125,8 @@ export function testNotify(url) {
   return post('/notify/test', url ? { url } : {});
 }
 
+export function getChangelog(name) {
+  return get(`/changelog/${encodeURIComponent(name)}`);
+}
+
 export { ApiError };
diff --git a/client/src/components/UpdateCard.jsx b/client/src/components/UpdateCard.jsx
index aebdbba..b95ac3d 100644
--- a/client/src/components/UpdateCard.jsx
+++ b/client/src/components/UpdateCard.jsx
@@ -1,5 +1,5 @@
 import React, { useCallback, useEffect, useState } from 'react';
-import { pin, unpin } from '../api.js';
+import { pin, unpin, getChangelog } from '../api.js';
 import { useUpdateRunner } from '../hooks/useUpdateRunner.js';
 import StatusMessage from './StatusMessage.jsx';
 import StreamLog from './StreamLog.jsx';
@@ -57,10 +57,61 @@ const ExternalIcon = () => (
   </svg>
 );
 
+// Renders a resolved changelog payload (GitHub release notes, a link-out, or
+// nothing). Release bodies render as plain text (React escapes — no XSS).
+function ChangelogContent({ data }) {
+  if (data.type === 'github') {
+    if (!data.releases.length) {
+      return (
+        <p className="changelog-empty">
+          No newer release notes found.{' '}
+          <a href={data.releasesUrl} target="_blank" rel="noopener noreferrer">
+            View releases
+          </a>
+        </p>
+      );
+    }
+    return (
+      <div className="changelog-releases">
+        {data.releases.map((r) => (
+          <div className="changelog-release" key={`${r.tag}-${r.url}`}>
+            <div className="changelog-release-head">
+              <a href={r.url} target="_blank" rel="noopener noreferrer">
+                {r.name || r.tag}
+              </a>
+              {r.publishedAt && (
+                <span className="changelog-date">
+                  {new Date(r.publishedAt).toLocaleDateString()}
+                </span>
+              )}
+            </div>
+            {r.body && <pre className="changelog-body">{r.body}</pre>}
+          </div>
+        ))}
+        <a className="card-link" href={data.releasesUrl} target="_blank" rel="noopener noreferrer">
+          All releases
+          <ExternalIcon />
+        </a>
+      </div>
+    );
+  }
+  if (data.type === 'link') {
+    return (
+      <p className="changelog-empty">
+        {data.note ? `${data.note} ` : ''}
+        <a href={data.url} target="_blank" rel="noopener noreferrer">
+          {data.label || 'Open'}
+        </a>
+      </p>
+    );
+  }
+  return <p className="changelog-empty">No changelog source available for this image.</p>;
+}
+
 /**
- * A single container's card: identity, version, source/changelog link, pin +
- * hide controls, update button, and an expandable live log for the in-flight
- * (or most recent) update.
+ * A single container's card: identity, version, source/changelog link, pin
+ * control, update button, an expandable "What's changed" panel, and an
+ * expandable live log for the in-flight (or most recent) update.
  *
  * props:
  *  - container: item shape from GET /api/containers
@@ -75,6 +126,11 @@ export default function UpdateCard({ container, onSettled, onPinChange, register
   const [pinBusy, setPinBusy] = useState(false);
   const [actionError, setActionError] = useState('');
 
+  const [clOpen, setClOpen] = useState(false);
+  const [clLoading, setClLoading] = useState(false);
+  const [clData, setClData] = useState(null);
+  const [clError, setClError] = useState('');
+
   const { run, busy, startError, status, lines } = useUpdateRunner(name, onSettled);
 
   useEffect(() => {
@@ -106,6 +162,23 @@ export default function UpdateCard({ container, onSettled, onPinChange, register
     }
   }, [pinned, image, onPinChange]);
 
+  const toggleChangelog = useCallback(async () => {
+    const next = !clOpen;
+    setClOpen(next);
+    if (next && !clData && !clLoading) {
+      setClLoading(true);
+      setClError('');
+      try {
+        const d = await getChangelog(name);
+        setClData(d);
+      } catch (err) {
+        setClError(err.message || 'Failed to load changelog');
+      } finally {
+        setClLoading(false);
+      }
+    }
+  }, [clOpen, clData, clLoading, name]);
+
   const showUpdateAvailable = updateAvailable && !pinned;
   const link = sourceLink(sourceUrl);
 
@@ -170,6 +243,11 @@ export default function UpdateCard({ container, onSettled, onPinChange, register
               <ExternalIcon />
             </a>
           )}
+          {showUpdateAvailable && (
+            <button type="button" className="btn-ghost" onClick={toggleChangelog} aria-expanded={clOpen}>
+              {clOpen ? 'Hide changes' : "What's changed"}
+            </button>
+          )}
         </div>
         <button
           type="button"
@@ -182,6 +260,18 @@ export default function UpdateCard({ container, onSettled, onPinChange, register
         </button>
       </div>
 
+      {clOpen && (
+        <div className="changelog-panel">
+          {clLoading && (
+            <div className="changelog-loading">
+              <span className="spinner" aria-hidden="true" /> Loading release notes…
+            </div>
+          )}
+          {!clLoading && clError && <StatusMessage type="error" message={clError} />}
+          {!clLoading && !clError && clData && <ChangelogContent data={clData} />}
+        </div>
+      )}
+
       <StreamLog lines={lines} />
     </div>
   );
diff --git a/client/src/styles/app.css b/client/src/styles/app.css
index 81255c6..258554b 100644
--- a/client/src/styles/app.css
+++ b/client/src/styles/app.css
@@ -1213,3 +1213,61 @@ a {
   font-size: 0.82rem;
   color: var(--color-text-muted);
 }
+
+/* ---------- Changelog panel (Phase 4) ---------- */
+
+.changelog-panel {
+  margin-top: 10px;
+  padding: 10px 12px;
+  background: var(--color-bg);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+}
+
+.changelog-loading {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--color-text-muted);
+  font-size: 0.85rem;
+}
+
+.changelog-empty {
+  margin: 0;
+  font-size: 0.85rem;
+  color: var(--color-text-muted);
+}
+
+.changelog-releases {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.changelog-release-head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+  font-weight: 700;
+  font-size: 0.9rem;
+}
+
+.changelog-date {
+  flex-shrink: 0;
+  font-weight: 500;
+  font-size: 0.75rem;
+  color: var(--color-text-faint);
+}
+
+.changelog-body {
+  margin: 6px 0 0;
+  white-space: pre-wrap;
+  word-break: break-word;
+  font-family: inherit;
+  font-size: 0.82rem;
+  line-height: 1.45;
+  color: var(--color-text-muted);
+  max-height: 240px;
+  overflow-y: auto;
+}
diff --git a/server/src/changelog.js b/server/src/changelog.js
new file mode 100644
index 0000000..f944c0a
--- /dev/null
+++ b/server/src/changelog.js
@@ -0,0 +1,138 @@
+/**
+ * Best-effort changelog resolver. Given an image's source label + current
+ * version, fetch GitHub release notes newer than what's running, or fall back
+ * to a "where to look" link (the source URL, Docker Hub tags, GHCR repo).
+ *
+ * The parsing/selection helpers are pure (unit-tested); only fetchGitHubReleases
+ * touches the network.
+ */
+
+import { parseRef } from './reconcile.js';
+
+/**
+ * Extract {owner, repo} from a GitHub URL, or null.
+ * @param {string|null} sourceUrl
+ * @returns {{owner: string, repo: string}|null}
+ */
+export function parseGitHubRepo(sourceUrl) {
+  if (typeof sourceUrl !== 'string') return null;
+  const m = sourceUrl.match(/github\.com[/:]([^/]+)\/([^/#?]+)/i);
+  if (!m) return null;
+  const owner = m[1];
+  const repo = m[2].replace(/\.git$/i, '');
+  if (!owner || !repo) return null;
+  return { owner, repo };
+}
+
+function normalizeVer(v) {
+  return String(v || '').trim().replace(/^v/i, '');
+}
+
+function truncate(s, n) {
+  if (typeof s !== 'string') return '';
+  return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+
+/**
+ * From a newest-first list of releases, pick those newer than currentVersion.
+ * Heuristic: walk from newest until we hit the release matching the running
+ * version; if we never match, show the most recent few. Pure + testable.
+ *
+ * @param {Array<{tag_name?: string, name?: string}>} releases
+ * @param {string|null} currentVersion
+ * @returns {Array<object>}
+ */
+export function selectNewerReleases(releases, currentVersion) {
+  if (!Array.isArray(releases)) return [];
+  if (!currentVersion) return releases.slice(0, 5);
+  const cur = normalizeVer(currentVersion);
+  const out = [];
+  for (const r of releases) {
+    const tag = normalizeVer(r.tag_name || r.name || '');
+    if (tag && tag === cur) break; // reached the running version
+    out.push(r);
+    if (out.length >= 10) break;
+  }
+  return out;
+}
+
+/**
+ * Best-effort "where to look" link for an image with no GitHub source label.
+ * @param {string} image
+ * @returns {{url: string, label: string}|null}
+ */
+export function buildRegistryLink(image) {
+  let parsed;
+  try {
+    parsed = parseRef(image);
+  } catch {
+    return null;
+  }
+  const { registry, repository } = parsed;
+  if (registry === 'docker.io') {
+    if (repository.startsWith('library/')) {
+      return { url: `https://hub.docker.com/_/${repository.slice('library/'.length)}`, label: 'Docker Hub' };
+    }
+    return { url: `https://hub.docker.com/r/${repository}/tags`, label: 'Docker Hub' };
+  }
+  if (registry === 'ghcr.io') {
+    return { url: `https://github.com/${repository}`, label: 'GitHub' };
+  }
+  return null;
+}
+
+async function fetchGitHubReleases(owner, repo, timeoutMs = 10000) {
+  const url = `https://api.github.com/repos/${owner}/${repo}/releases?per_page=30`;
+  const res = await fetch(url, {
+    headers: {
+      Accept: 'application/vnd.github+json',
+      'User-Agent': 'diun-updater',
+    },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) throw new Error(`GitHub API ${res.status}`);
+  return res.json();
+}
+
+/**
+ * Resolve a changelog payload for a container's image.
+ *
+ * @param {{ image: string, sourceUrl: string|null, currentVersion: string|null }} meta
+ * @returns {Promise<object>}
+ */
+export async function getChangelog({ image, sourceUrl, currentVersion }) {
+  const gh = parseGitHubRepo(sourceUrl);
+  if (gh) {
+    const releasesUrl = `https://github.com/${gh.owner}/${gh.repo}/releases`;
+    try {
+      const releases = await fetchGitHubReleases(gh.owner, gh.repo);
+      const selected = selectNewerReleases(releases, currentVersion);
+      return {
+        type: 'github',
+        repoUrl: `https://github.com/${gh.owner}/${gh.repo}`,
+        releasesUrl,
+        currentVersion: currentVersion || null,
+        releases: selected.map((r) => ({
+          tag: r.tag_name || r.name || '',
+          name: r.name || r.tag_name || '',
+          url: r.html_url,
+          publishedAt: r.published_at,
+          body: truncate(r.body || '', 1500),
+        })),
+      };
+    } catch (err) {
+      return {
+        type: 'link',
+        url: releasesUrl,
+        label: 'Releases',
+        note: `Couldn't fetch release notes (${err.message}).`,
+      };
+    }
+  }
+  if (sourceUrl) return { type: 'link', url: sourceUrl, label: 'Source' };
+  const reg = buildRegistryLink(image);
+  if (reg) return { type: 'link', url: reg.url, label: reg.label };
+  return { type: 'none' };
+}
+
+export default { parseGitHubRepo, selectNewerReleases, buildRegistryLink, getChangelog };
diff --git a/server/src/docker.js b/server/src/docker.js
index b47d9d9..06b0fcc 100644
--- a/server/src/docker.js
+++ b/server/src/docker.js
@@ -647,4 +647,19 @@ export async function updateContainer(name, onLine) {
   };
 }
 
+/**
+ * Lightweight per-container image metadata for the changelog endpoint:
+ * the configured image ref plus its OCI version + source labels.
+ *
+ * @param {string} name
+ * @returns {Promise<{ image: string|null, currentVersion: string|null, sourceUrl: string|null }>}
+ */
+export async function getContainerImageMeta(name) {
+  const inspectData = await docker.getContainer(name).inspect();
+  const image = inspectData.Config?.Image || null;
+  if (!image) return { image: null, currentVersion: null, sourceUrl: null };
+  const { version, source } = await inspectImageMeta(inspectData.Image, image);
+  return { image, currentVersion: version, sourceUrl: source };
+}
+
 export { docker };
diff --git a/server/src/routes/api.js b/server/src/routes/api.js
index 7c010c8..5fb01d5 100644
--- a/server/src/routes/api.js
+++ b/server/src/routes/api.js
@@ -8,7 +8,7 @@
  */
 
 import express from 'express';
-import { listContainers } from '../docker.js';
+import { listContainers, getContainerImageMeta } from '../docker.js';
 import { buildContainerItems } from '../containers-service.js';
 import { normalizeRef } from '../reconcile.js';
 import { runCheck } from '../checker.js';
@@ -16,6 +16,7 @@ import { subscribeGlobal, broadcastGlobal } from '../sse.js';
 import { getSettings, updateSettings } from '../settings.js';
 import scheduler from '../scheduler.js';
 import { sendDiscordTest } from '../notify.js';
+import { getChangelog } from '../changelog.js';
 import * as db from '../db.js';
 
 export const apiRouter = express.Router();
@@ -161,4 +162,33 @@ apiRouter.post('/api/notify/test', async (req, res) => {
   }
 });
 
+// Best-effort changelog for a container's image (GitHub releases newer than
+// the running version, or a link-out). Cached briefly per image+version.
+const changelogCache = new Map(); // key -> { at, data }
+const CHANGELOG_TTL_MS = 10 * 60 * 1000;
+
+apiRouter.get('/api/changelog/:name', async (req, res) => {
+  let meta;
+  try {
+    meta = await getContainerImageMeta(req.params.name);
+  } catch (err) {
+    if (err.statusCode === 404) return res.status(404).json({ error: 'not_found' });
+    return res.status(503).json({ error: 'docker_unavailable', message: err.message });
+  }
+  if (!meta.image) return res.status(404).json({ error: 'not_found' });
+
+  const key = `${meta.image}|${meta.currentVersion || ''}`;
+  const cached = changelogCache.get(key);
+  if (cached && Date.now() - cached.at < CHANGELOG_TTL_MS) {
+    return res.status(200).json(cached.data);
+  }
+  try {
+    const data = await getChangelog(meta);
+    changelogCache.set(key, { at: Date.now(), data });
+    return res.status(200).json(data);
+  } catch (err) {
+    return res.status(502).json({ error: 'changelog_failed', message: err.message });
+  }
+});
+
 export default apiRouter;
diff --git a/server/test/changelog.test.js b/server/test/changelog.test.js
new file mode 100644
index 0000000..9d5f15e
--- /dev/null
+++ b/server/test/changelog.test.js
@@ -0,0 +1,53 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseGitHubRepo, selectNewerReleases, buildRegistryLink } from '../src/changelog.js';
+
+test('parseGitHubRepo: extracts owner/repo, strips .git', () => {
+  assert.deepEqual(parseGitHubRepo('https://github.com/jellyfin/jellyfin'), {
+    owner: 'jellyfin',
+    repo: 'jellyfin',
+  });
+  assert.deepEqual(parseGitHubRepo('git+https://github.com/foo/bar.git'), {
+    owner: 'foo',
+    repo: 'bar',
+  });
+  assert.equal(parseGitHubRepo('https://gitlab.com/foo/bar'), null);
+  assert.equal(parseGitHubRepo(null), null);
+});
+
+test('selectNewerReleases: returns releases newer than current version', () => {
+  const releases = [
+    { tag_name: 'v3.0.0' },
+    { tag_name: 'v2.1.0' },
+    { tag_name: 'v2.0.0' },
+    { tag_name: 'v1.0.0' },
+  ];
+  // running 2.0.0 -> show 3.0.0 and 2.1.0 (stops at the match)
+  const out = selectNewerReleases(releases, '2.0.0');
+  assert.deepEqual(out.map((r) => r.tag_name), ['v3.0.0', 'v2.1.0']);
+});
+
+test('selectNewerReleases: up to date -> empty', () => {
+  const releases = [{ tag_name: 'v2.0.0' }, { tag_name: 'v1.0.0' }];
+  assert.deepEqual(selectNewerReleases(releases, 'v2.0.0'), []);
+});
+
+test('selectNewerReleases: unknown current version -> recent few', () => {
+  const releases = [{ tag_name: 'a' }, { tag_name: 'b' }, { tag_name: 'c' }];
+  assert.equal(selectNewerReleases(releases, null).length, 3);
+});
+
+test('buildRegistryLink: docker hub official + namespaced, ghcr', () => {
+  assert.deepEqual(buildRegistryLink('nginx:latest'), {
+    url: 'https://hub.docker.com/_/nginx',
+    label: 'Docker Hub',
+  });
+  assert.deepEqual(buildRegistryLink('linuxserver/sonarr:latest'), {
+    url: 'https://hub.docker.com/r/linuxserver/sonarr/tags',
+    label: 'Docker Hub',
+  });
+  assert.deepEqual(buildRegistryLink('ghcr.io/foo/bar:1.0'), {
+    url: 'https://github.com/foo/bar',
+    label: 'GitHub',
+  });
+});