feat(updates): "What's new" dialog + optional automatic self-update

Two complementary features around the existing self-update path:

What's new — after a build is deployed, every signed-in user sees a
one-time dialog with the release notes for everything that changed since
the build they last acknowledged. Notes are Markdown generated from the
commit messages (bookkeeping trailers stripped) and rendered with the
in-app Markdown pipeline. Tracked per user via User.lastSeenVersion, so
it shows exactly once per update and never replays history to new users.

Automatic updates — an opt-in global setting (Setting.autoUpdateEnabled)
makes the instance check GitHub a few times a day and apply a newer build
automatically, reusing the health-checked, auto-rollback self-update.
Off by default, requires SELF_UPDATE_ENABLED, backs off for a day after a
failed attempt so a persistent failure can't loop. Toggle lives in the
admin Update panel.

- API: GET /version/whats-new (+ /seen) for any user; getChangelog /
  getRecentChangelog in the version service; startAutoUpdate scheduler
  wired into the boot/shutdown lifecycle; autoUpdateEnabled surfaced and
  editable via /admin/version and /admin/settings.
- Web: WhatsNew modal mounted in the app shell; auto-update switch in the
  admin Update panel. FR/EN i18n at parity.
- Tests: integration coverage for the first-contact-silent → show-once →
  dismissed lifecycle.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WNvAeoRFGJkRnaBGwMstZ9

Author: softpython2884

README.md

@@ -38,7 +38,8 @@ the source.
   opt-in zero-knowledge vault whose contents are encrypted in the browser and never
   readable by the server.
 - **Administration** — create users, set per-user quotas, define the global cap, manage
-  Quick-Upload codes and read the audit log.
+  Quick-Upload codes and read the audit log. One-click (or **automatic**) self-update from
+  GitHub, with a "What's new" dialog that shows each user the release notes once per update.
 
 ## Architecture
 

apps/api/prisma/migrations/20260623160000_whats_new_and_auto_update/migration.sql

@@ -0,0 +1,5 @@
+-- AlterTable
+ALTER TABLE "User" ADD COLUMN "lastSeenVersion" TEXT;
+
+-- AlterTable
+ALTER TABLE "Setting" ADD COLUMN "autoUpdateEnabled" BOOLEAN NOT NULL DEFAULT false;

apps/api/prisma/schema.prisma

@@ -69,6 +69,9 @@ model User {
   lastLoginAt  DateTime?
   // If set, a daily job permanently deletes the user's files after this many days without a login.
   autoDeleteAfterDays Int?
+  // The build (git SHA) for which this user last dismissed the "What's new" dialog. null until
+  // they first load the app; lets us show release notes exactly once per update, per user.
+  lastSeenVersion String?
   createdAt    DateTime @default(now())
   updatedAt    DateTime @updatedAt
 
@@ -331,6 +334,9 @@ model Setting {
   globalStorageCapBytes BigInt  @default(0)
   // Optional VirusTotal API key set from the admin panel; overrides VIRUSTOTAL_API_KEY in .env.
   virustotalApiKey     String?
+  // When true, the instance checks GitHub periodically and applies a newer build automatically
+  // (requires SELF_UPDATE_ENABLED). Off by default — auto-applying code is opt-in.
+  autoUpdateEnabled    Boolean  @default(false)
   updatedAt            DateTime @updatedAt
 }
 

apps/api/src/index.ts

@@ -7,6 +7,7 @@ import { createContext } from './context.js';
 import { buildServer } from './server.js';
 import { startRemoteWorker } from './worker/remote-worker.js';
 import { startMaintenance } from './services/maintenance.js';
+import { startAutoUpdate } from './services/autoUpdate.js';
 import { prisma } from './db.js';
 
 // Prefer IPv4 when resolving outbound hosts. Some self-hosted boxes advertise IPv6 but have
@@ -31,11 +32,13 @@ async function main(): Promise<void> {
   const app = await buildServer(ctx);
   const stopWorker = startRemoteWorker(ctx, app.log);
   const stopMaintenance = startMaintenance(ctx, app.log);
+  const stopAutoUpdate = startAutoUpdate(ctx, app.log);
 
   const shutdown = async (signal: string) => {
     app.log.info({ signal }, 'shutting down');
     stopWorker();
     stopMaintenance();
+    stopAutoUpdate();
     await app.close();
     await prisma.$disconnect();
     process.exit(0);

apps/api/src/routes/admin.ts

@@ -157,12 +157,16 @@ export const adminRoutes: FastifyPluginAsync = async (app) => {
     const { check } = req.query as { check?: string };
     const local = await getLocalVersion();
     const status = readUpdateStatus();
+    const setting = await prisma.setting
+      .findUnique({ where: { id: GLOBAL_SETTING_ID }, select: { autoUpdateEnabled: true } })
+      .catch(() => null);
     const base = {
       current: local,
       status,
       // True when a "running" status is actually stuck (so the UI can offer a relaunch).
       stuck: isUpdateStuck(status),
       selfUpdateEnabled: app.ctx.env.SELF_UPDATE_ENABLED,
+      autoUpdateEnabled: setting?.autoUpdateEnabled ?? false,
       repo: app.ctx.env.GITHUB_REPO,
       branch: app.ctx.env.UPDATE_BRANCH,
     };
@@ -205,9 +209,10 @@ export const adminRoutes: FastifyPluginAsync = async (app) => {
     if (!body) return;
     // Build the update from only the provided fields, so the VT key and the cap can be saved
     // independently from their own forms.
-    const data: { globalStorageCapBytes?: bigint; virustotalApiKey?: string | null } = {};
+    const data: { globalStorageCapBytes?: bigint; virustotalApiKey?: string | null; autoUpdateEnabled?: boolean } = {};
     if (body.globalStorageCapBytes !== undefined) data.globalStorageCapBytes = BigInt(body.globalStorageCapBytes);
     if (body.virustotalApiKey !== undefined) data.virustotalApiKey = body.virustotalApiKey.trim() || null;
+    if (body.autoUpdateEnabled !== undefined) data.autoUpdateEnabled = body.autoUpdateEnabled;
 
     const setting = await prisma.setting.upsert({
       where: { id: GLOBAL_SETTING_ID },
@@ -223,6 +228,7 @@ export const adminRoutes: FastifyPluginAsync = async (app) => {
     return {
       globalStorageCapBytes: Number(setting.globalStorageCapBytes),
       virustotalConfigured: app.ctx.virustotal.enabled,
+      autoUpdateEnabled: setting.autoUpdateEnabled,
     };
   });
 

apps/api/src/routes/version.ts

@@ -0,0 +1,52 @@
+/**
+ * User-facing build info: the "What's new" dialog shown once per update, to every user (not just
+ * admins). The current build is the checked-out git SHA; each user's `lastSeenVersion` records
+ * the build they last acknowledged, so we can surface the release notes for everything that
+ * changed since — exactly once.
+ */
+import type { FastifyPluginAsync } from 'fastify';
+import { prisma } from '../db.js';
+import { getChangelog, getLocalVersion, getRecentChangelog } from '../services/version.js';
+
+export const versionRoutes: FastifyPluginAsync = async (app) => {
+  app.addHook('preHandler', app.requireAuth);
+
+  // GET /version/whats-new — release notes since the user's last acknowledged build, or
+  // { show: false } when there is nothing new (or this isn't a git deployment).
+  app.get('/whats-new', async (req) => {
+    const local = await getLocalVersion();
+    if (!local.isGit || !local.sha) return { show: false };
+
+    const user = await prisma.user.findUniqueOrThrow({
+      where: { id: req.user!.id },
+      select: { lastSeenVersion: true },
+    });
+    const seen = user.lastSeenVersion;
+
+    // First contact (new user, or upgrading from before this feature): remember the current
+    // build silently so we never dump the entire project history on them.
+    if (!seen) {
+      await prisma.user.update({ where: { id: req.user!.id }, data: { lastSeenVersion: local.sha } });
+      return { show: false };
+    }
+    if (seen === local.sha) return { show: false };
+
+    // Notes for seen..current; if `seen` is unreachable (force-push/rebase), fall back to the
+    // most recent commits so the user still sees something meaningful.
+    const log = (await getChangelog(seen, local.sha)) ?? (await getRecentChangelog(20));
+    if (!log) {
+      await prisma.user.update({ where: { id: req.user!.id }, data: { lastSeenVersion: local.sha } });
+      return { show: false };
+    }
+    return { show: true, version: local.shortSha, notes: log.markdown, count: log.count };
+  });
+
+  // POST /version/whats-new/seen — dismiss the dialog for the current build.
+  app.post('/whats-new/seen', async (req) => {
+    const local = await getLocalVersion();
+    if (local.sha) {
+      await prisma.user.update({ where: { id: req.user!.id }, data: { lastSeenVersion: local.sha } });
+    }
+    return { ok: true };
+  });
+};

apps/api/src/server.ts

@@ -17,6 +17,7 @@ import { quickRoutes } from './routes/quick.js';
 import { remoteRoutes } from './routes/remote.js';
 import { shareRoutes } from './routes/shares.js';
 import { spaceRoutes } from './routes/spaces.js';
+import { versionRoutes } from './routes/version.js';
 import { sharePublicRoutes } from './routes/share-public.js';
 import { twoFactorRoutes } from './routes/twofa.js';
 import { accountRoutes } from './routes/account.js';
@@ -97,6 +98,7 @@ export async function buildServer(ctx: AppContext): Promise<FastifyInstance> {
     await web.register(sharePublicRoutes, { prefix: '/s' });
     await web.register(twoFactorRoutes, { prefix: '/2fa' });
     await web.register(accountRoutes, { prefix: '/account' });
+    await web.register(versionRoutes, { prefix: '/version' });
     await web.register(adminRoutes, { prefix: '/admin' });
     await web.register(apiV1Routes, { prefix: '/api/v1' });
   });

apps/api/src/services/autoUpdate.ts

@@ -0,0 +1,55 @@
+/**
+ * Optional automatic self-update. When an admin enables it (Setting.autoUpdateEnabled) and the
+ * deployment allows self-update, the instance checks GitHub a few times a day and applies a newer
+ * build automatically — using the same health-checked, auto-rollback self-update path as the
+ * manual button. Off by default: auto-applying code is opt-in.
+ */
+import type { FastifyBaseLogger } from 'fastify';
+import type { AppContext } from '../context.js';
+import { prisma } from '../db.js';
+import { getLocalVersion, getRemoteVersion, isUpdateStuck, readUpdateStatus, startUpdate } from './version.js';
+
+// Check a few times a day — frequent enough to pick up releases promptly, light on the GitHub
+// rate limit. The first check runs shortly after boot.
+const CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
+const KICKOFF_MS = 5 * 60 * 1000;
+// After a failed update, wait a day before trying again so a persistent failure can't loop.
+const FAILED_BACKOFF_MS = 24 * 60 * 60 * 1000;
+
+export async function autoUpdateTick(ctx: AppContext, log: FastifyBaseLogger): Promise<void> {
+  if (!ctx.env.SELF_UPDATE_ENABLED) return;
+  const setting = await prisma.setting
+    .findUnique({ where: { id: 'global' }, select: { autoUpdateEnabled: true } })
+    .catch(() => null);
+  if (!setting?.autoUpdateEnabled) return;
+
+  const status = readUpdateStatus();
+  if (status.state === 'running' && !isUpdateStuck(status)) return; // already updating
+  if (status.state === 'failed' && status.finishedAt && Date.now() - Date.parse(status.finishedAt) < FAILED_BACKOFF_MS) {
+    return; // a recent failure needs a human look before we retry
+  }
+
+  const local = await getLocalVersion();
+  if (!local.isGit || !local.sha) return;
+  const remote = await getRemoteVersion(ctx.env);
+  if (!remote || remote.sha === local.sha) return; // up to date or GitHub unreachable
+
+  log.info({ from: local.shortSha, to: remote.shortSha }, 'auto-update: newer build available — applying');
+  const res = startUpdate(ctx.env);
+  if (!res.ok) log.warn({ error: res.error }, 'auto-update: could not start');
+}
+
+/** Schedule the periodic auto-update check. Returns a stop function for graceful shutdown. */
+export function startAutoUpdate(ctx: AppContext, log: FastifyBaseLogger): () => void {
+  let stopped = false;
+  const run = () => {
+    if (!stopped) void autoUpdateTick(ctx, log).catch((err) => log.error({ err }, 'auto-update tick failed'));
+  };
+  const timer = setInterval(run, CHECK_INTERVAL_MS);
+  const kickoff = setTimeout(run, KICKOFF_MS);
+  return () => {
+    stopped = true;
+    clearInterval(timer);
+    clearTimeout(kickoff);
+  };
+}

apps/api/src/services/version.ts

@@ -85,6 +85,78 @@ export async function getLocalVersion(): Promise<LocalVersion> {
   return cachedLocal;
 }
 
+// Trailer / footer lines we never want to show end users in the "What's new" notes.
+const NOISE_LINE = /^(Co-Authored-By|Claude-Session|Claude-[\w-]+|Signed-off-by|Reviewed-by):/i;
+
+/** Strip bookkeeping trailers and the generator footer from a commit body. */
+function cleanBody(body: string): string {
+  return body
+    .split('\n')
+    .filter((l) => !NOISE_LINE.test(l.trim()) && !/^🤖 Generated with/.test(l.trim()) && !/^https:\/\/claude\.ai/.test(l.trim()))
+    .join('\n')
+    .trim();
+}
+
+export interface Changelog {
+  /** Markdown ready to render in the "What's new" dialog. */
+  markdown: string;
+  /** Number of commits summarised (after capping). */
+  count: number;
+}
+
+// Beyond this many commits the notes get unwieldy; we summarise the newest and note the rest.
+const MAX_CHANGELOG_COMMITS = 40;
+
+/**
+ * Build human-readable release notes for the commits in `from..to` (newest first), as Markdown.
+ * Returns null when there is nothing to show or git can't produce a range (e.g. a force-push made
+ * `from` unreachable — the caller falls back to the most recent commits instead).
+ */
+export async function getChangelog(from: string, to: string): Promise<Changelog | null> {
+  if (!repoRoot || from === to) return null;
+  // %x1e separates commits, %x1f separates subject from body within a commit.
+  const fmt = '--format=%s%x1f%b%x1e';
+  let stdout: string;
+  try {
+    const res = await exec('git', ['log', fmt, `${from}..${to}`], { cwd: repoRoot, maxBuffer: 8 * 1024 * 1024 });
+    stdout = res.stdout;
+  } catch {
+    return null; // `from` not reachable — caller decides on a fallback
+  }
+  return renderChangelog(stdout);
+}
+
+/** The most recent `n` commits as Markdown — a fallback when the range can't be computed. */
+export async function getRecentChangelog(n: number): Promise<Changelog | null> {
+  if (!repoRoot) return null;
+  try {
+    const { stdout } = await exec('git', ['log', `-${n}`, '--format=%s%x1f%b%x1e'], { cwd: repoRoot, maxBuffer: 8 * 1024 * 1024 });
+    return renderChangelog(stdout);
+  } catch {
+    return null;
+  }
+}
+
+function renderChangelog(raw: string): Changelog | null {
+  const commits = raw
+    .split('\x1e')
+    .map((c) => c.trim())
+    .filter(Boolean)
+    .map((c) => {
+      const [subject, ...rest] = c.split('\x1f');
+      return { subject: (subject ?? '').trim(), body: cleanBody(rest.join('\x1f')) };
+    })
+    .filter((c) => c.subject);
+  if (commits.length === 0) return null;
+
+  const shown = commits.slice(0, MAX_CHANGELOG_COMMITS);
+  const blocks = shown.map((c) => (c.body ? `### ${c.subject}\n\n${c.body}` : `### ${c.subject}`));
+  if (commits.length > shown.length) {
+    blocks.push(`_…and ${commits.length - shown.length} more change(s)._`);
+  }
+  return { markdown: blocks.join('\n\n'), count: commits.length };
+}
+
 interface GithubCommit {
   sha: string;
   html_url: string;

apps/api/test/integration.test.ts

@@ -844,6 +844,34 @@ runIf('API integration', () => {
     });
   });
 
+  describe("what's new", () => {
+    it('stays silent on first contact, then shows release notes once per build', async () => {
+      const user = await createUser({ email: 'wn@test.local', password: 'correct-horse-battery' });
+      const auth = await login(app, 'wn@test.local', 'correct-horse-battery');
+
+      // First load: nothing to show, and the current build is remembered silently.
+      const first = await app.inject({ method: 'GET', url: '/version/whats-new', headers: { cookie: auth.cookie } });
+      expect(first.statusCode).toBe(200);
+      expect(first.json().show).toBe(false);
+      const afterFirst = await prisma.user.findUniqueOrThrow({ where: { id: user.id } });
+      // The test checkout is a git repo, so a build SHA was recorded.
+      expect(afterFirst.lastSeenVersion).toBeTruthy();
+
+      // Simulate having last seen an older build → notes appear (range falls back to recent commits).
+      await prisma.user.update({ where: { id: user.id }, data: { lastSeenVersion: 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeef' } });
+      const shown = await app.inject({ method: 'GET', url: '/version/whats-new', headers: { cookie: auth.cookie } });
+      expect(shown.json().show).toBe(true);
+      expect(typeof shown.json().notes).toBe('string');
+      expect(shown.json().notes.length).toBeGreaterThan(0);
+
+      // Dismissing records the current build, so it never shows again for this version.
+      const seen = await app.inject({ method: 'POST', url: '/version/whats-new/seen', headers: authHeaders(auth) });
+      expect(seen.statusCode).toBe(200);
+      const again = await app.inject({ method: 'GET', url: '/version/whats-new', headers: { cookie: auth.cookie } });
+      expect(again.json().show).toBe(false);
+    });
+  });
+
   describe('admin maintenance', () => {
     it('reconciles a drifted usedBytes counter', async () => {
       const admin = await createUser({