@promptbook/cli 0.112.0-99 → 0.113.0-0

package/apps/agents-server/src/app/admin/update/UpdateClient.tsx

@@ -1,8 +1,29 @@
 'use client';
 
-import { CheckCircle2, Download, Loader2, RefreshCcw, Rocket, Server, TriangleAlert } from 'lucide-react';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+    CheckCircle2,
+    ChevronDown,
+    ChevronUp,
+    ClipboardCopy,
+    Download,
+    FileDown,
+    GitCommit,
+    Loader2,
+    RefreshCcw,
+    Rocket,
+    Server,
+    Settings2,
+    TriangleAlert,
+} from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { AdminXtermTerminal } from '../../../components/AdminTerminal/AdminXtermTerminal';
 import { Card } from '../../../components/Homepage/Card';
+import { useServerLanguage } from '../../../components/ServerLanguage/ServerLanguageProvider';
+import type { ServerLanguageCode } from '../../../languages/ServerLanguageRegistry';
+import { downloadBlob, parseFilenameFromContentDisposition } from '../../../utils/download/browserFileDownload';
+import { createServerLanguageMoment } from '../../../utils/localization/createServerLanguageMoment';
+import { formatServerLanguageHumanReadableDate } from '../../../utils/localization/formatServerLanguageHumanReadableDate';
+import { CustomCommitPicker, type CustomCommitPickerCandidate } from './CustomCommitPicker';
 
 /**
  * Browser-safe environment option returned by the update API.
@@ -12,6 +33,7 @@ type UpdateEnvironmentOption = {
     readonly branch: string;
     readonly label: string;
     readonly description: string;
+    readonly isCustom: boolean;
 };
 
 /**
@@ -33,6 +55,16 @@ type UpdateJobSnapshot = {
     readonly logFilePath: string | null;
 };
 
+/**
+ * Browser-safe summary of one commit between the deployed checkout and the latest remote commit.
+ */
+type UpdatePendingCommit = {
+    readonly commitSha: string;
+    readonly shortCommitSha: string;
+    readonly subject: string;
+    readonly authoredAt: string | null;
+};
+
 /**
  * Browser-safe self-update overview returned by the super-admin API.
  */
@@ -45,53 +77,86 @@ type UpdateOverview = {
     readonly currentCommitSha: string | null;
     readonly currentCommitShortSha: string | null;
     readonly currentCommitMessage: string | null;
+    readonly currentCommitDate: string | null;
     readonly latestRemoteCommitSha: string | null;
     readonly latestRemoteCommitShortSha: string | null;
+    readonly latestRemoteCommitDate: string | null;
+    readonly latestRemoteCommitMessage: string | null;
+    readonly commitsBehindCount: number | null;
+    readonly pendingCommits: ReadonlyArray<UpdatePendingCommit>;
     readonly isUpdateAvailable: boolean;
+    readonly originRepositoryUrl: string;
+    readonly isOriginRepositoryDefault: boolean;
+    readonly defaultOriginRepositoryUrl: string;
     readonly job: UpdateJobSnapshot;
     readonly error?: string;
 };
 
+/**
+ * Duration (ms) of the transient "Copied!" / "Saved!" feedback shown next to log action buttons.
+ */
+const UPDATE_LOG_ACTION_FEEDBACK_DURATION_MS = 2500;
+
+/**
+ * Default download filename used when the server does not provide one via `Content-Disposition`.
+ */
+const DEFAULT_UPDATE_LOG_DOWNLOAD_FILENAME = 'self-update.log';
+
 /**
  * Client UI for standalone VPS branch-aware self-updates.
  */
 export function UpdateClient() {
+    const { language } = useServerLanguage();
     const [overview, setOverview] = useState<UpdateOverview | null>(null);
     const [selectedEnvironmentId, setSelectedEnvironmentId] = useState<string>('');
+    const [customRef, setCustomRef] = useState<string>('');
+    const [customCandidate, setCustomCandidate] = useState<CustomCommitPickerCandidate | null>(null);
+    const [originRepositoryUrlOverride, setOriginRepositoryUrlOverride] = useState<string>('');
+    const [isAdvancedExpanded, setIsAdvancedExpanded] = useState<boolean>(false);
     const [isLoading, setIsLoading] = useState(true);
     const [isStartingUpdate, setIsStartingUpdate] = useState(false);
     const [errorMessage, setErrorMessage] = useState<string | null>(null);
     const [successMessage, setSuccessMessage] = useState<string | null>(null);
 
-    /**
-     * Loads the latest self-update overview from the server.
-     */
-    const loadOverview = useCallback(async (options?: { readonly isSilent?: boolean }): Promise<void> => {
-        try {
-            if (!options?.isSilent) {
-                setIsLoading(true);
-            }
-            setErrorMessage(null);
-
-            const response = await fetch('/api/admin/update', { cache: 'no-store' });
-            const payload = (await response.json()) as UpdateOverview;
-
-            if (!response.ok) {
-                throw new Error(payload.error || 'Failed to load the update overview.');
-            }
-
-            setOverview(payload);
-            setSelectedEnvironmentId((currentSelectedEnvironmentId) =>
-                currentSelectedEnvironmentId || payload.currentEnvironment.id,
-            );
-        } catch (error) {
-            setErrorMessage(error instanceof Error ? error.message : 'Failed to load the update overview.');
-        } finally {
-            if (!options?.isSilent) {
-                setIsLoading(false);
+    const loadOverview = useCallback(
+        async (options?: { readonly isSilent?: boolean; readonly isRestartExpected?: boolean }): Promise<void> => {
+            try {
+                if (!options?.isSilent) {
+                    setIsLoading(true);
+                }
+                setErrorMessage(null);
+
+                const response = await fetch('/api/admin/update', { cache: 'no-store' });
+                const payload = (await response.json()) as UpdateOverview;
+
+                if (!response.ok) {
+                    throw new Error(payload.error || 'Failed to load the update overview.');
+                }
+
+                setOverview(payload);
+                setSelectedEnvironmentId(
+                    (currentSelectedEnvironmentId) => currentSelectedEnvironmentId || payload.currentEnvironment.id,
+                );
+                setOriginRepositoryUrlOverride((currentValue) => currentValue || payload.originRepositoryUrl);
+                if (payload.job.status === 'succeeded') {
+                    setSuccessMessage(getUpdateJobSuccessMessage(payload.job));
+                } else if (payload.job.status === 'failed') {
+                    setSuccessMessage(null);
+                }
+            } catch (error) {
+                if (options?.isRestartExpected) {
+                    return;
+                }
+
+                setErrorMessage(error instanceof Error ? error.message : 'Failed to load the update overview.');
+            } finally {
+                if (!options?.isSilent) {
+                    setIsLoading(false);
+                }
             }
-        }
-    }, []);
+        },
+        [],
+    );
 
     useEffect(() => {
         void loadOverview();
@@ -103,7 +168,7 @@ export function UpdateClient() {
         }
 
         const interval = window.setInterval(() => {
-            void loadOverview({ isSilent: true });
+            void loadOverview({ isSilent: true, isRestartExpected: true });
         }, 4000);
 
         return () => {
@@ -118,13 +183,18 @@ export function UpdateClient() {
             null,
         [overview, selectedEnvironmentId],
     );
+    const isCustomEnvironmentSelected = selectedEnvironment?.isCustom === true;
     const isEnvironmentSwitchRequired =
         Boolean(selectedEnvironment) && selectedEnvironment?.id !== overview?.currentEnvironment.id;
     const isUpdateRunning = overview?.job.status === 'running';
+    const updateTerminalId = `standalone-vps-update:${overview?.job.startedAt || overview?.job.finishedAt || overview?.job.status || 'loading'}`;
+    const updateTerminalEmptyState =
+        isLoading && !overview ? 'Loading update log...' : 'No persisted update log output yet.';
+    const isCustomRefRelease = isCustomEnvironmentSelected ? customCandidate?.isReleaseTag === true : true;
+    const isCustomRefMissing = isCustomEnvironmentSelected && !customRef.trim();
+    const isOriginOverrideChanged =
+        overview !== null && originRepositoryUrlOverride.trim() !== overview.originRepositoryUrl;
 
-    /**
-     * Starts one detached update run for the selected environment.
-     */
     async function startUpdate(): Promise<void> {
         if (!selectedEnvironment) {
             return;
@@ -142,6 +212,8 @@ export function UpdateClient() {
                 },
                 body: JSON.stringify({
                     environment: selectedEnvironment.id,
+                    customRef: isCustomEnvironmentSelected ? customRef.trim() : null,
+                    originRepositoryUrl: isOriginOverrideChanged ? originRepositoryUrlOverride.trim() : null,
                 }),
             });
             const payload = (await response.json()) as UpdateOverview;
@@ -152,9 +224,11 @@ export function UpdateClient() {
 
             setOverview(payload);
             setSuccessMessage(
-                isEnvironmentSwitchRequired
-                    ? `Switched to ${selectedEnvironment.label} and started the standalone VPS update.`
-                    : 'Standalone VPS update started.',
+                isCustomEnvironmentSelected
+                    ? `Started the standalone VPS update to custom ref ${customRef.trim()}.`
+                    : isEnvironmentSwitchRequired
+                      ? `Switched to ${selectedEnvironment.label} and started the standalone VPS update.`
+                      : 'Standalone VPS update started.',
             );
         } catch (error) {
             setErrorMessage(error instanceof Error ? error.message : 'Failed to start the update.');
@@ -169,8 +243,8 @@ export function UpdateClient() {
                 <div>
                     <h1 className="text-3xl font-light text-gray-900">Update</h1>
                     <p className="mt-1 max-w-3xl text-sm text-gray-500">
-                        Switch the standalone VPS between Production, Live, Preview, and LTS, and update the managed
-                        Promptbook checkout with one click.
+                        Switch the standalone VPS between Live, Preview, Production, LTS, or a custom ref, and update
+                        the managed Promptbook checkout with one click.
                     </p>
                 </div>
 
@@ -204,77 +278,7 @@ export function UpdateClient() {
 
             <div className="grid gap-4 lg:grid-cols-[1.4fr_1fr]">
                 <Card className="hover:border-gray-200 hover:shadow-md">
-                    <div className="space-y-4">
-                        <div className="flex items-start gap-3">
-                            <Server className="mt-0.5 h-5 w-5 text-blue-600" />
-                            <div>
-                                <h2 className="text-lg font-semibold text-slate-900">Current deployment</h2>
-                                <p className="mt-1 text-sm text-slate-500">
-                                    The server currently tracks the <span className="font-medium">{overview?.currentEnvironment.label || 'Production'}</span>{' '}
-                                    environment on branch <span className="font-mono">{overview?.currentEnvironment.branch || 'production'}</span>.
-                                </p>
-                            </div>
-                        </div>
-
-                        <dl className="grid gap-4 text-sm text-slate-600 sm:grid-cols-2">
-                            <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
-                                <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">Branch</dt>
-                                <dd className="mt-1 font-mono text-slate-900">
-                                    {overview?.currentEnvironment.branch || 'production'}
-                                </dd>
-                            </div>
-                            <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
-                                <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">
-                                    Deployed commit
-                                </dt>
-                                <dd className="mt-1 font-mono text-slate-900">
-                                    {overview?.currentCommitShortSha || 'Unknown'}
-                                </dd>
-                            </div>
-                            <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
-                                <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">
-                                    Latest remote commit
-                                </dt>
-                                <dd className="mt-1 font-mono text-slate-900">
-                                    {overview?.latestRemoteCommitShortSha || 'Unknown'}
-                                </dd>
-                            </div>
-                            <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
-                                <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">
-                                    Update availability
-                                </dt>
-                                <dd className="mt-1 flex items-center gap-2 text-slate-900">
-                                    {overview?.isUpdateAvailable ? (
-                                        <>
-                                            <TriangleAlert className="h-4 w-4 text-amber-500" />
-                                            New commit available
-                                        </>
-                                    ) : (
-                                        <>
-                                            <CheckCircle2 className="h-4 w-4 text-emerald-600" />
-                                            Up to date
-                                        </>
-                                    )}
-                                </dd>
-                            </div>
-                        </dl>
-
-                        {overview?.currentCommitMessage && (
-                            <div className="rounded-xl border border-slate-200 bg-white px-4 py-3 text-sm text-slate-600">
-                                <div className="text-xs font-semibold uppercase tracking-wide text-slate-500">
-                                    Current commit message
-                                </div>
-                                <div className="mt-1 text-slate-900">{overview.currentCommitMessage}</div>
-                            </div>
-                        )}
-
-                        {overview?.repositoryDirectory && (
-                            <div className="text-xs text-slate-500">
-                                Managed repository:
-                                <span className="ml-2 font-mono text-slate-700">{overview.repositoryDirectory}</span>
-                            </div>
-                        )}
-                    </div>
+                    <CurrentDeploymentCard overview={overview} language={language} />
                 </Card>
 
                 <Card className="hover:border-gray-200 hover:shadow-md">
@@ -312,13 +316,48 @@ export function UpdateClient() {
                                                 </span>
                                             )}
                                         </div>
-                                        <div className="mt-1 font-mono text-xs">{environment.branch}</div>
+                                        {environment.branch && (
+                                            <div className="mt-1 font-mono text-xs">{environment.branch}</div>
+                                        )}
                                         <div className="mt-2 text-sm opacity-80">{environment.description}</div>
                                     </button>
                                 );
                             })}
                         </div>
 
+                        {isCustomEnvironmentSelected && overview?.isAvailable && (
+                            <div className="space-y-3 rounded-xl border border-blue-200 bg-blue-50/40 p-4">
+                                <CustomCommitPicker
+                                    language={language}
+                                    selectedRef={customRef}
+                                    onSelectRef={(nextRef, matchedCandidate) => {
+                                        setCustomRef(nextRef);
+                                        setCustomCandidate(matchedCandidate);
+                                    }}
+                                    isDisabled={isUpdateRunning || isStartingUpdate}
+                                />
+
+                                {customRef.trim() && !isCustomRefRelease && (
+                                    <div className="flex items-start gap-2 rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-xs text-amber-800">
+                                        <TriangleAlert className="mt-0.5 h-4 w-4 shrink-0" />
+                                        <div>
+                                            <strong>Heads up:</strong> the selected ref is not a release tag, so it may
+                                            be unstable and was not validated by the regular release pipeline.
+                                        </div>
+                                    </div>
+                                )}
+                            </div>
+                        )}
+
+                        <AdvancedOriginRepositoryPanel
+                            originRepositoryUrlOverride={originRepositoryUrlOverride}
+                            onChange={setOriginRepositoryUrlOverride}
+                            overview={overview}
+                            isExpanded={isAdvancedExpanded}
+                            onToggleExpanded={() => setIsAdvancedExpanded((current) => !current)}
+                            isDisabled={isUpdateRunning || isStartingUpdate}
+                        />
+
                         <button
                             type="button"
                             onClick={() => void startUpdate()}
@@ -327,20 +366,28 @@ export function UpdateClient() {
                                 !selectedEnvironment ||
                                 isUpdateRunning ||
                                 isStartingUpdate ||
-                                (!isEnvironmentSwitchRequired && !overview?.isUpdateAvailable)
+                                isCustomRefMissing ||
+                                (!isCustomEnvironmentSelected &&
+                                    !isEnvironmentSwitchRequired &&
+                                    !overview?.isUpdateAvailable &&
+                                    !isOriginOverrideChanged)
                             }
                             className="inline-flex w-full items-center justify-center gap-2 rounded-md bg-blue-600 px-4 py-3 text-sm font-semibold text-white hover:bg-blue-700 disabled:cursor-not-allowed disabled:opacity-60"
                         >
                             {isStartingUpdate || isUpdateRunning ? (
                                 <Loader2 className="h-4 w-4 animate-spin" />
+                            ) : isCustomEnvironmentSelected ? (
+                                <Rocket className="h-4 w-4" />
                             ) : isEnvironmentSwitchRequired ? (
                                 <Rocket className="h-4 w-4" />
                             ) : (
                                 <Download className="h-4 w-4" />
                             )}
-                            {isEnvironmentSwitchRequired
-                                ? `Switch to ${selectedEnvironment?.label || 'selected environment'} and update`
-                                : 'Update to latest commit'}
+                            {isCustomEnvironmentSelected
+                                ? `Update to ${customRef.trim() || 'custom ref'}`
+                                : isEnvironmentSwitchRequired
+                                  ? `Switch to ${selectedEnvironment?.label || 'selected environment'} and update`
+                                  : 'Update to latest commit'}
                         </button>
                     </div>
                 </Card>
@@ -374,7 +421,9 @@ export function UpdateClient() {
                     <dl className="grid gap-4 text-sm text-slate-600 md:grid-cols-2 xl:grid-cols-4">
                         <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
                             <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">Target</dt>
-                            <dd className="mt-1 text-slate-900">{overview?.job.targetEnvironment.label || 'Production'}</dd>
+                            <dd className="mt-1 text-slate-900">
+                                {overview?.job.targetEnvironment.label || 'Production'}
+                            </dd>
                         </div>
                         <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
                             <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">Step</dt>
@@ -382,22 +431,26 @@ export function UpdateClient() {
                         </div>
                         <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
                             <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">Started</dt>
-                            <dd className="mt-1 text-slate-900">{formatTimestamp(overview?.job.startedAt)}</dd>
+                            <dd className="mt-1 text-slate-900">
+                                {formatHumanReadableTimestamp(overview?.job.startedAt, language)}
+                            </dd>
                         </div>
                         <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
                             <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">Finished</dt>
-                            <dd className="mt-1 text-slate-900">{formatTimestamp(overview?.job.finishedAt)}</dd>
+                            <dd className="mt-1 text-slate-900">
+                                {formatHumanReadableTimestamp(overview?.job.finishedAt, language)}
+                            </dd>
                         </div>
                     </dl>
 
-                    {overview?.job.errorMessage && (
-                        <div className="rounded-xl border border-rose-200 bg-rose-50 px-4 py-3 text-sm text-rose-700">
-                            {overview.job.errorMessage}
+                    {overview?.job.status === 'succeeded' && (
+                        <div className="rounded-xl border border-emerald-200 bg-emerald-50 px-4 py-3 text-sm text-emerald-700">
+                            {getUpdateJobSuccessMessage(overview.job)}
                         </div>
                     )}
-                    {overview?.job.isStale && (
-                        <div className="rounded-xl border border-amber-200 bg-amber-50 px-4 py-3 text-sm text-amber-800">
-                            The previous background update process stopped unexpectedly. You can start the update again.
+                    {overview?.job.status === 'failed' && (
+                        <div className="rounded-xl border border-rose-200 bg-rose-50 px-4 py-3 text-sm text-rose-700">
+                            {getUpdateJobFailureMessage(overview.job)}
                         </div>
                     )}
                     {overview?.job.logFilePath && (
@@ -406,30 +459,467 @@ export function UpdateClient() {
                             <span className="ml-2 font-mono text-slate-700">{overview.job.logFilePath}</span>
                         </div>
                     )}
-                    <pre className="max-h-[28rem] overflow-auto rounded-xl border border-slate-200 bg-slate-950 p-4 text-xs text-slate-100">
-                        {overview?.job.logTail || 'No persisted update log output yet.'}
-                    </pre>
+                    {overview?.job.status === 'failed' && <UpdateJobLogActions />}
+                    <AdminXtermTerminal
+                        terminalId={updateTerminalId}
+                        output={overview?.job.logTail || ''}
+                        emptyState={updateTerminalEmptyState}
+                        isReadOnly
+                        isPlainTextOutput
+                        ariaLabel="Standalone VPS update log"
+                    />
                 </div>
             </Card>
+
+            <PendingCommitsCard overview={overview} language={language} />
         </div>
     );
 }
 
 /**
- * Formats optional timestamps for the status cards.
+ * Current-deployment metrics card, including the new commits-behind and time-behind info.
  *
- * @param value - ISO timestamp or `null`.
- * @returns Human-friendly timestamp or fallback text.
+ * @private internal component of `<UpdateClient/>`
+ */
+function CurrentDeploymentCard({
+    overview,
+    language,
+}: {
+    readonly overview: UpdateOverview | null;
+    readonly language: ServerLanguageCode;
+}) {
+    const driftLabel = useMemo(
+        () => buildDeploymentDriftLabel(overview, language),
+        [overview, language],
+    );
+
+    return (
+        <div className="space-y-4">
+            <div className="flex items-start gap-3">
+                <Server className="mt-0.5 h-5 w-5 text-blue-600" />
+                <div>
+                    <h2 className="text-lg font-semibold text-slate-900">Current deployment</h2>
+                    <p className="mt-1 text-sm text-slate-500">
+                        The server currently tracks the{' '}
+                        <span className="font-medium">
+                            {overview?.currentEnvironment.label || 'Production'}
+                        </span>{' '}
+                        environment on branch{' '}
+                        <span className="font-mono">{overview?.currentEnvironment.branch || 'production'}</span>.
+                    </p>
+                </div>
+            </div>
+
+            <dl className="grid gap-4 text-sm text-slate-600 sm:grid-cols-2">
+                <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
+                    <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">Branch</dt>
+                    <dd className="mt-1 font-mono text-slate-900">
+                        {overview?.currentEnvironment.branch || 'production'}
+                    </dd>
+                </div>
+                <CommitSummaryCard
+                    label="Deployed commit"
+                    commitSha={overview?.currentCommitSha ?? null}
+                    shortCommitSha={overview?.currentCommitShortSha ?? null}
+                    subject={overview?.currentCommitMessage ?? null}
+                    authoredAt={overview?.currentCommitDate ?? null}
+                    language={language}
+                />
+                <CommitSummaryCard
+                    label="Latest remote commit"
+                    commitSha={overview?.latestRemoteCommitSha ?? null}
+                    shortCommitSha={overview?.latestRemoteCommitShortSha ?? null}
+                    subject={overview?.latestRemoteCommitMessage ?? null}
+                    authoredAt={overview?.latestRemoteCommitDate ?? null}
+                    language={language}
+                />
+                <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
+                    <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">
+                        Update availability
+                    </dt>
+                    <dd className="mt-1 flex items-center gap-2 text-slate-900">
+                        {overview?.isUpdateAvailable ? (
+                            <>
+                                <TriangleAlert className="h-4 w-4 text-amber-500" />
+                                {driftLabel}
+                            </>
+                        ) : (
+                            <>
+                                <CheckCircle2 className="h-4 w-4 text-emerald-600" />
+                                Up to date
+                            </>
+                        )}
+                    </dd>
+                </div>
+            </dl>
+
+            {overview?.repositoryDirectory && (
+                <div className="text-xs text-slate-500">
+                    Managed repository:
+                    <span className="ml-2 font-mono text-slate-700">{overview.repositoryDirectory}</span>
+                </div>
+            )}
+        </div>
+    );
+}
+
+/**
+ * Renders one commit as subject, hash and authored date.
+ *
+ * @private internal component of `<UpdateClient/>`
+ */
+function CommitSummaryCard({
+    label,
+    commitSha,
+    shortCommitSha,
+    subject,
+    authoredAt,
+    language,
+}: {
+    readonly label: string;
+    readonly commitSha: string | null;
+    readonly shortCommitSha: string | null;
+    readonly subject: string | null;
+    readonly authoredAt: string | null;
+    readonly language: ServerLanguageCode;
+}) {
+    const commitHashLabel = commitSha || shortCommitSha || 'Unknown hash';
+
+    return (
+        <div className="rounded-xl border border-slate-200 bg-slate-50 px-4 py-3">
+            <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">{label}</dt>
+            <dd className="mt-1 text-slate-900">{subject || 'Unknown commit subject'}</dd>
+            <div className="mt-2 break-all font-mono text-xs text-slate-600">{commitHashLabel}</div>
+            <div className="mt-1 text-xs text-slate-500">{formatHumanReadableTimestamp(authoredAt, language)}</div>
+        </div>
+    );
+}
+
+/**
+ * Lists the commits between the deployed checkout and the latest remote commit so the super admin can review what
+ * exactly is about to be installed before triggering the self-update.
+ *
+ * @private internal component of `<UpdateClient/>`
  */
-function formatTimestamp(value: string | null | undefined): string {
-    if (!value) {
-        return 'Not available';
+function PendingCommitsCard({
+    overview,
+    language,
+}: {
+    readonly overview: UpdateOverview | null;
+    readonly language: ServerLanguageCode;
+}) {
+    if (!overview || overview.pendingCommits.length === 0) {
+        return null;
     }
 
-    const date = new Date(value);
-    if (Number.isNaN(date.getTime())) {
-        return value;
+    const commitsBehindLabel =
+        overview.commitsBehindCount !== null && overview.commitsBehindCount > 0
+            ? `${overview.commitsBehindCount} commit${overview.commitsBehindCount === 1 ? '' : 's'} behind`
+            : `${overview.pendingCommits.length} commit${overview.pendingCommits.length === 1 ? '' : 's'} pending`;
+    const timeBehindLabel = buildDeploymentTimeBehindLabel(overview, language);
+
+    return (
+        <Card className="hover:border-gray-200 hover:shadow-md">
+            <div className="space-y-4">
+                <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+                    <div className="flex items-start gap-3">
+                        <GitCommit className="mt-0.5 h-5 w-5 text-amber-500" />
+                        <div>
+                            <h2 className="text-lg font-semibold text-slate-900">Pending commits</h2>
+                            <p className="mt-1 text-sm text-slate-500">
+                                Commits between the currently deployed checkout and the latest commit on{' '}
+                                <span className="font-mono">{overview.currentEnvironment.branch}</span>.
+                            </p>
+                        </div>
+                    </div>
+                    <div className="text-xs font-semibold uppercase tracking-wide text-slate-500 sm:text-right">
+                        <div>{commitsBehindLabel}</div>
+                        {timeBehindLabel && <div className="mt-1 normal-case text-slate-400">{timeBehindLabel}</div>}
+                    </div>
+                </div>
+
+                <ul className="divide-y divide-slate-100 rounded-xl border border-slate-200 bg-white">
+                    {overview.pendingCommits.map((pendingCommit) => (
+                        <li key={pendingCommit.commitSha} className="px-4 py-3">
+                            <div className="text-sm text-slate-900">{pendingCommit.subject}</div>
+                            <div className="mt-1 break-all font-mono text-xs text-slate-500">
+                                {pendingCommit.commitSha || pendingCommit.shortCommitSha}
+                            </div>
+                            <div className="mt-1 text-xs text-slate-500">
+                                {formatHumanReadableTimestamp(pendingCommit.authoredAt, language)}
+                            </div>
+                        </li>
+                    ))}
+                </ul>
+            </div>
+        </Card>
+    );
+}
+
+/**
+ * Renders the copy / download actions for the persisted standalone VPS self-update log file.
+ *
+ * Shown when the latest update job failed so the super admin can quickly share the full log with the developers.
+ *
+ * @private internal component of `<UpdateClient/>`
+ */
+function UpdateJobLogActions() {
+    const [actionFeedback, setActionFeedback] = useState<string | null>(null);
+    const [actionErrorMessage, setActionErrorMessage] = useState<string | null>(null);
+    const [isCopying, setIsCopying] = useState(false);
+    const [isDownloading, setIsDownloading] = useState(false);
+    const feedbackTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+    useEffect(() => {
+        return () => {
+            if (feedbackTimeoutRef.current !== null) {
+                clearTimeout(feedbackTimeoutRef.current);
+                feedbackTimeoutRef.current = null;
+            }
+        };
+    }, []);
+
+    function showActionFeedback(feedbackMessage: string): void {
+        if (feedbackTimeoutRef.current !== null) {
+            clearTimeout(feedbackTimeoutRef.current);
+        }
+        setActionFeedback(feedbackMessage);
+        setActionErrorMessage(null);
+        feedbackTimeoutRef.current = setTimeout(() => {
+            setActionFeedback(null);
+            feedbackTimeoutRef.current = null;
+        }, UPDATE_LOG_ACTION_FEEDBACK_DURATION_MS);
+    }
+
+    async function fetchUpdateLogResponse(): Promise<Response> {
+        const response = await fetch('/api/admin/update/log', { cache: 'no-store' });
+        if (!response.ok) {
+            const errorPayload = (await response.json().catch(() => null)) as { readonly error?: string } | null;
+            throw new Error(errorPayload?.error || 'Failed to load the self-update log file.');
+        }
+        return response;
+    }
+
+    async function handleCopyLog(): Promise<void> {
+        if (isCopying || isDownloading) {
+            return;
+        }
+
+        try {
+            setIsCopying(true);
+            setActionErrorMessage(null);
+            if (!navigator.clipboard?.writeText) {
+                throw new Error('The browser clipboard API is unavailable in this context.');
+            }
+            const response = await fetchUpdateLogResponse();
+            const logContent = await response.text();
+            await navigator.clipboard.writeText(logContent);
+            showActionFeedback('Self-update log copied to clipboard.');
+        } catch (error) {
+            setActionErrorMessage(error instanceof Error ? error.message : 'Failed to copy the self-update log.');
+        } finally {
+            setIsCopying(false);
+        }
+    }
+
+    async function handleDownloadLog(): Promise<void> {
+        if (isCopying || isDownloading) {
+            return;
+        }
+
+        try {
+            setIsDownloading(true);
+            setActionErrorMessage(null);
+            const response = await fetchUpdateLogResponse();
+            const logFilename =
+                parseFilenameFromContentDisposition(response.headers.get('Content-Disposition')) ||
+                DEFAULT_UPDATE_LOG_DOWNLOAD_FILENAME;
+            const logBlob = await response.blob();
+            downloadBlob(logBlob, logFilename);
+            showActionFeedback(`Saved self-update log as ${logFilename}.`);
+        } catch (error) {
+            setActionErrorMessage(error instanceof Error ? error.message : 'Failed to download the self-update log.');
+        } finally {
+            setIsDownloading(false);
+        }
+    }
+
+    return (
+        <div className="flex flex-wrap items-center gap-3 rounded-xl border border-rose-200 bg-rose-50/40 px-4 py-3 text-sm text-rose-700">
+            <span className="font-medium">Share the log with the developers:</span>
+            <button
+                type="button"
+                onClick={() => void handleCopyLog()}
+                disabled={isCopying || isDownloading}
+                className="inline-flex items-center gap-2 rounded-md border border-rose-200 bg-white px-3 py-1.5 text-xs font-semibold text-rose-700 hover:bg-rose-100 disabled:cursor-not-allowed disabled:opacity-60"
+            >
+                {isCopying ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <ClipboardCopy className="h-3.5 w-3.5" />}
+                Copy log
+            </button>
+            <button
+                type="button"
+                onClick={() => void handleDownloadLog()}
+                disabled={isCopying || isDownloading}
+                className="inline-flex items-center gap-2 rounded-md border border-rose-200 bg-white px-3 py-1.5 text-xs font-semibold text-rose-700 hover:bg-rose-100 disabled:cursor-not-allowed disabled:opacity-60"
+            >
+                {isDownloading ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <FileDown className="h-3.5 w-3.5" />}
+                Download log
+            </button>
+            {actionFeedback && (
+                <span className="text-xs text-rose-600" role="status" aria-live="polite">
+                    {actionFeedback}
+                </span>
+            )}
+            {actionErrorMessage && (
+                <span className="text-xs text-rose-700" role="alert">
+                    {actionErrorMessage}
+                </span>
+            )}
+        </div>
+    );
+}
+
+/**
+ * Collapsible advanced panel for overriding the upstream repository URL.
+ *
+ * @private internal component of `<UpdateClient/>`
+ */
+function AdvancedOriginRepositoryPanel({
+    originRepositoryUrlOverride,
+    onChange,
+    overview,
+    isExpanded,
+    onToggleExpanded,
+    isDisabled,
+}: {
+    readonly originRepositoryUrlOverride: string;
+    readonly onChange: (nextValue: string) => void;
+    readonly overview: UpdateOverview | null;
+    readonly isExpanded: boolean;
+    readonly onToggleExpanded: () => void;
+    readonly isDisabled: boolean;
+}) {
+    return (
+        <div className="rounded-xl border border-slate-200 bg-white">
+            <button
+                type="button"
+                onClick={onToggleExpanded}
+                className="flex w-full items-center justify-between gap-3 px-4 py-3 text-sm font-semibold text-slate-700"
+            >
+                <span className="inline-flex items-center gap-2">
+                    <Settings2 className="h-4 w-4" />
+                    Advanced
+                </span>
+                {isExpanded ? <ChevronUp className="h-4 w-4" /> : <ChevronDown className="h-4 w-4" />}
+            </button>
+            {isExpanded && (
+                <div className="space-y-3 border-t border-slate-100 px-4 py-3 text-sm text-slate-600">
+                    <label className="block">
+                        <span className="text-xs font-semibold uppercase tracking-wide text-slate-500">
+                            Upstream repository URL
+                        </span>
+                        <input
+                            type="url"
+                            value={originRepositoryUrlOverride}
+                            onChange={(event) => onChange(event.target.value)}
+                            disabled={isDisabled}
+                            placeholder={overview?.defaultOriginRepositoryUrl || ''}
+                            className="mt-1 w-full rounded-md border border-slate-300 bg-white px-3 py-2 font-mono text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:cursor-not-allowed disabled:opacity-60"
+                        />
+                    </label>
+                    <p className="text-xs text-slate-500">
+                        Defaults to <span className="font-mono">{overview?.defaultOriginRepositoryUrl}</span>. Only
+                        change this if you self-host a fork of the original Promptbook repository — the new value is
+                        persisted in the standalone VPS <code>.env</code>.
+                    </p>
+                    {overview && !overview.isOriginRepositoryDefault && (
+                        <div className="rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-xs text-amber-800">
+                            <strong>Custom origin active:</strong> updates currently pull from{' '}
+                            <span className="font-mono">{overview.originRepositoryUrl}</span>.
+                        </div>
+                    )}
+                </div>
+            )}
+        </div>
+    );
+}
+
+/**
+ * Builds the "behind by …" label combining commits-behind and time-behind info.
+ *
+ * @param overview - Current overview snapshot.
+ * @param language - Active UI language for moment localization.
+ * @returns Human-readable label or fallback text.
+ */
+function buildDeploymentDriftLabel(overview: UpdateOverview | null, language: ServerLanguageCode): string {
+    if (!overview) {
+        return 'New commit available';
+    }
+
+    const commitsBehindLabel =
+        overview.commitsBehindCount !== null && overview.commitsBehindCount > 0
+            ? `${overview.commitsBehindCount} commit${overview.commitsBehindCount === 1 ? '' : 's'} behind`
+            : 'New commit available';
+
+    const timeBehindLabel = buildDeploymentTimeBehindLabel(overview, language);
+    if (!timeBehindLabel) {
+        return commitsBehindLabel;
+    }
+
+    return `${commitsBehindLabel} · ${timeBehindLabel}`;
+}
+
+/**
+ * Builds the localized time-behind portion of the deployment drift label (e.g. `3 days behind`).
+ *
+ * @param overview - Current overview snapshot.
+ * @param language - Active UI language for moment localization.
+ * @returns Time-behind label or empty string when either side of the comparison is missing.
+ */
+function buildDeploymentTimeBehindLabel(overview: UpdateOverview | null, language: ServerLanguageCode): string {
+    if (!overview?.currentCommitDate || !overview.latestRemoteCommitDate) {
+        return '';
+    }
+
+    const currentMoment = createServerLanguageMoment(overview.currentCommitDate, language);
+    const latestMoment = createServerLanguageMoment(overview.latestRemoteCommitDate, language);
+    if (!currentMoment.isValid() || !latestMoment.isValid()) {
+        return '';
     }
 
-    return `${date.toLocaleString()} (${value})`;
+    return `${currentMoment.from(latestMoment, true)} behind`;
+}
+
+/**
+ * Builds the success message for a finished standalone VPS update.
+ *
+ * @param job - Completed update job snapshot.
+ * @returns Human-readable success message.
+ */
+function getUpdateJobSuccessMessage(job: UpdateJobSnapshot): string {
+    return job.currentStep || 'Standalone VPS update finished successfully.';
+}
+
+/**
+ * Builds the failure message for a failed standalone VPS update.
+ *
+ * @param job - Failed update job snapshot.
+ * @returns Human-readable failure message.
+ */
+function getUpdateJobFailureMessage(job: UpdateJobSnapshot): string {
+    return job.errorMessage || 'The standalone VPS update failed. Review the installer log for details.';
+}
+
+/**
+ * Formats optional timestamps for the status cards using `moment.js` with the active UI language.
+ *
+ * @param value - ISO timestamp or `null`.
+ * @param language - Active UI language code.
+ * @returns Localized human-friendly timestamp or fallback text.
+ */
+function formatHumanReadableTimestamp(value: string | null | undefined, language: ServerLanguageCode): string {
+    return formatServerLanguageHumanReadableDate(value, language, {
+        fallbackLabel: 'Not available',
+        isExactDateIncluded: true,
+    });
 }