@promptbook/cli 0.113.0-1 → 0.113.0-10

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

@@ -0,0 +1,42 @@
+import { VPS_SELF_UPDATE_RESTART_SUCCESS_STEP, VPS_SELF_UPDATE_STALE_ERROR_MESSAGE } from './vpsSelfUpdateJobConstants';
+import type { VpsSelfUpdateJobOverviewContext, VpsSelfUpdateJobSnapshot } from './vpsSelfUpdateTypes';
+
+/**
+ * Converts the persisted shell status into the status that should be shown in the admin overview.
+ *
+ * A successful self-update may restart the old Agents Server process before the browser sees the final
+ * `STATUS=succeeded` write. In that case the stale PID alone is not enough to call the update failed:
+ * if the running server is already on the recorded target branch and target commit, the update succeeded.
+ *
+ * @param job - Persisted self-update job snapshot.
+ * @param context - Current repository state observed by the running server.
+ * @returns Job snapshot resolved for browser display.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export function resolveVpsSelfUpdateJobForOverview(
+    job: VpsSelfUpdateJobSnapshot,
+    context: VpsSelfUpdateJobOverviewContext,
+): VpsSelfUpdateJobSnapshot {
+    const isRestartedSuccessfulUpdate =
+        job.status === 'failed' &&
+        job.isStale &&
+        (!job.errorMessage || job.errorMessage === VPS_SELF_UPDATE_STALE_ERROR_MESSAGE) &&
+        job.targetBranch === context.currentEnvironment.branch &&
+        job.targetCommitSha !== null &&
+        context.currentCommitSha !== null &&
+        job.targetCommitSha === context.currentCommitSha;
+
+    if (!isRestartedSuccessfulUpdate) {
+        return job;
+    }
+
+    return {
+        ...job,
+        status: 'succeeded',
+        currentStep: VPS_SELF_UPDATE_RESTART_SUCCESS_STEP,
+        currentCommitSha: context.currentCommitSha,
+        errorMessage: null,
+        isStale: false,
+    };
+}

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

@@ -0,0 +1,201 @@
+import { spawn } from 'child_process';
+import { mkdir, open, rm } from 'fs/promises';
+import { dirname } from 'path';
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
+import { spaceTrim } from 'spacetrim';
+import { createVpsInstallerCommandEnvironment, resolveVpsInstallerScriptPath } from '../vpsConfiguration';
+import { resolveVpsSelfUpdateEnvironment } from './vpsSelfUpdateEnvironment';
+import {
+    normalizeVpsSelfUpdateOriginRepositoryUrl,
+    persistVpsSelfUpdateOriginRepositoryUrl,
+    readConfiguredVpsSelfUpdateOriginRepositoryUrl,
+} from './vpsSelfUpdateOriginRepository';
+import { preserveVpsSelfUpdateJobInTaskHistory } from './vpsSelfUpdateJobHistory';
+import { readPersistedVpsSelfUpdateJob } from './readPersistedVpsSelfUpdateJob';
+import { readVpsSelfUpdateOverview } from './readVpsSelfUpdateOverview';
+import {
+    encodeStatusField,
+    resolveVpsSelfUpdateDatabaseMigrationSummaryFilePath,
+    resolveVpsSelfUpdateLogFilePath,
+    resolveVpsSelfUpdateStatusFilePath,
+    writeVpsSelfUpdateStatusFile,
+} from './vpsSelfUpdateStateFiles';
+import type { VpsSelfUpdateJobTrigger, VpsSelfUpdateOverview, VpsSelfUpdateStartRequest } from './vpsSelfUpdateTypes';
+
+/**
+ * Starts one detached VPS self-update run for the selected environment.
+ *
+ * The actual update is executed by `other/vps/install.sh self-update`, while this
+ * helper writes the initial persisted state and detaches the background process so
+ * the triggering HTTP request can finish before pm2 restarts the server.
+ *
+ * @param request - Update request payload.
+ * @returns Fresh overview including the running background job.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function startVpsSelfUpdate(request: VpsSelfUpdateStartRequest): Promise<VpsSelfUpdateOverview> {
+    if (process.platform !== 'linux') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Self-update is available only on the standalone Linux VPS deployment.
+            `),
+        );
+    }
+
+    const targetEnvironment = resolveVpsSelfUpdateEnvironment(request.environmentId);
+    const trigger = normalizeVpsSelfUpdateJobTrigger(request.trigger);
+    const isCustomEnvironment = targetEnvironment.isCustom;
+    const targetRef = isCustomEnvironment
+        ? normalizeVpsSelfUpdateArbitraryRef(request.customRef)
+        : targetEnvironment.branch;
+
+    if (isCustomEnvironment && !targetRef) {
+        throw new NotAllowed(
+            spaceTrim(`
+                A custom self-update requires a non-empty target ref (commit hash, tag, or branch).
+            `),
+        );
+    }
+
+    const requestedOriginUrl = normalizeVpsSelfUpdateOriginRepositoryUrl(request.originRepositoryUrl);
+    if (requestedOriginUrl !== null) {
+        await persistVpsSelfUpdateOriginRepositoryUrl(requestedOriginUrl);
+    }
+
+    const originRepositoryUrl = requestedOriginUrl || (await readConfiguredVpsSelfUpdateOriginRepositoryUrl());
+
+    const currentJob = await readPersistedVpsSelfUpdateJob({ isLogTailIncluded: false });
+    if (currentJob.status === 'running' && !currentJob.isStale) {
+        throw new NotAllowed(
+            spaceTrim(`
+                A standalone VPS self-update is already running.
+            `),
+        );
+    }
+
+    const scriptPath = await resolveVpsInstallerScriptPath();
+    if (!scriptPath) {
+        throw new NotAllowed('The shared VPS installer script could not be found on this server.');
+    }
+    await preserveVpsSelfUpdateJobInTaskHistory(currentJob);
+
+    const statusFilePath = resolveVpsSelfUpdateStatusFilePath();
+    const logFilePath = resolveVpsSelfUpdateLogFilePath();
+    const databaseMigrationSummaryFilePath = resolveVpsSelfUpdateDatabaseMigrationSummaryFilePath();
+    const startedAt = new Date().toISOString();
+    const jobId = createVpsSelfUpdateJobId(startedAt);
+    await mkdir(dirname(logFilePath), { recursive: true });
+    await rm(databaseMigrationSummaryFilePath, { force: true });
+    const logHandle = await open(logFilePath, 'a');
+
+    try {
+        const installerArguments = isCustomEnvironment
+            ? [scriptPath, 'self-update', '--ref', targetRef]
+            : [scriptPath, 'self-update', '--branch', targetRef];
+
+        const child = spawn('bash', installerArguments, {
+            detached: true,
+            stdio: ['ignore', logHandle.fd, logHandle.fd],
+            env: {
+                ...createVpsInstallerCommandEnvironment(),
+                PTBK_SELF_UPDATE_STATUS_FILE: statusFilePath,
+                PTBK_SELF_UPDATE_LOG_FILE: logFilePath,
+                PTBK_SELF_UPDATE_JOB_ID: jobId,
+                PTBK_SELF_UPDATE_TRIGGER: trigger,
+                PTBK_TARGET_REPOSITORY_REF: targetRef,
+                PTBK_DATABASE_MIGRATION_SUMMARY_FILE: databaseMigrationSummaryFilePath,
+                PROMPTBOOK_REPOSITORY_URL: originRepositoryUrl,
+            },
+        });
+
+        await writeVpsSelfUpdateStatusFile({
+            JOB_ID: jobId,
+            STATUS: 'running',
+            TRIGGER: trigger,
+            PID: String(child.pid ?? ''),
+            TARGET_REF: targetRef,
+            CURRENT_STEP_B64: encodeStatusField(createQueuedVpsSelfUpdateStep(trigger)),
+            ERROR_MESSAGE_B64: '',
+            STARTED_AT: startedAt,
+            FINISHED_AT: '',
+            CURRENT_COMMIT: '',
+            TARGET_COMMIT: '',
+            LOG_FILE: logFilePath,
+            DATABASE_MIGRATION_STATUS: 'pending',
+            DATABASE_MIGRATION_SUMMARY_FILE: databaseMigrationSummaryFilePath,
+            DATABASE_MIGRATION_SUMMARY_B64: '',
+            DATABASE_MIGRATION_ERROR_MESSAGE_B64: '',
+        });
+
+        child.unref();
+    } finally {
+        await logHandle.close();
+    }
+
+    return readVpsSelfUpdateOverview();
+}
+
+/**
+ * Creates a stable identifier for one self-update run.
+ *
+ * @param startedAt - ISO timestamp of the self-update start.
+ * @returns Self-update job id.
+ */
+function createVpsSelfUpdateJobId(startedAt: string): string {
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+
+    const startedAtFingerprint = startedAt.replace(/[^0-9]/gu, '');
+    const randomFingerprint = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER).toString(36);
+
+    return `self-update-${startedAtFingerprint}-${process.pid}-${randomFingerprint}`;
+}
+
+/**
+ * Normalizes one self-update trigger value.
+ *
+ * @param trigger - Optional trigger from the caller.
+ * @returns Supported trigger value.
+ */
+function normalizeVpsSelfUpdateJobTrigger(trigger: VpsSelfUpdateJobTrigger | undefined): VpsSelfUpdateJobTrigger {
+    return trigger === 'automatic' ? 'automatic' : 'manual';
+}
+
+/**
+ * Builds the initial queued status step for the selected trigger.
+ *
+ * @param trigger - Source that started the update.
+ * @returns Human-readable initial status.
+ */
+function createQueuedVpsSelfUpdateStep(trigger: VpsSelfUpdateJobTrigger): string {
+    return trigger === 'automatic'
+        ? 'Queued automatic standalone VPS self-update.'
+        : 'Queued standalone VPS self-update.';
+}
+
+/**
+ * Normalizes one free-form arbitrary git ref entered by the super admin.
+ *
+ * @param value - Raw user-provided ref.
+ * @returns Trimmed ref or empty string when invalid.
+ */
+function normalizeVpsSelfUpdateArbitraryRef(value: string | null | undefined): string {
+    const trimmedValue = value?.trim() || '';
+    if (!trimmedValue) {
+        return '';
+    }
+
+    if (!/^[A-Za-z0-9._/-]+$/u.test(trimmedValue)) {
+        throw new NotAllowed(
+            spaceTrim(`
+                The provided git ref \`${trimmedValue}\` contains unsupported characters.
+
+                **Only letters, digits, dots, underscores, slashes, and dashes are allowed.**
+            `),
+        );
+    }
+
+    return trimmedValue;
+}

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

@@ -0,0 +1,152 @@
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
+import { spaceTrim } from 'spacetrim';
+import { updateVpsEnvironmentVariables } from '../vpsConfiguration';
+import { DEFAULT_VPS_SELF_UPDATE_CRON_EXPRESSION, normalizeVpsSelfUpdateCronExpression } from './vpsSelfUpdateCron';
+import {
+    resolveVpsSelfUpdateEnvironment,
+    VPS_SELF_UPDATE_ENVIRONMENTS,
+    type VpsSelfUpdateEnvironmentOption,
+} from './vpsSelfUpdateEnvironment';
+import type { VpsSelfUpdateAutomaticConfiguration } from './vpsSelfUpdateTypes';
+import { readVpsSelfUpdateConfiguredEnvironmentValue } from './vpsSelfUpdateConfiguration';
+
+/**
+ * `.env` variable that toggles automatic standalone VPS self-updates.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+export const VPS_SELF_UPDATE_AUTOMATIC_ENABLED_ENV_NAME = 'PTBK_AUTO_SELF_UPDATE_ENABLED';
+
+/**
+ * `.env` variable that stores the branch tracked by standalone VPS self-updates.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+export const VPS_SELF_UPDATE_BRANCH_ENV_NAME = 'PROMPTBOOK_REPOSITORY_REF';
+
+/**
+ * `.env` variable that stores the automatic self-update cron expression.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+export const VPS_SELF_UPDATE_AUTOMATIC_CRON_ENV_NAME = 'PTBK_AUTO_SELF_UPDATE_CRON';
+
+/**
+ * Payload accepted when saving the automatic self-update configuration.
+ *
+ * @private type of `vpsSelfUpdate`
+ */
+export type VpsSelfUpdateAutomaticConfigurationUpdate = {
+    /**
+     * Whether scheduled branch updates are enabled.
+     */
+    readonly isEnabled: boolean;
+    /**
+     * Environment id or branch to track.
+     */
+    readonly environmentId: string;
+    /**
+     * Cron expression controlling how often the scheduler checks the branch.
+     */
+    readonly cronExpression: string;
+};
+
+/**
+ * Reads automatic self-update configuration from the standalone VPS `.env` file.
+ *
+ * @returns Browser-safe automatic self-update configuration.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readVpsSelfUpdateAutomaticConfiguration(): Promise<VpsSelfUpdateAutomaticConfiguration> {
+    const [rawEnabled, rawBranch, rawCronExpression] = await Promise.all([
+        readVpsSelfUpdateConfiguredEnvironmentValue(VPS_SELF_UPDATE_AUTOMATIC_ENABLED_ENV_NAME),
+        readVpsSelfUpdateConfiguredEnvironmentValue(VPS_SELF_UPDATE_BRANCH_ENV_NAME),
+        readVpsSelfUpdateConfiguredEnvironmentValue(VPS_SELF_UPDATE_AUTOMATIC_CRON_ENV_NAME),
+    ]);
+
+    return {
+        isEnabled: isVpsSelfUpdateAutomaticEnabled(rawEnabled),
+        environment: resolveVpsSelfUpdateEnvironment(rawBranch),
+        cronExpression: normalizeStoredVpsSelfUpdateCronExpression(rawCronExpression),
+    };
+}
+
+/**
+ * Saves automatic self-update configuration through the shared VPS `.env` writer.
+ *
+ * @param update - Raw configuration payload from `/admin/update`.
+ * @returns Normalized automatic self-update configuration.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function updateVpsSelfUpdateAutomaticConfiguration(
+    update: VpsSelfUpdateAutomaticConfigurationUpdate,
+): Promise<VpsSelfUpdateAutomaticConfiguration> {
+    const environment = resolveStrictVpsSelfUpdateEnvironment(update.environmentId);
+    const cronExpression = normalizeVpsSelfUpdateCronExpression(update.cronExpression);
+
+    await updateVpsEnvironmentVariables({
+        [VPS_SELF_UPDATE_AUTOMATIC_ENABLED_ENV_NAME]: update.isEnabled ? 'true' : 'false',
+        [VPS_SELF_UPDATE_BRANCH_ENV_NAME]: environment.branch,
+        [VPS_SELF_UPDATE_AUTOMATIC_CRON_ENV_NAME]: cronExpression,
+    });
+
+    return {
+        isEnabled: update.isEnabled,
+        environment,
+        cronExpression,
+    };
+}
+
+/**
+ * Parses the automatic self-update boolean environment value.
+ *
+ * @param value - Raw `.env` value.
+ * @returns `true` when automatic self-updates are explicitly enabled.
+ */
+function isVpsSelfUpdateAutomaticEnabled(value: string | null): boolean {
+    const normalizedValue = value?.trim().toLowerCase() || '';
+    return (
+        normalizedValue === '1' || normalizedValue === 'true' || normalizedValue === 'yes' || normalizedValue === 'on'
+    );
+}
+
+/**
+ * Normalizes a stored cron expression, falling back to the default if a hand-edited value is invalid.
+ *
+ * @param value - Stored `.env` cron expression.
+ * @returns Valid cron expression for scheduler and browser use.
+ */
+function normalizeStoredVpsSelfUpdateCronExpression(value: string | null): string {
+    try {
+        return normalizeVpsSelfUpdateCronExpression(value || DEFAULT_VPS_SELF_UPDATE_CRON_EXPRESSION);
+    } catch {
+        return DEFAULT_VPS_SELF_UPDATE_CRON_EXPRESSION;
+    }
+}
+
+/**
+ * Resolves and validates one branch environment selected by the admin.
+ *
+ * @param value - Environment id or branch.
+ * @returns Supported non-custom self-update environment.
+ */
+function resolveStrictVpsSelfUpdateEnvironment(value: string): VpsSelfUpdateEnvironmentOption {
+    const normalizedValue = value.trim().toLowerCase();
+    const environment = VPS_SELF_UPDATE_ENVIRONMENTS.find(
+        (option) => !option.isCustom && (option.id === normalizedValue || option.branch === normalizedValue),
+    );
+
+    if (!environment) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Automatic self-update branch \`${value}\` is not supported.
+
+                **Use one of:** \`main\`, \`preview\`, \`production\`, or \`lts\`.
+            `),
+        );
+    }
+
+    return environment;
+}

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

@@ -0,0 +1,81 @@
+import { constants as filesystemConstants } from 'fs';
+import { access, readFile } from 'fs/promises';
+import { dirname, resolve } from 'path';
+import { resolveVpsEnvironmentFilePath } from '../vpsConfiguration';
+import { resolveVpsSelfUpdateEnvironment, type VpsSelfUpdateEnvironmentOption } from './vpsSelfUpdateEnvironment';
+
+/**
+ * Reads the currently configured standalone VPS self-update environment from `.env`.
+ *
+ * @returns Canonical environment metadata.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readCurrentVpsSelfUpdateEnvironment(): Promise<VpsSelfUpdateEnvironmentOption> {
+    const configuredBranch = await readVpsSelfUpdateConfiguredEnvironmentValue('PROMPTBOOK_REPOSITORY_REF');
+    return resolveVpsSelfUpdateEnvironment(configuredBranch);
+}
+
+/**
+ * Reads one configured `.env` value from the standalone VPS installation.
+ *
+ * @param key - Environment variable name.
+ * @returns Stored value or `null`.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readVpsSelfUpdateConfiguredEnvironmentValue(key: string): Promise<string | null> {
+    try {
+        const environmentFileContent = await readFile(resolveVpsEnvironmentFilePath(), 'utf-8');
+
+        for (const line of environmentFileContent.split(/\r?\n/u)) {
+            const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/u);
+            if (!match || match[1] !== key) {
+                continue;
+            }
+
+            const rawValue = match[2]?.trim() || '';
+            if (
+                (rawValue.startsWith('"') && rawValue.endsWith('"')) ||
+                (rawValue.startsWith("'") && rawValue.endsWith("'"))
+            ) {
+                return rawValue.slice(1, -1);
+            }
+
+            return rawValue;
+        }
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return process.env[key]?.trim() || null;
+        }
+        throw error;
+    }
+
+    return process.env[key]?.trim() || null;
+}
+
+/**
+ * Resolves the managed Promptbook repository directory.
+ *
+ * @returns Absolute path or `null` when it cannot be determined.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function resolveManagedPromptbookRepositoryDirectory(): Promise<string | null> {
+    const configuredDirectory =
+        (await readVpsSelfUpdateConfiguredEnvironmentValue('PTBK_REPOSITORY_DIR')) ||
+        process.env.PTBK_REPOSITORY_DIR?.trim() ||
+        '';
+
+    if (configuredDirectory) {
+        return resolve(configuredDirectory);
+    }
+
+    const fallbackDirectory = resolve(dirname(resolveVpsEnvironmentFilePath()), 'repository');
+    try {
+        await access(fallbackDirectory, filesystemConstants.R_OK);
+        return fallbackDirectory;
+    } catch {
+        return null;
+    }
+}