@promptbook/cli 0.113.0-8 → 0.113.0-9

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

@@ -0,0 +1,112 @@
+'use client';
+
+import { HardDrive, Loader2, Trash2 } from 'lucide-react';
+import type { ServerLanguageCode } from '../../../languages/ServerLanguageRegistry';
+import { Card } from '../../../components/Homepage/Card';
+import { formatHumanReadableTimestamp } from './formatHumanReadableTimestamp';
+import type { UpdateClientState } from './useUpdateClientState';
+import { UPDATE_PAGE_CARD_CLASS_NAME } from './updatePageCardClassName';
+
+/**
+ * Props for the installed versions card.
+ *
+ * @private type of `<InstalledVersionsCard/>`
+ */
+type InstalledVersionsCardProps = {
+    readonly state: UpdateClientState;
+    readonly language: ServerLanguageCode;
+};
+
+/**
+ * Lists the Agents Server versions installed in the releases directory, marks the currently deployed
+ * one, and lets the super admin delete old versions manually to free disk space.
+ *
+ * @private internal component of `<UpdateClient/>`
+ */
+export function InstalledVersionsCard({ state, language }: InstalledVersionsCardProps) {
+    const { overview } = state;
+
+    if (!overview || overview.installedVersions.length === 0) {
+        return null;
+    }
+
+    return (
+        <Card className={UPDATE_PAGE_CARD_CLASS_NAME}>
+            <div className="min-w-0 space-y-4">
+                <div className="flex min-w-0 items-start gap-3">
+                    <HardDrive className="mt-0.5 h-5 w-5 shrink-0 text-slate-500" />
+                    <div className="min-w-0">
+                        <h2 className="text-lg font-semibold text-slate-900">Installed versions</h2>
+                        <p className="mt-1 text-sm text-slate-500">
+                            Every version keeps its own multi-gigabyte checkout on disk. Old versions beyond the{' '}
+                            {overview.garbageCollectionKeepVersionsCount} most recent (configurable via the{' '}
+                            <span className="break-all font-mono">AGENTS_SERVER_GC_KEEP_VERSIONS</span> environment
+                            variable) are garbage-collected automatically during each self-update, and you can also
+                            delete old versions manually here.
+                        </p>
+                    </div>
+                </div>
+
+                <ul className="divide-y divide-slate-100 rounded-xl border border-slate-200 bg-white">
+                    {overview.installedVersions.map((installedVersion) => (
+                        <li
+                            key={installedVersion.name}
+                            className="flex min-w-0 items-center justify-between gap-3 px-4 py-3"
+                        >
+                            <div className="min-w-0">
+                                <div className="flex min-w-0 flex-wrap items-center gap-2">
+                                    <span className="break-all font-mono text-sm text-slate-900">
+                                        {installedVersion.name}
+                                    </span>
+                                    {installedVersion.isCurrent && (
+                                        <span className="shrink-0 rounded-full bg-emerald-100 px-2 py-0.5 text-xs font-semibold text-emerald-700">
+                                            Current
+                                        </span>
+                                    )}
+                                </div>
+                                <div className="mt-1 break-all font-mono text-xs text-slate-500">
+                                    {installedVersion.directoryPath}
+                                </div>
+                                <div className="mt-1 text-xs text-slate-500">
+                                    {formatHumanReadableTimestamp(installedVersion.modifiedAt, language)}
+                                </div>
+                            </div>
+
+                            {!installedVersion.isCurrent && (
+                                <button
+                                    type="button"
+                                    onClick={() => void confirmAndDeleteInstalledVersion(state, installedVersion.name)}
+                                    disabled={state.isUpdateRunning || state.deletingVersionName !== null}
+                                    className="inline-flex shrink-0 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-50 disabled:cursor-not-allowed disabled:opacity-60"
+                                >
+                                    {state.deletingVersionName === installedVersion.name ? (
+                                        <Loader2 className="h-3.5 w-3.5 animate-spin" />
+                                    ) : (
+                                        <Trash2 className="h-3.5 w-3.5" />
+                                    )}
+                                    Delete
+                                </button>
+                            )}
+                        </li>
+                    ))}
+                </ul>
+            </div>
+        </Card>
+    );
+}
+
+/**
+ * Asks for confirmation before deleting one old installed version.
+ *
+ * @param state - Update client state with the delete action.
+ * @param versionName - Release directory name to delete.
+ *
+ * @private function of `<InstalledVersionsCard/>`
+ */
+async function confirmAndDeleteInstalledVersion(state: UpdateClientState, versionName: string): Promise<void> {
+    if (!window.confirm(`Delete the installed Agents Server version ${versionName}? This cannot be undone.`)) {
+        return;
+    }
+
+    await state.deleteInstalledVersion(versionName);
+}

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

@@ -6,6 +6,7 @@ import { Card } from '../../../components/Homepage/Card';
 import { buildDeploymentTimeBehindLabel } from './buildDeploymentTimeBehindLabel';
 import { formatHumanReadableTimestamp } from './formatHumanReadableTimestamp';
 import type { UpdateOverview } from './UpdateOverview';
+import { UPDATE_PAGE_CARD_CLASS_NAME } from './updatePageCardClassName';
 
 /**
  * Props for the pending commits card.
@@ -32,20 +33,20 @@ export function PendingCommitsCard({ overview, language }: PendingCommitsCardPro
     const timeBehindLabel = buildDeploymentTimeBehindLabel(overview, language);
 
     return (
-        <Card className="hover:border-gray-200 hover:shadow-md">
-            <div className="space-y-4">
+        <Card className={UPDATE_PAGE_CARD_CLASS_NAME}>
+            <div className="min-w-0 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>
+                    <div className="flex min-w-0 items-start gap-3">
+                        <GitCommit className="mt-0.5 h-5 w-5 shrink-0 text-amber-500" />
+                        <div className="min-w-0">
                             <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>.
+                                <span className="break-all 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 className="shrink-0 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>
@@ -54,7 +55,7 @@ export function PendingCommitsCard({ overview, language }: PendingCommitsCardPro
                 <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="break-words 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>

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

@@ -79,7 +79,7 @@ export function TargetEnvironmentCard({ state, language }: TargetEnvironmentCard
     const isControlsDisabled = state.isUpdateRunning || state.isStartingUpdate;
 
     return (
-        <div className="space-y-4">
+        <div className="min-w-0 space-y-4">
             <div>
                 <h2 className="text-lg font-semibold text-slate-900">Target environment</h2>
                 <p className="mt-1 text-sm text-slate-500">
@@ -124,7 +124,7 @@ function EnvironmentOptionList({
     onSelectEnvironment,
 }: EnvironmentOptionListProps) {
     return (
-        <div className="grid gap-3">
+        <div className="grid min-w-0 gap-3">
             {environments.map((environment) => (
                 <EnvironmentOptionButton
                     key={environment.id}
@@ -156,22 +156,22 @@ function EnvironmentOptionButton({
             type="button"
             onClick={() => onSelectEnvironment(environment.id)}
             disabled={isDisabled}
-            className={`rounded-2xl border px-4 py-4 text-left transition ${
+            className={`min-w-0 rounded-2xl border px-4 py-4 text-left transition ${
                 isSelected
                     ? 'border-blue-300 bg-blue-50 text-blue-900 shadow-sm'
                     : 'border-slate-200 bg-white text-slate-700 hover:border-slate-300 hover:shadow-sm'
             } disabled:cursor-not-allowed disabled:opacity-60`}
         >
-            <div className="flex items-center justify-between gap-3">
-                <div className="text-sm font-semibold">{environment.label}</div>
+            <div className="flex min-w-0 items-center justify-between gap-3">
+                <div className="min-w-0 break-words text-sm font-semibold">{environment.label}</div>
                 {isCurrent && (
-                    <span className="rounded-full border border-emerald-200 bg-emerald-50 px-2 py-0.5 text-[11px] font-semibold uppercase tracking-wide text-emerald-700">
+                    <span className="shrink-0 rounded-full border border-emerald-200 bg-emerald-50 px-2 py-0.5 text-[11px] font-semibold uppercase tracking-wide text-emerald-700">
                         Current
                     </span>
                 )}
             </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>
+            {environment.branch && <div className="mt-1 break-all font-mono text-xs">{environment.branch}</div>}
+            <div className="mt-2 break-words text-sm opacity-80">{environment.description}</div>
         </button>
     );
 }
@@ -191,7 +191,7 @@ function CustomRefPanel({ state, language, isControlsDisabled }: CustomRefPanelP
     }
 
     return (
-        <div className="space-y-3 rounded-xl border border-blue-200 bg-blue-50/40 p-4">
+        <div className="min-w-0 space-y-3 rounded-xl border border-blue-200 bg-blue-50/40 p-4">
             <CustomCommitPicker
                 language={language}
                 selectedRef={state.customRef}
@@ -225,10 +225,10 @@ function UpdateStartButton({ state }: UpdateStartButtonProps) {
             type="button"
             onClick={() => void state.startUpdate()}
             disabled={isUpdateStartDisabled(state)}
-            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"
+            className="inline-flex w-full min-w-0 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"
         >
             <UpdateStartButtonIcon buttonMode={buttonMode} />
-            {getUpdateStartButtonLabel(state)}
+            <span className="min-w-0 break-words text-center">{getUpdateStartButtonLabel(state)}</span>
         </button>
     );
 }
@@ -240,14 +240,14 @@ function UpdateStartButton({ state }: UpdateStartButtonProps) {
  */
 function UpdateStartButtonIcon({ buttonMode }: { readonly buttonMode: UpdateStartButtonMode }) {
     if (buttonMode === 'loading') {
-        return <Loader2 className="h-4 w-4 animate-spin" />;
+        return <Loader2 className="h-4 w-4 shrink-0 animate-spin" />;
     }
 
     if (buttonMode === 'rocket') {
-        return <Rocket className="h-4 w-4" />;
+        return <Rocket className="h-4 w-4 shrink-0" />;
     }
 
-    return <Download className="h-4 w-4" />;
+    return <Download className="h-4 w-4 shrink-0" />;
 }
 
 /**

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

@@ -3,11 +3,14 @@
 import { RefreshCcw } from 'lucide-react';
 import { Card } from '../../../components/Homepage/Card';
 import { useServerLanguage } from '../../../components/ServerLanguage/ServerLanguageProvider';
+import { AutomaticSelfUpdateConfigurationCard } from './AutomaticSelfUpdateConfigurationCard';
 import { CurrentDeploymentCard } from './CurrentDeploymentCard';
+import { InstalledVersionsCard } from './InstalledVersionsCard';
 import { PendingCommitsCard } from './PendingCommitsCard';
 import { TargetEnvironmentCard } from './TargetEnvironmentCard';
 import { UpdateJobCard } from './UpdateJobCard';
 import { useUpdateClientState } from './useUpdateClientState';
+import { UPDATE_PAGE_CARD_CLASS_NAME } from './updatePageCardClassName';
 
 /**
  * Client UI for standalone VPS branch-aware self-updates.
@@ -17,9 +20,9 @@ export function UpdateClient() {
     const state = useUpdateClientState();
 
     return (
-        <div className="container mx-auto space-y-6 px-4 py-8">
+        <div className="container mx-auto min-w-0 space-y-6 px-4 py-8">
             <div className="mt-20 flex flex-col gap-3 sm:flex-row sm:items-end sm:justify-between">
-                <div>
+                <div className="min-w-0">
                     <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 Live, Preview, Production, LTS, or a custom ref, and update
@@ -31,7 +34,7 @@ export function UpdateClient() {
                     type="button"
                     onClick={() => void state.loadOverview()}
                     disabled={state.isLoading || state.isStartingUpdate}
-                    className="inline-flex items-center gap-2 rounded-md border border-slate-300 bg-white px-4 py-2 text-sm font-semibold text-slate-700 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-60"
+                    className="inline-flex shrink-0 items-center gap-2 rounded-md border border-slate-300 bg-white px-4 py-2 text-sm font-semibold text-slate-700 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-60"
                 >
                     <RefreshCcw className={`h-4 w-4 ${state.isLoading ? 'animate-spin' : ''}`} />
                     Refresh
@@ -55,18 +58,25 @@ export function UpdateClient() {
                 </div>
             )}
 
-            <div className="grid gap-4 lg:grid-cols-[1.4fr_1fr]">
-                <Card className="hover:border-gray-200 hover:shadow-md">
+            <div className="grid min-w-0 items-start gap-4 lg:grid-cols-[minmax(0,1.4fr)_minmax(0,1fr)]">
+                <Card className={UPDATE_PAGE_CARD_CLASS_NAME}>
                     <CurrentDeploymentCard overview={state.overview} language={language} />
                 </Card>
 
-                <Card className="hover:border-gray-200 hover:shadow-md">
-                    <TargetEnvironmentCard state={state} language={language} />
-                </Card>
+                <div className="min-w-0 space-y-4">
+                    <Card className={UPDATE_PAGE_CARD_CLASS_NAME}>
+                        <TargetEnvironmentCard state={state} language={language} />
+                    </Card>
+
+                    <Card className={UPDATE_PAGE_CARD_CLASS_NAME}>
+                        <AutomaticSelfUpdateConfigurationCard state={state} />
+                    </Card>
+                </div>
             </div>
 
             <UpdateJobCard state={state} language={language} />
             <PendingCommitsCard overview={state.overview} language={language} />
+            <InstalledVersionsCard state={state} language={language} />
         </div>
     );
 }

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

@@ -0,0 +1,305 @@
+'use client';
+
+import type {
+    UpdateDatabaseMigrationPrefixSummary,
+    UpdateDatabaseMigrationSnapshot,
+    UpdateDatabaseMigrationStatus,
+} from './UpdateOverview';
+
+/**
+ * Props for the self-update database migrations panel.
+ *
+ * @private type of `<UpdateDatabaseMigrationsPanel/>`
+ */
+type UpdateDatabaseMigrationsPanelProps = {
+    readonly databaseMigrations: UpdateDatabaseMigrationSnapshot | null;
+    readonly isJobIdle: boolean;
+};
+
+/**
+ * Props for one database migration metric.
+ *
+ * @private type of `<UpdateDatabaseMigrationsPanel/>`
+ */
+type DatabaseMigrationMetricProps = {
+    readonly label: string;
+    readonly value: string;
+};
+
+/**
+ * Renders database migration status recorded during the latest self-update job.
+ *
+ * @private internal component of `<UpdateJobCard/>`
+ */
+export function UpdateDatabaseMigrationsPanel({
+    databaseMigrations,
+    isJobIdle,
+}: UpdateDatabaseMigrationsPanelProps) {
+    const status = databaseMigrations?.status ?? 'pending';
+    const appliedCount = getAppliedDatabaseMigrationCount(databaseMigrations);
+    const processedPrefixCount = getProcessedDatabaseMigrationPrefixCount(databaseMigrations);
+
+    return (
+        <section className="min-w-0 rounded-xl border border-slate-200 bg-slate-50/70 px-4 py-4">
+            <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+                <div className="min-w-0">
+                    <h3 className="text-sm font-semibold text-slate-900">Database migrations</h3>
+                    <p className="mt-1 text-sm text-slate-600">
+                        {formatDatabaseMigrationStatusMessage(databaseMigrations, isJobIdle)}
+                    </p>
+                </div>
+                <DatabaseMigrationStatusBadge status={status} />
+            </div>
+
+            <dl className="mt-4 grid min-w-0 gap-3 text-sm text-slate-600 md:grid-cols-3">
+                <DatabaseMigrationMetric
+                    label="Applied"
+                    value={appliedCount === null ? 'Not recorded' : String(appliedCount)}
+                />
+                <DatabaseMigrationMetric
+                    label="Prefixes"
+                    value={processedPrefixCount === null ? 'Not recorded' : String(processedPrefixCount)}
+                />
+                <DatabaseMigrationMetric
+                    label="Migration files"
+                    value={
+                        databaseMigrations === null || databaseMigrations.totalMigrationFiles === null
+                            ? 'Not recorded'
+                            : String(databaseMigrations.totalMigrationFiles)
+                    }
+                />
+            </dl>
+
+            {databaseMigrations?.summaryFilePath && (
+                <div className="mt-3 text-xs text-slate-500">
+                    Migration summary:
+                    <span className="ml-2 break-all font-mono text-slate-700">
+                        {databaseMigrations.summaryFilePath}
+                    </span>
+                </div>
+            )}
+
+            {databaseMigrations && databaseMigrations.perPrefix.length > 0 && (
+                <div className="mt-4 space-y-2">
+                    {databaseMigrations.perPrefix.map((prefixSummary, index) => (
+                        <DatabaseMigrationPrefixSummaryRow
+                            key={`${prefixSummary.prefix}:${index}`}
+                            prefixSummary={prefixSummary}
+                        />
+                    ))}
+                </div>
+            )}
+        </section>
+    );
+}
+
+/**
+ * Renders one database migration metric.
+ *
+ * @private internal component of `<UpdateDatabaseMigrationsPanel/>`
+ */
+function DatabaseMigrationMetric({ label, value }: DatabaseMigrationMetricProps) {
+    return (
+        <div className="min-w-0 rounded-xl border border-slate-200 bg-white px-4 py-3">
+            <dt className="text-xs font-semibold uppercase tracking-wide text-slate-500">{label}</dt>
+            <dd className="mt-1 break-words text-slate-900">{value}</dd>
+        </div>
+    );
+}
+
+/**
+ * Renders one prefix row inside the database migration panel.
+ *
+ * @private internal component of `<UpdateDatabaseMigrationsPanel/>`
+ */
+function DatabaseMigrationPrefixSummaryRow({
+    prefixSummary,
+}: {
+    readonly prefixSummary: UpdateDatabaseMigrationPrefixSummary;
+}) {
+    const isAppliedMigrationFileListVisible = prefixSummary.appliedMigrationFiles.length > 0;
+
+    return (
+        <div className="min-w-0 rounded-lg border border-slate-200 bg-white px-3 py-2">
+            <div className="flex flex-col gap-1 sm:flex-row sm:items-center sm:justify-between">
+                <span className="break-all font-mono text-xs text-slate-700">
+                    {formatDatabaseMigrationPrefix(prefixSummary.prefix)}
+                </span>
+                <span className="shrink-0 text-xs font-semibold text-slate-500">
+                    {formatCountWithNoun(prefixSummary.appliedCount, 'migration file', 'migration files')} applied
+                </span>
+            </div>
+            {isAppliedMigrationFileListVisible && (
+                <ul className="mt-2 space-y-1">
+                    {prefixSummary.appliedMigrationFiles.map((migrationFile) => (
+                        <li key={migrationFile} className="break-all font-mono text-xs text-slate-600">
+                            {migrationFile}
+                        </li>
+                    ))}
+                </ul>
+            )}
+        </div>
+    );
+}
+
+/**
+ * Renders the database migration status badge.
+ *
+ * @private internal component of `<UpdateDatabaseMigrationsPanel/>`
+ */
+function DatabaseMigrationStatusBadge({ status }: { readonly status: UpdateDatabaseMigrationStatus }) {
+    return (
+        <span
+            className={`inline-flex shrink-0 items-center gap-2 rounded-full border px-3 py-1 text-xs font-semibold uppercase tracking-wide ${getDatabaseMigrationStatusClassName(
+                status,
+            )}`}
+        >
+            {status}
+        </span>
+    );
+}
+
+/**
+ * Formats the database migration status message.
+ *
+ * @param databaseMigrations - Migration snapshot recorded on the job.
+ * @param isJobIdle - Whether no update job has been started yet.
+ * @returns Human-readable status message.
+ */
+function formatDatabaseMigrationStatusMessage(
+    databaseMigrations: UpdateDatabaseMigrationSnapshot | null,
+    isJobIdle: boolean,
+): string {
+    if (isJobIdle) {
+        return 'No self-update database migration run has been recorded yet.';
+    }
+
+    if (!databaseMigrations) {
+        return 'Database migration details are not available for this update.';
+    }
+
+    const appliedCount = getAppliedDatabaseMigrationCount(databaseMigrations) ?? 0;
+    const processedPrefixCount = getProcessedDatabaseMigrationPrefixCount(databaseMigrations) ?? 0;
+
+    if (databaseMigrations.status === 'running') {
+        return 'Agents Server database migrations are running.';
+    }
+
+    if (databaseMigrations.status === 'succeeded') {
+        if (appliedCount === 0) {
+            return `Checked ${formatNullableMigrationFileCount(databaseMigrations.totalMigrationFiles)} across ${formatCountWithNoun(
+                processedPrefixCount,
+                'prefix',
+                'prefixes',
+            )}. No pending migrations were applied.`;
+        }
+
+        return `Applied ${formatCountWithNoun(appliedCount, 'migration file', 'migration files')} across ${formatCountWithNoun(
+            processedPrefixCount,
+            'prefix',
+            'prefixes',
+        )}.`;
+    }
+
+    if (databaseMigrations.status === 'failed') {
+        return databaseMigrations.errorMessage || 'Agents Server database migrations failed during self-update.';
+    }
+
+    if (databaseMigrations.status === 'skipped') {
+        return databaseMigrations.errorMessage || 'PostgreSQL database migrations were skipped for this update.';
+    }
+
+    if (databaseMigrations.status === 'unknown') {
+        return 'Database migration details were not recorded for this update job.';
+    }
+
+    return 'Waiting for the database migration step.';
+}
+
+/**
+ * Counts applied migration files across all prefixes.
+ *
+ * @param databaseMigrations - Migration snapshot recorded on the job.
+ * @returns Applied migration count or `null` when no snapshot is available.
+ */
+function getAppliedDatabaseMigrationCount(databaseMigrations: UpdateDatabaseMigrationSnapshot | null): number | null {
+    if (!databaseMigrations) {
+        return null;
+    }
+
+    return databaseMigrations.perPrefix.reduce((total, prefixSummary) => total + prefixSummary.appliedCount, 0);
+}
+
+/**
+ * Counts processed prefixes from the migration snapshot.
+ *
+ * @param databaseMigrations - Migration snapshot recorded on the job.
+ * @returns Prefix count or `null` when no snapshot is available.
+ */
+function getProcessedDatabaseMigrationPrefixCount(
+    databaseMigrations: UpdateDatabaseMigrationSnapshot | null,
+): number | null {
+    if (!databaseMigrations) {
+        return null;
+    }
+
+    return databaseMigrations.processedPrefixes.length || databaseMigrations.perPrefix.length;
+}
+
+/**
+ * Formats one migration prefix for display.
+ *
+ * @param prefix - Raw table prefix.
+ * @returns Display label.
+ */
+function formatDatabaseMigrationPrefix(prefix: string): string {
+    return prefix || '<default>';
+}
+
+/**
+ * Formats a nullable migration file count for a sentence.
+ *
+ * @param value - Count or `null`.
+ * @returns Count string or fallback text.
+ */
+function formatNullableMigrationFileCount(value: number | null): string {
+    return value === null ? 'the available migration files' : formatCountWithNoun(value, 'migration file', 'migration files');
+}
+
+/**
+ * Formats a count together with its singular/plural noun.
+ *
+ * @param count - Numeric count.
+ * @param singularNoun - Noun used when count is one.
+ * @param pluralNoun - Noun used otherwise.
+ * @returns Count with noun.
+ */
+function formatCountWithNoun(count: number, singularNoun: string, pluralNoun: string): string {
+    return `${count} ${count === 1 ? singularNoun : pluralNoun}`;
+}
+
+/**
+ * Resolves status badge styling for database migration status.
+ *
+ * @param status - Current database migration status.
+ * @returns Tailwind class list for the status badge.
+ */
+function getDatabaseMigrationStatusClassName(status: UpdateDatabaseMigrationStatus): string {
+    if (status === 'running') {
+        return 'border-blue-200 bg-blue-50 text-blue-700';
+    }
+
+    if (status === 'failed') {
+        return 'border-rose-200 bg-rose-50 text-rose-700';
+    }
+
+    if (status === 'succeeded') {
+        return 'border-emerald-200 bg-emerald-50 text-emerald-700';
+    }
+
+    if (status === 'skipped') {
+        return 'border-amber-200 bg-amber-50 text-amber-700';
+    }
+
+    return 'border-slate-200 bg-white text-slate-500';
+}