@promptbook/cli 0.113.0-7 → 0.113.0-9

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

@@ -0,0 +1,286 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import type { VpsSelfUpdateCommitMetadata, VpsSelfUpdatePendingCommit } from './vpsSelfUpdateTypes';
+
+/**
+ * Promisified `execFile` used for isolated git calls.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const EXEC_FILE_ASYNC = promisify(execFile);
+
+/**
+ * Hard ceiling for the pending-commits listing returned in the overview to avoid huge payloads on a long-stale server.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const VPS_SELF_UPDATE_MAX_PENDING_COMMITS = 100;
+
+/**
+ * Number of latest branch commits fetched for the update overview.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const VPS_SELF_UPDATE_OVERVIEW_FETCH_DEPTH = VPS_SELF_UPDATE_MAX_PENDING_COMMITS + 1;
+
+/**
+ * Field separator used between commit fields in the `git log` machine output.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+export const GIT_LOG_FIELD_SEPARATOR = '\x1f';
+
+/**
+ * Executes one git command in the managed repository.
+ *
+ * @param repositoryDirectory - Repository checkout path.
+ * @param gitArguments - Arguments passed to `git`.
+ * @returns Trimmed stdout or `null` when the command fails.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function runGitInRepository(
+    repositoryDirectory: string,
+    gitArguments: ReadonlyArray<string>,
+): Promise<string | null> {
+    try {
+        const { stdout } = await EXEC_FILE_ASYNC('git', ['-C', repositoryDirectory, ...gitArguments], {
+            maxBuffer: 1024 * 1024,
+        });
+        return stdout.trim() || null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Fetches the tracked remote branch into the local object database before building the browser overview.
+ *
+ * @param repositoryDirectory - Repository checkout path.
+ * @param branch - Target branch.
+ * @param originRepositoryUrl - Configured upstream repository URL.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function refreshVpsSelfUpdateRemoteBranch(
+    repositoryDirectory: string,
+    branch: string,
+    originRepositoryUrl: string,
+): Promise<void> {
+    if (!branch) {
+        return;
+    }
+
+    await runGitInRepository(repositoryDirectory, [
+        'fetch',
+        '--no-tags',
+        '--prune',
+        `--depth=${VPS_SELF_UPDATE_OVERVIEW_FETCH_DEPTH}`,
+        originRepositoryUrl,
+        `+refs/heads/${branch}:${createVpsSelfUpdateRemoteBranchReference(branch)}`,
+    ]);
+}
+
+/**
+ * Reads the latest tracked-branch commit from the local remote-tracking ref, falling back to `ls-remote`.
+ *
+ * @param repositoryDirectory - Repository checkout path.
+ * @param branch - Target branch.
+ * @param originRepositoryUrl - Configured upstream repository URL.
+ * @returns Remote branch commit sha or `null`.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readLatestRemoteBranchCommitSha(
+    repositoryDirectory: string,
+    branch: string,
+    originRepositoryUrl: string,
+): Promise<string | null> {
+    if (!branch) {
+        return null;
+    }
+
+    const remoteBranchReference = createVpsSelfUpdateRemoteBranchReference(branch);
+    const localCommitSha = await runGitInRepository(repositoryDirectory, [
+        'rev-parse',
+        '--verify',
+        `${remoteBranchReference}^{commit}`,
+    ]);
+
+    return localCommitSha || readRemoteCommitSha(repositoryDirectory, branch, originRepositoryUrl);
+}
+
+/**
+ * Reads hash, subject and author timestamp for one known commit from the local repository.
+ *
+ * @param repositoryDirectory - Repository checkout path.
+ * @param commitReference - Commit hash or git revision reference to look up.
+ * @returns Commit metadata or `null` when the commit cannot be resolved locally.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readCommitMetadataFromRepository(
+    repositoryDirectory: string,
+    commitReference: string,
+): Promise<VpsSelfUpdateCommitMetadata | null> {
+    const output = await runGitInRepository(repositoryDirectory, [
+        'log',
+        '-1',
+        `--format=%H${GIT_LOG_FIELD_SEPARATOR}%aI${GIT_LOG_FIELD_SEPARATOR}%s`,
+        commitReference,
+    ]);
+    if (!output) {
+        return null;
+    }
+
+    const fields = output.split(GIT_LOG_FIELD_SEPARATOR);
+    const commitSha = fields[0] ?? '';
+    if (!commitSha) {
+        return null;
+    }
+
+    return {
+        commitSha,
+        authoredAt: fields[1] || null,
+        subject: fields.slice(2).join(GIT_LOG_FIELD_SEPARATOR),
+    };
+}
+
+/**
+ * Counts how many commits separate two commits in the local repository.
+ *
+ * Returns `null` when either commit cannot be resolved (typical for a shallow clone that has not been deepened yet).
+ *
+ * @param repositoryDirectory - Repository checkout path.
+ * @param fromCommitSha - Older commit hash.
+ * @param toCommitSha - Newer commit hash.
+ * @returns Commit count or `null`.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function countCommitsBetween(
+    repositoryDirectory: string,
+    fromCommitSha: string,
+    toCommitSha: string,
+): Promise<number | null> {
+    if (fromCommitSha === toCommitSha) {
+        return 0;
+    }
+
+    const output = await runGitInRepository(repositoryDirectory, [
+        'rev-list',
+        '--count',
+        `${fromCommitSha}..${toCommitSha}`,
+    ]);
+    if (output === null) {
+        return null;
+    }
+
+    const parsedCommitCount = Number.parseInt(output, 10);
+    return Number.isFinite(parsedCommitCount) ? parsedCommitCount : null;
+}
+
+/**
+ * Lists commits that separate two commits in the local repository so the admin UI can show subject/hash/date for each one.
+ *
+ * Returns an empty list when either commit cannot be resolved (typical for a shallow clone that has not been deepened yet)
+ * or when both commits are identical.
+ *
+ * @param repositoryDirectory - Repository checkout path.
+ * @param fromCommitSha - Older commit hash (deployed commit).
+ * @param toCommitSha - Newer commit hash (latest remote commit).
+ * @returns Browser-safe pending-commit list (newest first).
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function listCommitsBetween(
+    repositoryDirectory: string,
+    fromCommitSha: string,
+    toCommitSha: string,
+): Promise<ReadonlyArray<VpsSelfUpdatePendingCommit>> {
+    if (fromCommitSha === toCommitSha) {
+        return [];
+    }
+
+    const output = await runGitInRepository(repositoryDirectory, [
+        'log',
+        `--max-count=${VPS_SELF_UPDATE_MAX_PENDING_COMMITS}`,
+        `--format=%H${GIT_LOG_FIELD_SEPARATOR}%aI${GIT_LOG_FIELD_SEPARATOR}%s`,
+        `${fromCommitSha}..${toCommitSha}`,
+    ]);
+    if (!output) {
+        return [];
+    }
+
+    const pendingCommits: Array<VpsSelfUpdatePendingCommit> = [];
+    for (const line of output.split('\n')) {
+        if (!line) {
+            continue;
+        }
+
+        const fields = line.split(GIT_LOG_FIELD_SEPARATOR);
+        const commitSha = fields[0] ?? '';
+        if (!commitSha) {
+            continue;
+        }
+
+        const authoredAt = fields[1] || null;
+        const subject = fields.slice(2).join(GIT_LOG_FIELD_SEPARATOR);
+
+        pendingCommits.push({
+            commitSha,
+            shortCommitSha: commitSha.slice(0, 7),
+            subject,
+            authoredAt,
+        });
+    }
+
+    return pendingCommits;
+}
+
+/**
+ * Abbreviates a git sha for compact display.
+ *
+ * @param sha - Full commit sha.
+ * @returns Short commit sha or `null`.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export function abbreviateCommitSha(sha: string | null): string | null {
+    return sha ? sha.slice(0, 7) : null;
+}
+
+/**
+ * Reads the latest remote branch commit without mutating the local checkout.
+ *
+ * @param repositoryDirectory - Repository checkout path.
+ * @param branch - Target branch.
+ * @param originRepositoryUrl - Configured upstream repository URL.
+ * @returns Remote commit sha or `null`.
+ */
+async function readRemoteCommitSha(
+    repositoryDirectory: string,
+    branch: string,
+    originRepositoryUrl: string,
+): Promise<string | null> {
+    if (!branch) {
+        return null;
+    }
+
+    const output = await runGitInRepository(repositoryDirectory, [
+        'ls-remote',
+        originRepositoryUrl,
+        `refs/heads/${branch}`,
+    ]);
+    return output?.split(/\s+/u)[0] || null;
+}
+
+/**
+ * Creates the local remote-tracking reference used for the update overview fetch.
+ *
+ * @param branch - Target branch.
+ * @returns Local remote-tracking reference.
+ */
+function createVpsSelfUpdateRemoteBranchReference(branch: string): string {
+    return `refs/remotes/origin/${branch}`;
+}

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

@@ -0,0 +1,191 @@
+import { readVpsSelfUpdateAutomaticConfiguration } from './vpsSelfUpdateAutomaticConfiguration';
+import { resolveNextVpsSelfUpdateCronRun } from './vpsSelfUpdateCron';
+import { readVpsSelfUpdateOverview } from './readVpsSelfUpdateOverview';
+
+/**
+ * Global key used to keep one automatic self-update scheduler per Node.js process.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const VPS_SELF_UPDATE_SCHEDULER_GLOBAL_KEY = '__PROMPTBOOK_VPS_SELF_UPDATE_SCHEDULER__';
+
+/**
+ * Maximum safe delay accepted by Node.js timers.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const VPS_SELF_UPDATE_MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/**
+ * Scheduler state stored on `globalThis` to survive module reloads.
+ *
+ * @private type of `vpsSelfUpdateScheduler`
+ */
+type VpsSelfUpdateSchedulerState = {
+    /**
+     * Whether the scheduler has been bootstrapped in this process.
+     */
+    isBootstrapped: boolean;
+    /**
+     * Whether one scheduled check is currently running.
+     */
+    isRunning: boolean;
+    /**
+     * Pending timer, if any.
+     */
+    timeout: NodeJS.Timeout | null;
+};
+
+/**
+ * Global object shape used for process-wide scheduler state.
+ *
+ * @private type of `vpsSelfUpdateScheduler`
+ */
+type VpsSelfUpdateSchedulerGlobal = typeof globalThis & {
+    [VPS_SELF_UPDATE_SCHEDULER_GLOBAL_KEY]?: VpsSelfUpdateSchedulerState;
+};
+
+/**
+ * Starts the automatic VPS self-update scheduler when the current runtime can run it.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export function ensureAutomaticVpsSelfUpdateSchedulerBootstrapped(): void {
+    if (!isAutomaticVpsSelfUpdateSchedulerRuntimeAvailable()) {
+        return;
+    }
+
+    const state = getVpsSelfUpdateSchedulerState();
+    if (state.isBootstrapped) {
+        return;
+    }
+
+    state.isBootstrapped = true;
+    void scheduleNextAutomaticVpsSelfUpdateCheck();
+}
+
+/**
+ * Reschedules the automatic self-update timer after the admin changes `.env` configuration.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export function rescheduleAutomaticVpsSelfUpdateScheduler(): void {
+    if (!isAutomaticVpsSelfUpdateSchedulerRuntimeAvailable()) {
+        return;
+    }
+
+    const state = getVpsSelfUpdateSchedulerState();
+    state.isBootstrapped = true;
+    clearAutomaticVpsSelfUpdateTimer(state);
+    void scheduleNextAutomaticVpsSelfUpdateCheck();
+}
+
+/**
+ * Schedules the next cron-based automatic self-update check.
+ */
+async function scheduleNextAutomaticVpsSelfUpdateCheck(): Promise<void> {
+    const state = getVpsSelfUpdateSchedulerState();
+
+    try {
+        const configuration = await readVpsSelfUpdateAutomaticConfiguration();
+        const nextRunAt = resolveNextVpsSelfUpdateCronRun(configuration.cronExpression);
+        const delayMs = Math.max(1_000, nextRunAt.getTime() - Date.now());
+        const timeoutDelayMs = Math.min(delayMs, VPS_SELF_UPDATE_MAX_TIMER_DELAY_MS);
+
+        clearAutomaticVpsSelfUpdateTimer(state);
+        state.timeout = setTimeout(() => {
+            if (delayMs > VPS_SELF_UPDATE_MAX_TIMER_DELAY_MS) {
+                void scheduleNextAutomaticVpsSelfUpdateCheck();
+                return;
+            }
+
+            void runAutomaticVpsSelfUpdateCheck();
+        }, timeoutDelayMs);
+        state.timeout.unref?.();
+    } catch (error) {
+        console.error('[vps-self-update] failed to schedule automatic self-update check', error);
+    }
+}
+
+/**
+ * Runs one scheduled automatic self-update check.
+ */
+async function runAutomaticVpsSelfUpdateCheck(): Promise<void> {
+    const state = getVpsSelfUpdateSchedulerState();
+    if (state.isRunning) {
+        await scheduleNextAutomaticVpsSelfUpdateCheck();
+        return;
+    }
+
+    state.isRunning = true;
+
+    try {
+        const configuration = await readVpsSelfUpdateAutomaticConfiguration();
+        if (!configuration.isEnabled) {
+            return;
+        }
+
+        const overview = await readVpsSelfUpdateOverview();
+        if (!overview.isAvailable || !overview.isUpdateAvailable || overview.job.status === 'running') {
+            return;
+        }
+
+        const { startVpsSelfUpdate } = await import('./startVpsSelfUpdate');
+        await startVpsSelfUpdate({
+            environmentId: configuration.environment.id,
+            trigger: 'automatic',
+        });
+    } catch (error) {
+        console.error('[vps-self-update] automatic self-update check failed', error);
+    } finally {
+        state.isRunning = false;
+        await scheduleNextAutomaticVpsSelfUpdateCheck();
+    }
+}
+
+/**
+ * Clears one pending scheduler timer.
+ *
+ * @param state - Process-wide scheduler state.
+ */
+function clearAutomaticVpsSelfUpdateTimer(state: VpsSelfUpdateSchedulerState): void {
+    if (!state.timeout) {
+        return;
+    }
+
+    clearTimeout(state.timeout);
+    state.timeout = null;
+}
+
+/**
+ * Returns process-wide scheduler state.
+ *
+ * @returns Mutable scheduler state.
+ */
+function getVpsSelfUpdateSchedulerState(): VpsSelfUpdateSchedulerState {
+    const schedulerGlobal = globalThis as VpsSelfUpdateSchedulerGlobal;
+    schedulerGlobal[VPS_SELF_UPDATE_SCHEDULER_GLOBAL_KEY] ??= {
+        isBootstrapped: false,
+        isRunning: false,
+        timeout: null,
+    };
+
+    return schedulerGlobal[VPS_SELF_UPDATE_SCHEDULER_GLOBAL_KEY]!;
+}
+
+/**
+ * Returns whether the current process should host the automatic self-update scheduler.
+ *
+ * @returns `true` when running in a Linux Node.js server process outside tests and builds.
+ */
+function isAutomaticVpsSelfUpdateSchedulerRuntimeAvailable(): boolean {
+    if (process.platform !== 'linux') {
+        return false;
+    }
+
+    if (process.env.NODE_ENV === 'test' || process.env.JEST_WORKER_ID !== undefined) {
+        return false;
+    }
+
+    return process.env.NEXT_PHASE !== 'phase-production-build';
+}

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

@@ -0,0 +1,197 @@
+import { mkdir, open, readFile, stat, writeFile } from 'fs/promises';
+import { dirname, resolve } from 'path';
+import { resolveVpsEnvironmentFilePath } from '../vpsConfiguration';
+
+/**
+ * Resolves the filesystem path of the persisted self-update log file.
+ *
+ * @returns Absolute log-file path.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export function resolveVpsSelfUpdateLogFilePath(): string {
+    return resolve(resolveVpsSelfUpdateStateDirectory(), 'self-update.log');
+}
+
+/**
+ * Resolves the filesystem path of the persisted self-update database migration summary file.
+ *
+ * @returns Absolute migration-summary file path.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export function resolveVpsSelfUpdateDatabaseMigrationSummaryFilePath(): string {
+    return resolve(resolveVpsSelfUpdateStateDirectory(), 'self-update-database-migrations.json');
+}
+
+/**
+ * Resolves the filesystem path of the persisted self-update task history file.
+ *
+ * @returns Absolute task-history file path.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export function resolveVpsSelfUpdateTaskHistoryFilePath(): string {
+    return resolve(resolveVpsSelfUpdateStateDirectory(), 'self-update-task-history.json');
+}
+
+/**
+ * Resolves the filesystem path of the persisted self-update status file.
+ *
+ * @returns Absolute status-file path.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export function resolveVpsSelfUpdateStatusFilePath(): string {
+    return resolve(resolveVpsSelfUpdateStateDirectory(), 'self-update.status');
+}
+
+/**
+ * Encodes one free-form status field into base64 for the shell-owned status file.
+ *
+ * @param value - Raw string value.
+ * @returns Base64-encoded value.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export function encodeStatusField(value: string): string {
+    return Buffer.from(value, 'utf-8').toString('base64');
+}
+
+/**
+ * Reads the full persisted standalone VPS self-update log so the super admin can copy/download it for debugging.
+ *
+ * @returns Log file content or `null` when the file does not exist yet.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readVpsSelfUpdateLogFileContent(): Promise<string | null> {
+    const logFilePath = resolveVpsSelfUpdateLogFilePath();
+    try {
+        return await readFile(logFilePath, 'utf-8');
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+
+/**
+ * Reads the persisted shell-owned status file.
+ *
+ * @returns Parsed key/value entries.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readVpsSelfUpdateStatusFile(): Promise<Map<string, string>> {
+    const statusFilePath = resolveVpsSelfUpdateStatusFilePath();
+    try {
+        const rawContent = await readFile(statusFilePath, 'utf-8');
+        return new Map(
+            rawContent
+                .split(/\r?\n/u)
+                .map((line) => line.trim())
+                .filter((line) => line !== '' && !line.startsWith('#'))
+                .map((line) => {
+                    const separatorIndex = line.indexOf('=');
+                    if (separatorIndex === -1) {
+                        return [line, ''] as const;
+                    }
+
+                    return [line.slice(0, separatorIndex), line.slice(separatorIndex + 1)] as const;
+                }),
+        );
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return new Map();
+        }
+        throw error;
+    }
+}
+
+/**
+ * Writes the minimal initial status file before the detached installer takes over.
+ *
+ * @param entries - Flat status-file fields.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function writeVpsSelfUpdateStatusFile(entries: Readonly<Record<string, string>>): Promise<void> {
+    const statusFilePath = resolveVpsSelfUpdateStatusFilePath();
+    await mkdir(dirname(statusFilePath), { recursive: true });
+    await writeFile(
+        statusFilePath,
+        `${Object.entries(entries)
+            .map(([key, value]) => `${key}=${value}`)
+            .join('\n')}\n`,
+        'utf-8',
+    );
+}
+
+/**
+ * Decodes one optional base64-encoded status field.
+ *
+ * @param value - Base64 string or `undefined`.
+ * @returns Decoded UTF-8 text or `null`.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export function decodeVpsSelfUpdateStatusField(value: string | undefined): string | null {
+    if (!value) {
+        return null;
+    }
+
+    try {
+        return Buffer.from(value, 'base64').toString('utf-8') || null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Reads the trailing chunk of a text log file for the browser UI.
+ *
+ * @param filePath - File to tail.
+ * @param byteLimit - Maximum bytes to read from the end of the file.
+ * @returns UTF-8 tail text or `null` when missing.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readLastVpsSelfUpdateTextFileChunk(
+    filePath: string | null,
+    byteLimit = 32768,
+): Promise<string | null> {
+    if (!filePath) {
+        return null;
+    }
+
+    try {
+        const fileHandle = await open(filePath, 'r');
+        try {
+            const fileStats = await stat(filePath);
+            const readLength = Math.min(fileStats.size, byteLimit);
+            const offset = Math.max(0, fileStats.size - readLength);
+            const buffer = Buffer.alloc(readLength);
+            const { bytesRead } = await fileHandle.read(buffer, 0, readLength, offset);
+            const text = buffer.subarray(0, bytesRead).toString('utf-8');
+            return offset > 0 ? text.replace(/^[^\n]*\n/u, '') : text;
+        } finally {
+            await fileHandle.close();
+        }
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+
+/**
+ * Resolves the state-directory path used for persistent update logs and status files.
+ *
+ * @returns Absolute directory path.
+ */
+function resolveVpsSelfUpdateStateDirectory(): string {
+    return resolve(dirname(resolveVpsEnvironmentFilePath()), '.promptbook', 'self-update');
+}