feat(admin+spaces): version rollback, post-update reload, openable space files

Admin rollback — a "Previous versions" panel lists recent commits and can
restore the deployment to any earlier one. It reuses the self-update path
(GET /admin/version/history, POST /admin/rollback with an ancestor-only
SHA guard; self-update.sh honours UPDATE_TARGET_REF) so the build,
health-check and auto-rollback-on-failure all apply.

Post-update reload — when an admin starts an update/rollback, the panel
reloads the page once it succeeds (the API is now on the new build), which
also surfaces the "What's new" dialog. The dialog stays silent after a
rollback (current build is an ancestor of what the user last saw).

Shared Spaces: open & edit files — space files now open in the in-app
viewer (image/PDF/audio/video/text/markdown/html); editors get an editable
text surface that re-uploads in place (versioned), mirroring the Drive.

Docs — in-app docs gain a "Shared Spaces" section and updated "Updates"
notes (auto-update, rollback, What's new); API.md clarifies that vaults and
shared spaces are out of scope for the token REST API / WebDAV.

Author: softpython2884

apps/api/src/routes/admin.ts

@@ -17,6 +17,8 @@ import {
   commitsBehind,
   getLocalVersion,
   getRemoteVersion,
+  getVersionHistory,
+  isAncestor,
   isUpdateStuck,
   readUpdateStatus,
   startUpdate,
@@ -187,6 +189,37 @@ export const adminRoutes: FastifyPluginAsync = async (app) => {
     return reply.code(202).send({ ok: true });
   });
 
+  // GET /admin/version/history — recent commits on the checkout, as rollback candidates.
+  app.get('/version/history', async () => {
+    const [history, local] = await Promise.all([getVersionHistory(15), getLocalVersion()]);
+    return { history, currentSha: local.sha };
+  });
+
+  // POST /admin/rollback — roll the deployment back to a previous commit. The target must be a
+  // known ancestor of the current build (so this can only go BACKWARDS to a version that ran
+  // here), and the same health-checked, auto-rollback path as a forward update is used.
+  app.post('/rollback', async (req, reply) => {
+    const body = (req.body ?? {}) as { sha?: unknown };
+    const sha = typeof body.sha === 'string' ? body.sha.trim() : '';
+    if (!/^[0-9a-f]{7,40}$/.test(sha)) return reply.code(400).send({ error: 'A valid commit SHA is required' });
+
+    const local = await getLocalVersion();
+    if (!local.sha) return reply.code(400).send({ error: 'This deployment is not a git checkout' });
+    if (local.sha === sha || local.shortSha === sha) {
+      return reply.code(400).send({ error: 'That is already the running version' });
+    }
+    // Only allow rolling back to a commit that is an ancestor of HEAD (a version that ran here),
+    // never to arbitrary or future refs.
+    if (!(await isAncestor(sha, local.sha))) {
+      return reply.code(400).send({ error: 'Can only roll back to a previous version of this deployment' });
+    }
+
+    const result = startUpdate(app.ctx.env, sha);
+    if (!result.ok) return reply.code(409).send({ error: result.error });
+    await audit(req, 'admin.rollback.start', { target: sha });
+    return reply.code(202).send({ ok: true });
+  });
+
   // ── Maintenance (manual trigger) ─────────────────────────────────────────--
   app.post('/maintenance', async (req) => {
     const summary = await runMaintenance(app.ctx, req.log);

apps/api/src/routes/version.ts

@@ -6,7 +6,7 @@
  */
 import type { FastifyPluginAsync } from 'fastify';
 import { prisma } from '../db.js';
-import { getChangelog, getLocalVersion, getRecentChangelog } from '../services/version.js';
+import { getChangelog, getLocalVersion, getRecentChangelog, isAncestor } from '../services/version.js';
 
 export const versionRoutes: FastifyPluginAsync = async (app) => {
   app.addHook('preHandler', app.requireAuth);
@@ -31,6 +31,13 @@ export const versionRoutes: FastifyPluginAsync = async (app) => {
     }
     if (seen === local.sha) return { show: false };
 
+    // If the current build is an ancestor of what the user last saw, the deployment was rolled
+    // BACK — there is nothing "new" to announce, so just record the build silently.
+    if (await isAncestor(local.sha, seen)) {
+      await prisma.user.update({ where: { id: req.user!.id }, data: { lastSeenVersion: 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));

apps/api/src/services/version.ts

@@ -157,6 +157,42 @@ function renderChangelog(raw: string): Changelog | null {
   return { markdown: blocks.join('\n\n'), count: commits.length };
 }
 
+export interface HistoryCommit {
+  sha: string;
+  shortSha: string;
+  subject: string;
+  committedAt: string | null;
+}
+
+/** The most recent commits on the current checkout (newest first) — rollback candidates. */
+export async function getVersionHistory(n = 15): Promise<HistoryCommit[]> {
+  if (!repoRoot) return [];
+  try {
+    const { stdout } = await exec('git', ['log', `-${n}`, '--format=%H%x1f%h%x1f%cI%x1f%s'], { cwd: repoRoot });
+    return stdout
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map((l) => {
+        const [sha, shortSha, committedAt, subject] = l.split('\x1f');
+        return { sha: sha ?? '', shortSha: shortSha ?? '', committedAt: committedAt || null, subject: subject ?? '' };
+      });
+  } catch {
+    return [];
+  }
+}
+
+/** True when `ancestor` is an ancestor of `descendant` (git merge-base --is-ancestor exit 0). */
+export async function isAncestor(ancestor: string, descendant: string): Promise<boolean> {
+  if (!repoRoot) return false;
+  try {
+    await exec('git', ['merge-base', '--is-ancestor', ancestor, descendant], { cwd: repoRoot });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 interface GithubCommit {
   sha: string;
   html_url: string;
@@ -243,8 +279,12 @@ export function isUpdateStuck(status: UpdateStatus): boolean {
   return status.state === 'running' && status.startedAt !== null && Date.now() - Date.parse(status.startedAt) > STALE_RUNNING_MS;
 }
 
-/** Spawn the detached self-update script. It survives the PM2 reload it triggers. */
-export function startUpdate(env: Env): StartUpdateResult {
+/**
+ * Spawn the detached self-update script. It survives the PM2 reload it triggers. When `targetRef`
+ * is given, the checkout is reset to THAT commit (a rollback to a previous version) instead of the
+ * latest on the tracked branch — the build/health-check/auto-rollback safety net is identical.
+ */
+export function startUpdate(env: Env, targetRef?: string): StartUpdateResult {
   if (!env.SELF_UPDATE_ENABLED) return { ok: false, error: 'Self-update is disabled on this instance.' };
   if (!repoRoot) return { ok: false, error: 'This deployment is not a git checkout; update it manually.' };
   const current = readUpdateStatus();
@@ -281,7 +321,7 @@ export function startUpdate(env: Env): StartUpdateResult {
     cwd: repoRoot,
     detached: true,
     stdio: 'ignore',
-    env: { ...process.env, UPDATE_BRANCH: env.UPDATE_BRANCH },
+    env: { ...process.env, UPDATE_BRANCH: env.UPDATE_BRANCH, ...(targetRef ? { UPDATE_TARGET_REF: targetRef } : {}) },
   });
   child.unref();
   return { ok: true };

apps/api/test/integration.test.ts

@@ -872,6 +872,32 @@ runIf('API integration', () => {
     });
   });
 
+  describe('admin version history & rollback', () => {
+    it('lists history and validates rollback targets', async () => {
+      await createUser({ email: 'rb@test.local', password: 'correct-horse-battery', role: 'ADMIN' });
+      const auth = await login(app, 'rb@test.local', 'correct-horse-battery');
+
+      const hist = await app.inject({ method: 'GET', url: '/admin/version/history', headers: { cookie: auth.cookie } });
+      expect(hist.statusCode).toBe(200);
+      expect(Array.isArray(hist.json().history)).toBe(true);
+      const currentSha = hist.json().currentSha as string | null;
+
+      // A malformed SHA is rejected up front.
+      const bad = await app.inject({ method: 'POST', url: '/admin/rollback', headers: authHeaders(auth), payload: { sha: 'not-a-sha' } });
+      expect(bad.statusCode).toBe(400);
+
+      // A well-formed but unknown SHA isn't an ancestor of HEAD → refused (never goes forward/sideways).
+      const unknown = await app.inject({ method: 'POST', url: '/admin/rollback', headers: authHeaders(auth), payload: { sha: 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeef' } });
+      expect(unknown.statusCode).toBe(400);
+
+      // Rolling back to the version already running is a no-op error.
+      if (currentSha) {
+        const same = await app.inject({ method: 'POST', url: '/admin/rollback', headers: authHeaders(auth), payload: { sha: currentSha } });
+        expect(same.statusCode).toBe(400);
+      }
+    });
+  });
+
   describe('admin maintenance', () => {
     it('reconciles a drifted usedBytes counter', async () => {
       const admin = await createUser({

apps/web/src/app/(app)/admin/UpdatePanel.tsx

@@ -7,7 +7,7 @@
  * terminal state.
  */
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { GitCommitHorizontal, RefreshCw, Download, CheckCircle2, AlertTriangle, Loader2 } from 'lucide-react';
+import { GitCommitHorizontal, RefreshCw, Download, CheckCircle2, AlertTriangle, Loader2, History, RotateCcw } from 'lucide-react';
 import { api, ApiError } from '@/lib/api';
 import { useT } from '@/lib/i18n';
 import { confirm, toast } from '@/components/ui/overlays';
@@ -33,6 +33,12 @@ interface UpdateStatus {
   finishedAt: string | null;
   message: string | null;
 }
+interface HistoryCommit {
+  sha: string;
+  shortSha: string;
+  subject: string;
+  committedAt: string | null;
+}
 interface VersionInfo {
   current: LocalVersion;
   status: UpdateStatus;
@@ -52,7 +58,12 @@ export function UpdatePanel() {
   const [info, setInfo] = useState<VersionInfo | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [busy, setBusy] = useState<'check' | 'update' | null>(null);
+  const [history, setHistory] = useState<HistoryCommit[] | null>(null);
+  const [showHistory, setShowHistory] = useState(false);
   const pollRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  // Set when THIS admin starts an update/rollback, so we reload the page once it succeeds
+  // (the API has restarted on the new build) — which then surfaces the "What's new" dialog.
+  const initiated = useRef(false);
 
   const fetchVersion = useCallback(async (check: boolean) => {
     const res = await api.get<VersionInfo>(`/admin/version${check ? '?check=1' : ''}`);
@@ -100,6 +111,50 @@ export function UpdatePanel() {
     }
   }
 
+  // When an update/rollback this admin started finishes successfully, the API is now running the
+  // new build — reload so the browser fetches the new bundle (and the What's-new dialog appears).
+  useEffect(() => {
+    if (info?.status.state === 'success' && initiated.current) {
+      initiated.current = false;
+      toast(t('admin.updateReloading'), 'info');
+      const id = setTimeout(() => window.location.reload(), 1800);
+      return () => clearTimeout(id);
+    }
+  }, [info?.status.state, t]);
+
+  async function loadHistory() {
+    if (history) {
+      setShowHistory((s) => !s);
+      return;
+    }
+    try {
+      const res = await api.get<{ history: HistoryCommit[]; currentSha: string | null }>('/admin/version/history');
+      setHistory(res.history);
+      setShowHistory(true);
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : String(e));
+    }
+  }
+
+  async function rollback(commit: HistoryCommit) {
+    const ok = await confirm({
+      title: t('admin.rollbackConfirmTitle'),
+      message: t('admin.rollbackConfirmMsg', { sha: commit.shortSha, subject: commit.subject }),
+      confirmLabel: t('admin.rollbackConfirmBtn'),
+      danger: true,
+    });
+    if (!ok) return;
+    setError(null);
+    try {
+      await api.post('/admin/rollback', { sha: commit.sha });
+      initiated.current = true;
+      toast(t('admin.rollbackStarted'), 'info');
+      await fetchVersion(false);
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : String(e));
+    }
+  }
+
   async function toggleAuto() {
     if (!info) return;
     try {
@@ -121,6 +176,7 @@ export function UpdatePanel() {
     setError(null);
     try {
       await api.post('/admin/update');
+      initiated.current = true;
       toast(t('admin.updateStarted'), 'info');
       await fetchVersion(false);
     } catch (e) {
@@ -251,6 +307,51 @@ export function UpdatePanel() {
         </div>
       )}
 
+      {/* Version history / rollback */}
+      {selfUpdateEnabled && current.isGit && (
+        <div className="rounded-lg border border-white/[0.07] bg-white/[0.02]">
+          <button
+            type="button"
+            onClick={loadHistory}
+            className="flex w-full items-center justify-between gap-2 px-3 py-2.5 text-sm text-zinc-200"
+          >
+            <span className="flex items-center gap-2">
+              <History size={15} className="text-zinc-400" /> {t('admin.rollbackTitle')}
+            </span>
+            <span className="text-xs text-zinc-500">{showHistory ? t('admin.hide') : t('admin.show')}</span>
+          </button>
+          {showHistory && history && (
+            <div className="border-t border-white/[0.06] p-2">
+              <p className="px-1 pb-2 text-xs text-zinc-500">{t('admin.rollbackHint')}</p>
+              <div className="space-y-1">
+                {history.map((c) => {
+                  const isCurrent = c.sha === current.sha;
+                  return (
+                    <div key={c.sha} className="flex items-center gap-3 rounded-md px-2 py-1.5 hover:bg-white/[0.03]">
+                      <code className="shrink-0 font-mono text-xs text-zinc-400">{c.shortSha}</code>
+                      <span className="min-w-0 flex-1 truncate text-xs text-zinc-300">{c.subject}</span>
+                      {isCurrent ? (
+                        <span className="shrink-0 rounded-full bg-emerald-400/10 px-2 py-0.5 text-[11px] text-emerald-300">
+                          {t('admin.rollbackCurrent')}
+                        </span>
+                      ) : (
+                        <button
+                          className="btn-ghost shrink-0 px-2 py-1 text-xs"
+                          onClick={() => rollback(c)}
+                          disabled={busy !== null || running}
+                        >
+                          <RotateCcw size={13} /> {t('admin.rollbackTo')}
+                        </button>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+
       {/* Automatic updates */}
       {selfUpdateEnabled && (
         <button

apps/web/src/app/(app)/spaces/[id]/page.tsx

@@ -40,6 +40,7 @@ import { api, API_URL, ApiError } from '@/lib/api';
 import { useAuth } from '@/lib/auth';
 import { useT } from '@/lib/i18n';
 import { Select } from '@/components/ui/Select';
+import { FileViewer, type ViewerSource } from '@/components/FileViewer';
 import { confirm, choose, prompt, toast } from '@/components/ui/overlays';
 
 export default function SpacePage() {
@@ -57,6 +58,7 @@ export default function SpacePage() {
   const [loading, setLoading] = useState(true);
   const [uploadPct, setUploadPct] = useState<number | null>(null);
   const [showManage, setShowManage] = useState(false);
+  const [viewing, setViewing] = useState<ViewerSource | null>(null);
   const fileInput = useRef<HTMLInputElement>(null);
 
   const canWrite = space ? space.myRole === 'OWNER' || space.myRole === 'EDITOR' : false;
@@ -144,6 +146,28 @@ export default function SpacePage() {
     window.open(`${API_URL}/spaces/${spaceId}/files/${f.id}/download`, '_blank');
   }
 
+  // Open a file in the in-app viewer. Editors additionally get an editable text surface that
+  // re-uploads under the same name (the upload pipeline versions it in place).
+  function openFile(f: PublicFile) {
+    setViewing({
+      name: f.name,
+      mime: f.mimeType,
+      sizeBytes: f.sizeBytes,
+      url: api.url(`/spaces/${spaceId}/files/${f.id}/download`),
+      ...(canWrite
+        ? {
+            onSave: async (text: string) => {
+              const form = new FormData();
+              form.append('file', new File([text], f.name, { type: f.mimeType || 'text/plain' }));
+              const q = f.folderId ? `?folderId=${encodeURIComponent(f.folderId)}` : '';
+              await api.upload(`/spaces/${spaceId}/files${q}`, form);
+              await Promise.all([loadFiles(), loadSpace()]);
+            },
+          }
+        : {}),
+    });
+  }
+
   async function renameFile(f: PublicFile) {
     const name = await prompt({ title: t('space.rename'), defaultValue: f.name, confirmLabel: t('space.save') });
     if (!name?.trim() || name === f.name) return;
@@ -425,13 +449,13 @@ export default function SpacePage() {
           ))}
           {files.map((f) => (
             <div key={f.id} className="row">
-              <div className="flex min-w-0 items-center gap-3">
+              <button className="flex min-w-0 items-center gap-3 text-left" onClick={() => openFile(f)} title={t('space.openFile')}>
                 <span className="grid h-9 w-9 shrink-0 place-items-center rounded-lg bg-accent-soft text-violet-300"><FileIcon size={16} /></span>
                 <div className="min-w-0">
                   <p className="truncate font-medium text-zinc-100">{f.name}</p>
                   <p className="text-xs text-zinc-500">{formatBytes(f.sizeBytes)}</p>
                 </div>
-              </div>
+              </button>
               <div className="flex shrink-0 items-center gap-1">
                 <button className="rounded-lg p-1.5 text-zinc-400 transition hover:bg-white/5 hover:text-zinc-100" title={t('space.download')} onClick={() => download(f)}><Download size={15} /></button>
                 {canWrite && (
@@ -445,6 +469,8 @@ export default function SpacePage() {
           ))}
         </div>
       )}
+
+      {viewing && <FileViewer source={viewing} onClose={() => setViewing(null)} />}
     </div>
   );
 }