@promptbook/cli 0.113.0-1 → 0.113.0-10

package/apps/agents-server/src/utils/vpsSelfUpdate/listVpsSelfUpdateCandidateCommits.ts

@@ -0,0 +1,217 @@
+import { resolveManagedPromptbookRepositoryDirectory } from './vpsSelfUpdateConfiguration';
+import { readConfiguredVpsSelfUpdateOriginRepositoryUrl } from './vpsSelfUpdateOriginRepository';
+import { GIT_LOG_FIELD_SEPARATOR, runGitInRepository } from './vpsSelfUpdateRepository';
+import type { VpsSelfUpdateCandidateCommit, VpsSelfUpdateCandidateCommitsFilter } from './vpsSelfUpdateTypes';
+
+/**
+ * Hard ceiling for the candidate-commit listing to avoid streaming the entire repository to the browser.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const VPS_SELF_UPDATE_MAX_CANDIDATE_COMMITS = 500;
+
+/**
+ * Default candidate-commit count returned to the browser.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const VPS_SELF_UPDATE_DEFAULT_CANDIDATE_COMMITS = 200;
+
+/**
+ * Lists commits from the managed repository for the custom-target picker.
+ *
+ * Fetches the latest refs from the configured upstream first so the picker can include
+ * recent commits that have not been deployed yet, then resolves branches/tags per commit.
+ *
+ * @param filter - Filter applied to the result.
+ * @returns Browser-safe commit list.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function listVpsSelfUpdateCandidateCommits(
+    filter: VpsSelfUpdateCandidateCommitsFilter = {},
+): Promise<ReadonlyArray<VpsSelfUpdateCandidateCommit>> {
+    if (process.platform !== 'linux') {
+        return [];
+    }
+
+    const repositoryDirectory = await resolveManagedPromptbookRepositoryDirectory();
+    if (!repositoryDirectory) {
+        return [];
+    }
+
+    const originRepositoryUrl = await readConfiguredVpsSelfUpdateOriginRepositoryUrl();
+    await runGitInRepository(repositoryDirectory, [
+        'fetch',
+        '--no-tags',
+        '--prune',
+        '--depth=200',
+        originRepositoryUrl,
+        '+refs/heads/*:refs/remotes/origin/*',
+    ]);
+    await runGitInRepository(repositoryDirectory, [
+        'fetch',
+        '--tags',
+        '--force',
+        originRepositoryUrl,
+        '+refs/tags/*:refs/tags/*',
+    ]);
+
+    const limit = clampVpsSelfUpdateCandidateCommitLimit(filter.limit);
+    const gitLogArguments = [
+        'log',
+        `--max-count=${VPS_SELF_UPDATE_MAX_CANDIDATE_COMMITS}`,
+        '--all',
+        `--format=%H${GIT_LOG_FIELD_SEPARATOR}%aI${GIT_LOG_FIELD_SEPARATOR}%an${GIT_LOG_FIELD_SEPARATOR}%ae${GIT_LOG_FIELD_SEPARATOR}%s`,
+    ];
+
+    if (filter.authoredAfter) {
+        gitLogArguments.push(`--since=${filter.authoredAfter}`);
+    }
+    if (filter.authoredBefore) {
+        gitLogArguments.push(`--until=${filter.authoredBefore}`);
+    }
+
+    const gitLogOutput = await runGitInRepository(repositoryDirectory, gitLogArguments);
+    if (!gitLogOutput) {
+        return [];
+    }
+
+    const branchesByCommit = await readVpsSelfUpdateRefsByCommit(repositoryDirectory, 'refs/remotes/origin');
+    const tagsByCommit = await readVpsSelfUpdateRefsByCommit(repositoryDirectory, 'refs/tags');
+    const searchText = filter.searchText?.trim().toLowerCase() || '';
+
+    const commits: Array<VpsSelfUpdateCandidateCommit> = [];
+    for (const line of gitLogOutput.split('\n')) {
+        if (!line) {
+            continue;
+        }
+
+        const fields = line.split(GIT_LOG_FIELD_SEPARATOR);
+        const commitSha = fields[0] ?? '';
+        if (!commitSha) {
+            continue;
+        }
+
+        const authoredAt = fields[1] ?? '';
+        const authorName = fields[2] ?? '';
+        const authorEmail = fields[3] ?? '';
+        const subject = fields.slice(4).join(GIT_LOG_FIELD_SEPARATOR);
+        const branches = branchesByCommit.get(commitSha) ?? [];
+        const tags = tagsByCommit.get(commitSha) ?? [];
+
+        if (
+            searchText &&
+            !matchesVpsSelfUpdateCandidateCommitSearchText(searchText, commitSha, subject, authorName, branches, tags)
+        ) {
+            continue;
+        }
+
+        commits.push({
+            commitSha,
+            shortCommitSha: commitSha.slice(0, 7),
+            subject,
+            authorName,
+            authorEmail,
+            authoredAt,
+            branches,
+            tags,
+            isReleaseTag: tags.length > 0,
+        });
+
+        if (commits.length >= limit) {
+            break;
+        }
+    }
+
+    return commits;
+}
+
+/**
+ * Clamps an external limit value to the safe candidate-commit range.
+ *
+ * @param value - Raw user-provided limit.
+ * @returns Clamped value.
+ */
+function clampVpsSelfUpdateCandidateCommitLimit(value: number | null | undefined): number {
+    if (value === null || value === undefined || !Number.isFinite(value)) {
+        return VPS_SELF_UPDATE_DEFAULT_CANDIDATE_COMMITS;
+    }
+
+    return Math.max(1, Math.min(VPS_SELF_UPDATE_MAX_CANDIDATE_COMMITS, Math.floor(value)));
+}
+
+/**
+ * Returns `true` when one commit matches the free-text filter applied to the picker.
+ *
+ * @param searchText - Lower-cased search text.
+ * @param commitSha - Full commit hash.
+ * @param subject - Commit subject.
+ * @param authorName - Author display name.
+ * @param branches - Branches pointing at the commit.
+ * @param tags - Tags pointing at the commit.
+ * @returns `true` when the commit should be included.
+ */
+function matchesVpsSelfUpdateCandidateCommitSearchText(
+    searchText: string,
+    commitSha: string,
+    subject: string,
+    authorName: string,
+    branches: ReadonlyArray<string>,
+    tags: ReadonlyArray<string>,
+): boolean {
+    if (commitSha.toLowerCase().startsWith(searchText)) {
+        return true;
+    }
+
+    if (subject.toLowerCase().includes(searchText)) {
+        return true;
+    }
+
+    if (authorName.toLowerCase().includes(searchText)) {
+        return true;
+    }
+
+    if (branches.some((branch) => branch.toLowerCase().includes(searchText))) {
+        return true;
+    }
+
+    return tags.some((tag) => tag.toLowerCase().includes(searchText));
+}
+
+/**
+ * Reads refs grouped by commit hash so the picker can annotate each commit with its branches/tags.
+ *
+ * @param repositoryDirectory - Repository checkout path.
+ * @param refPrefix - Ref namespace passed to `git for-each-ref` (e.g. `refs/tags`).
+ * @returns Map keyed by commit hash.
+ */
+async function readVpsSelfUpdateRefsByCommit(
+    repositoryDirectory: string,
+    refPrefix: string,
+): Promise<Map<string, Array<string>>> {
+    const output = await runGitInRepository(repositoryDirectory, [
+        'for-each-ref',
+        '--format=%(objectname)\x1f%(refname:short)',
+        refPrefix,
+    ]);
+    const refsByCommit = new Map<string, Array<string>>();
+
+    if (!output) {
+        return refsByCommit;
+    }
+
+    for (const line of output.split('\n')) {
+        const [commitSha, refName] = line.split('\x1f');
+        if (!commitSha || !refName) {
+            continue;
+        }
+
+        const cleanRefName = refName.replace(/^origin\//u, '');
+        const list = refsByCommit.get(commitSha) ?? [];
+        list.push(cleanRefName);
+        refsByCommit.set(commitSha, list);
+    }
+
+    return refsByCommit;
+}

package/apps/agents-server/src/utils/vpsSelfUpdate/readPersistedVpsSelfUpdateJob.ts

@@ -0,0 +1,310 @@
+import { resolveVpsSelfUpdateEnvironment } from './vpsSelfUpdateEnvironment';
+import { VPS_SELF_UPDATE_STALE_ERROR_MESSAGE } from './vpsSelfUpdateJobConstants';
+import {
+    decodeVpsSelfUpdateStatusField,
+    readLastVpsSelfUpdateTextFileChunk,
+    readVpsSelfUpdateStatusFile,
+    resolveVpsSelfUpdateLogFilePath,
+} from './vpsSelfUpdateStateFiles';
+import type {
+    VpsSelfUpdateDatabaseMigrationSnapshot,
+    VpsSelfUpdateDatabaseMigrationStatus,
+    VpsSelfUpdateJobSnapshot,
+    VpsSelfUpdateJobStatus,
+} from './vpsSelfUpdateTypes';
+import type { VpsSelfUpdateJobTrigger } from './vpsSelfUpdateTypes';
+
+/**
+ * Options for reading the shell-owned self-update status snapshot.
+ */
+type ReadPersistedVpsSelfUpdateJobOptions = {
+    /**
+     * Whether to include the log tail in the returned snapshot.
+     */
+    readonly isLogTailIncluded?: boolean;
+};
+
+/**
+ * Status values accepted from the shell-owned database migration status field.
+ */
+const VPS_SELF_UPDATE_DATABASE_MIGRATION_STATUSES = new Set<VpsSelfUpdateDatabaseMigrationStatus>([
+    'pending',
+    'running',
+    'succeeded',
+    'failed',
+    'skipped',
+    'unknown',
+]);
+
+/**
+ * Reads a lightweight snapshot of the currently persisted standalone VPS self-update job.
+ *
+ * Reads only the persisted status file and its log tail — no git access, no remote fetching —
+ * so it is safe to call from frequent polling loops such as the admin task manager.
+ *
+ * @returns Parsed job snapshot (status `idle` when no job has ever been persisted).
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readVpsSelfUpdateJobSnapshot(): Promise<VpsSelfUpdateJobSnapshot> {
+    return readPersistedVpsSelfUpdateJob({ isLogTailIncluded: false });
+}
+
+/**
+ * Reads one persisted update-job snapshot from disk.
+ *
+ * @param options - Snapshot loading options.
+ * @returns Parsed job snapshot.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readPersistedVpsSelfUpdateJob(
+    options: ReadPersistedVpsSelfUpdateJobOptions = {},
+): Promise<VpsSelfUpdateJobSnapshot> {
+    const statusEntries = await readVpsSelfUpdateStatusFile();
+    const jobId = statusEntries.get('JOB_ID') || null;
+    const targetBranch = statusEntries.get('TARGET_REF') || null;
+    const targetEnvironment = resolveVpsSelfUpdateEnvironment(targetBranch);
+    const pid = parseNullableVpsSelfUpdateInteger(statusEntries.get('PID'));
+    const currentStep = decodeVpsSelfUpdateStatusField(statusEntries.get('CURRENT_STEP_B64'));
+    const errorMessage = decodeVpsSelfUpdateStatusField(statusEntries.get('ERROR_MESSAGE_B64'));
+    const logFilePath = statusEntries.get('LOG_FILE') || resolveVpsSelfUpdateLogFilePath();
+    const rawStatus = statusEntries.get('STATUS');
+    const status = isVpsSelfUpdateJobStatus(rawStatus) ? rawStatus : 'idle';
+    const rawTrigger = statusEntries.get('TRIGGER');
+    const trigger = isVpsSelfUpdateJobTrigger(rawTrigger) ? rawTrigger : 'manual';
+    const isStale = status === 'running' && pid !== null ? !(await isVpsSelfUpdateProcessAlive(pid)) : false;
+    const databaseMigrations = parseVpsSelfUpdateDatabaseMigrationSnapshot(statusEntries, status);
+
+    return {
+        jobId,
+        status: isStale ? 'failed' : status,
+        trigger,
+        pid,
+        targetBranch,
+        targetEnvironment,
+        currentStep,
+        currentCommitSha: statusEntries.get('CURRENT_COMMIT') || null,
+        targetCommitSha: statusEntries.get('TARGET_COMMIT') || null,
+        errorMessage: isStale && !errorMessage ? VPS_SELF_UPDATE_STALE_ERROR_MESSAGE : errorMessage,
+        startedAt: statusEntries.get('STARTED_AT') || null,
+        finishedAt: statusEntries.get('FINISHED_AT') || null,
+        isStale,
+        logTail: options.isLogTailIncluded === false ? null : await readLastVpsSelfUpdateTextFileChunk(logFilePath),
+        logFilePath,
+        databaseMigrations,
+    };
+}
+
+/**
+ * Checks whether a detached update process is still alive.
+ *
+ * @param pid - Candidate process id.
+ * @returns `true` when the process exists.
+ */
+async function isVpsSelfUpdateProcessAlive(pid: number): Promise<boolean> {
+    if (!Number.isFinite(pid) || pid <= 0) {
+        return false;
+    }
+
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (error) {
+        return (error as NodeJS.ErrnoException).code === 'EPERM';
+    }
+}
+
+/**
+ * Parses one optional integer field.
+ *
+ * @param value - Raw string value.
+ * @returns Parsed integer or `null`.
+ */
+function parseNullableVpsSelfUpdateInteger(value: string | undefined): number | null {
+    if (!value) {
+        return null;
+    }
+
+    const parsedValue = Number.parseInt(value, 10);
+    return Number.isFinite(parsedValue) ? parsedValue : null;
+}
+
+/**
+ * Type guard for persisted job statuses.
+ *
+ * @param value - Raw status value.
+ * @returns `true` when supported.
+ */
+function isVpsSelfUpdateJobStatus(value: string | undefined): value is VpsSelfUpdateJobStatus {
+    return value === 'idle' || value === 'running' || value === 'succeeded' || value === 'failed';
+}
+
+/**
+ * Type guard for persisted job triggers.
+ *
+ * @param value - Raw trigger value.
+ * @returns `true` when supported.
+ */
+function isVpsSelfUpdateJobTrigger(value: string | undefined): value is VpsSelfUpdateJobTrigger {
+    return value === 'manual' || value === 'automatic';
+}
+
+/**
+ * Parses database migration status and summary fields from the shell-owned update status file.
+ *
+ * @param statusEntries - Parsed status-file fields.
+ * @param jobStatus - Persisted self-update job status.
+ * @returns Browser-safe database migration snapshot.
+ */
+function parseVpsSelfUpdateDatabaseMigrationSnapshot(
+    statusEntries: ReadonlyMap<string, string>,
+    jobStatus: VpsSelfUpdateJobStatus,
+): VpsSelfUpdateDatabaseMigrationSnapshot {
+    const rawStatus = statusEntries.get('DATABASE_MIGRATION_STATUS');
+    const summaryFilePath = statusEntries.get('DATABASE_MIGRATION_SUMMARY_FILE') || null;
+    const errorMessage = decodeVpsSelfUpdateStatusField(statusEntries.get('DATABASE_MIGRATION_ERROR_MESSAGE_B64'));
+    const summary = parseVpsSelfUpdateDatabaseMigrationSummary(
+        decodeVpsSelfUpdateStatusField(statusEntries.get('DATABASE_MIGRATION_SUMMARY_B64')),
+    );
+
+    return {
+        status: isVpsSelfUpdateDatabaseMigrationStatus(rawStatus)
+            ? rawStatus
+            : resolveMissingVpsSelfUpdateDatabaseMigrationStatus(jobStatus),
+        ...summary,
+        errorMessage,
+        summaryFilePath,
+    };
+}
+
+/**
+ * Parses the machine-readable migration summary produced by the migration CLI.
+ *
+ * @param rawSummary - JSON summary string from `PTBK_DATABASE_MIGRATION_SUMMARY_FILE`.
+ * @returns Normalized migration summary fields.
+ */
+function parseVpsSelfUpdateDatabaseMigrationSummary(
+    rawSummary: string | null,
+): Pick<
+    VpsSelfUpdateDatabaseMigrationSnapshot,
+    'processedPrefixes' | 'totalMigrationFiles' | 'perPrefix' | 'isSkippedDueToActiveMigrationLock'
+> {
+    if (!rawSummary) {
+        return createEmptyVpsSelfUpdateDatabaseMigrationSummary();
+    }
+
+    try {
+        const parsedSummary = JSON.parse(rawSummary) as unknown;
+        if (!isRecord(parsedSummary)) {
+            return createEmptyVpsSelfUpdateDatabaseMigrationSummary();
+        }
+
+        return {
+            processedPrefixes: parseStringArray(parsedSummary.processedPrefixes),
+            totalMigrationFiles: parseNullableNonNegativeInteger(parsedSummary.totalMigrationFiles),
+            perPrefix: parseVpsSelfUpdateDatabaseMigrationPrefixSummaries(parsedSummary.perPrefix),
+            isSkippedDueToActiveMigrationLock:
+                typeof parsedSummary.isSkippedDueToActiveMigrationLock === 'boolean'
+                    ? parsedSummary.isSkippedDueToActiveMigrationLock
+                    : null,
+        };
+    } catch {
+        return createEmptyVpsSelfUpdateDatabaseMigrationSummary();
+    }
+}
+
+/**
+ * Creates empty migration summary values for jobs without recorded migration details.
+ *
+ * @returns Empty database migration summary.
+ */
+function createEmptyVpsSelfUpdateDatabaseMigrationSummary(): Pick<
+    VpsSelfUpdateDatabaseMigrationSnapshot,
+    'processedPrefixes' | 'totalMigrationFiles' | 'perPrefix' | 'isSkippedDueToActiveMigrationLock'
+> {
+    return {
+        processedPrefixes: [],
+        totalMigrationFiles: null,
+        perPrefix: [],
+        isSkippedDueToActiveMigrationLock: null,
+    };
+}
+
+/**
+ * Resolves the migration status used when older status files do not contain migration fields.
+ *
+ * @param jobStatus - Persisted self-update job status.
+ * @returns Migration status fallback.
+ */
+function resolveMissingVpsSelfUpdateDatabaseMigrationStatus(
+    jobStatus: VpsSelfUpdateJobStatus,
+): VpsSelfUpdateDatabaseMigrationStatus {
+    return jobStatus === 'idle' ? 'pending' : 'unknown';
+}
+
+/**
+ * Type guard for persisted database migration statuses.
+ *
+ * @param value - Raw status value.
+ * @returns `true` when supported.
+ */
+function isVpsSelfUpdateDatabaseMigrationStatus(
+    value: string | undefined,
+): value is VpsSelfUpdateDatabaseMigrationStatus {
+    return value !== undefined && VPS_SELF_UPDATE_DATABASE_MIGRATION_STATUSES.has(value as VpsSelfUpdateDatabaseMigrationStatus);
+}
+
+/**
+ * Parses per-prefix migration summaries from untrusted JSON.
+ *
+ * @param value - Raw per-prefix JSON value.
+ * @returns Normalized per-prefix summaries.
+ */
+function parseVpsSelfUpdateDatabaseMigrationPrefixSummaries(
+    value: unknown,
+): VpsSelfUpdateDatabaseMigrationSnapshot['perPrefix'] {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+
+    return value.filter(isRecord).map((prefixSummary) => ({
+        prefix: typeof prefixSummary.prefix === 'string' ? prefixSummary.prefix : '',
+        appliedCount: parseNullableNonNegativeInteger(prefixSummary.appliedCount) ?? 0,
+        appliedMigrationFiles: parseStringArray(prefixSummary.appliedMigrationFiles),
+    }));
+}
+
+/**
+ * Parses an array of strings from untrusted JSON.
+ *
+ * @param value - Raw JSON value.
+ * @returns String array.
+ */
+function parseStringArray(value: unknown): Array<string> {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+
+    return value.filter((item): item is string => typeof item === 'string');
+}
+
+/**
+ * Parses a non-negative integer from untrusted JSON.
+ *
+ * @param value - Raw JSON value.
+ * @returns Parsed integer or `null`.
+ */
+function parseNullableNonNegativeInteger(value: unknown): number | null {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+/**
+ * Checks whether a raw JSON value is a record.
+ *
+ * @param value - Raw JSON value.
+ * @returns `true` when the value is a non-array object.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/apps/agents-server/src/utils/vpsSelfUpdate/readVpsSelfUpdateOverview.ts

@@ -0,0 +1,178 @@
+import { resolveVpsInstallerScriptPath } from '../vpsConfiguration';
+import {
+    readCurrentVpsSelfUpdateEnvironment,
+    resolveManagedPromptbookRepositoryDirectory,
+} from './vpsSelfUpdateConfiguration';
+import { readVpsSelfUpdateAutomaticConfiguration } from './vpsSelfUpdateAutomaticConfiguration';
+import { VPS_SELF_UPDATE_ENVIRONMENTS, type VpsSelfUpdateEnvironmentOption } from './vpsSelfUpdateEnvironment';
+import {
+    readConfiguredVpsSelfUpdateOriginRepositoryUrl,
+    VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL,
+} from './vpsSelfUpdateOriginRepository';
+import { readPersistedVpsSelfUpdateJob } from './readPersistedVpsSelfUpdateJob';
+import { resolveVpsSelfUpdateJobForOverview } from './resolveVpsSelfUpdateJobForOverview';
+import {
+    listVpsSelfUpdateInstalledVersions,
+    readAgentsServerGcKeepVersionsCount,
+} from './vpsSelfUpdateInstalledVersions';
+import {
+    abbreviateCommitSha,
+    countCommitsBetween,
+    listCommitsBetween,
+    readCommitMetadataFromRepository,
+    readLatestRemoteBranchCommitSha,
+    refreshVpsSelfUpdateRemoteBranch,
+} from './vpsSelfUpdateRepository';
+import type { VpsSelfUpdateJobSnapshot, VpsSelfUpdateOverview } from './vpsSelfUpdateTypes';
+
+/**
+ * Reads the current standalone VPS self-update overview.
+ *
+ * @returns Browser-safe update summary for the super-admin UI.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readVpsSelfUpdateOverview(): Promise<VpsSelfUpdateOverview> {
+    const currentEnvironment = await readCurrentVpsSelfUpdateEnvironment();
+    const repositoryDirectory = await resolveManagedPromptbookRepositoryDirectory();
+    const scriptPath = await resolveVpsInstallerScriptPath();
+    const job = await readPersistedVpsSelfUpdateJob();
+    const originRepositoryUrl = await readConfiguredVpsSelfUpdateOriginRepositoryUrl();
+    const automaticConfiguration = await readVpsSelfUpdateAutomaticConfiguration();
+    const installedVersions = await listVpsSelfUpdateInstalledVersions();
+    const garbageCollectionKeepVersionsCount = await readAgentsServerGcKeepVersionsCount();
+
+    if (process.platform !== 'linux') {
+        return createUnavailableOverview({
+            currentEnvironment,
+            repositoryDirectory,
+            job,
+            originRepositoryUrl,
+            automaticConfiguration,
+            installedVersions,
+            garbageCollectionKeepVersionsCount,
+            unavailableReason: 'Self-update is available only on the standalone Linux VPS deployment.',
+        });
+    }
+
+    if (!scriptPath) {
+        return createUnavailableOverview({
+            currentEnvironment,
+            repositoryDirectory,
+            job,
+            originRepositoryUrl,
+            automaticConfiguration,
+            installedVersions,
+            garbageCollectionKeepVersionsCount,
+            unavailableReason: 'The shared VPS installer script could not be found on this server.',
+        });
+    }
+
+    if (!repositoryDirectory) {
+        return createUnavailableOverview({
+            currentEnvironment,
+            repositoryDirectory: null,
+            job,
+            originRepositoryUrl,
+            automaticConfiguration,
+            installedVersions,
+            garbageCollectionKeepVersionsCount,
+            unavailableReason: 'The managed Promptbook repository directory is not configured on this server.',
+        });
+    }
+
+    await refreshVpsSelfUpdateRemoteBranch(repositoryDirectory, currentEnvironment.branch, originRepositoryUrl);
+
+    const [currentCommit, latestRemoteCommitSha] = await Promise.all([
+        readCommitMetadataFromRepository(repositoryDirectory, 'HEAD'),
+        readLatestRemoteBranchCommitSha(repositoryDirectory, currentEnvironment.branch, originRepositoryUrl),
+    ]);
+    const latestRemoteCommit = latestRemoteCommitSha
+        ? await readCommitMetadataFromRepository(repositoryDirectory, latestRemoteCommitSha)
+        : null;
+    const currentCommitSha = currentCommit?.commitSha ?? null;
+    const latestRemoteCommitResolvedSha = latestRemoteCommit?.commitSha ?? latestRemoteCommitSha;
+    const commitsBehindCount =
+        currentCommitSha && latestRemoteCommitResolvedSha
+            ? await countCommitsBetween(repositoryDirectory, currentCommitSha, latestRemoteCommitResolvedSha)
+            : null;
+    const pendingCommits =
+        currentCommitSha && latestRemoteCommitResolvedSha
+            ? await listCommitsBetween(repositoryDirectory, currentCommitSha, latestRemoteCommitResolvedSha)
+            : [];
+    const resolvedJob = resolveVpsSelfUpdateJobForOverview(job, {
+        currentEnvironment,
+        currentCommitSha,
+    });
+
+    return {
+        isAvailable: Boolean(currentCommitSha),
+        unavailableReason: currentCommitSha ? null : 'The managed Promptbook repository checkout is not available.',
+        environments: VPS_SELF_UPDATE_ENVIRONMENTS,
+        currentEnvironment,
+        repositoryDirectory,
+        currentCommitSha,
+        currentCommitShortSha: abbreviateCommitSha(currentCommitSha),
+        currentCommitMessage: currentCommit?.subject ?? null,
+        currentCommitDate: currentCommit?.authoredAt ?? null,
+        latestRemoteCommitSha: latestRemoteCommitResolvedSha,
+        latestRemoteCommitShortSha: abbreviateCommitSha(latestRemoteCommitResolvedSha),
+        latestRemoteCommitDate: latestRemoteCommit?.authoredAt ?? null,
+        latestRemoteCommitMessage: latestRemoteCommit?.subject ?? null,
+        commitsBehindCount,
+        pendingCommits,
+        isUpdateAvailable: Boolean(
+            currentCommitSha && latestRemoteCommitResolvedSha && currentCommitSha !== latestRemoteCommitResolvedSha,
+        ),
+        originRepositoryUrl,
+        isOriginRepositoryDefault: originRepositoryUrl === VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL,
+        defaultOriginRepositoryUrl: VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL,
+        automaticConfiguration,
+        installedVersions,
+        garbageCollectionKeepVersionsCount,
+        job: resolvedJob,
+    };
+}
+
+/**
+ * Builds the placeholder overview used when self-update is unavailable on the host.
+ *
+ * @param context - Fields shared across every unavailable-overview branch.
+ * @returns Browser-safe placeholder overview.
+ */
+function createUnavailableOverview(context: {
+    readonly currentEnvironment: VpsSelfUpdateEnvironmentOption;
+    readonly repositoryDirectory: string | null;
+    readonly job: VpsSelfUpdateJobSnapshot;
+    readonly originRepositoryUrl: string;
+    readonly automaticConfiguration: VpsSelfUpdateOverview['automaticConfiguration'];
+    readonly installedVersions: VpsSelfUpdateOverview['installedVersions'];
+    readonly garbageCollectionKeepVersionsCount: number;
+    readonly unavailableReason: string;
+}): VpsSelfUpdateOverview {
+    return {
+        isAvailable: false,
+        unavailableReason: context.unavailableReason,
+        environments: VPS_SELF_UPDATE_ENVIRONMENTS,
+        currentEnvironment: context.currentEnvironment,
+        repositoryDirectory: context.repositoryDirectory,
+        currentCommitSha: null,
+        currentCommitShortSha: null,
+        currentCommitMessage: null,
+        currentCommitDate: null,
+        latestRemoteCommitSha: null,
+        latestRemoteCommitShortSha: null,
+        latestRemoteCommitDate: null,
+        latestRemoteCommitMessage: null,
+        commitsBehindCount: null,
+        pendingCommits: [],
+        isUpdateAvailable: false,
+        originRepositoryUrl: context.originRepositoryUrl,
+        isOriginRepositoryDefault: context.originRepositoryUrl === VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL,
+        defaultOriginRepositoryUrl: VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL,
+        automaticConfiguration: context.automaticConfiguration,
+        installedVersions: context.installedVersions,
+        garbageCollectionKeepVersionsCount: context.garbageCollectionKeepVersionsCount,
+        job: context.job,
+    };
+}