@promptbook/cli 0.113.0-1 → 0.113.0-11

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

@@ -0,0 +1,81 @@
+import { rm, stat } from 'fs/promises';
+import { resolve } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
+import { readPersistedVpsSelfUpdateJob } from './readPersistedVpsSelfUpdateJob';
+import { resolveManagedPromptbookRepositoryDirectory } from './vpsSelfUpdateConfiguration';
+import { resolveVpsSelfUpdateReleasesDirectory } from './vpsSelfUpdateInstalledVersions';
+
+/**
+ * Deletes one old installed Agents Server version from the releases directory.
+ *
+ * Only non-current version directories inside the releases directory can be deleted,
+ * and never while a self-update job is running (the installer may be using them).
+ *
+ * @param versionName - Release directory name shown on the Update page (e.g. `10dbbe7`).
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function deleteVpsSelfUpdateInstalledVersion(versionName: string): Promise<void> {
+    if (process.platform !== 'linux') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Installed Agents Server versions can be deleted only on the standalone Linux VPS deployment.
+            `),
+        );
+    }
+
+    const normalizedVersionName = versionName?.trim() || '';
+    if (!/^[A-Za-z0-9._-]+$/u.test(normalizedVersionName) || normalizedVersionName.startsWith('.')) {
+        throw new NotAllowed(
+            spaceTrim(`
+                The version name \`${versionName}\` is not a valid installed version.
+
+                **Version names contain only letters, digits, dots, underscores, and dashes and do not start with a dot.**
+            `),
+        );
+    }
+
+    const currentJob = await readPersistedVpsSelfUpdateJob({ isLogTailIncluded: false });
+    if (currentJob.status === 'running' && !currentJob.isStale) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Installed versions cannot be deleted while a standalone VPS self-update is running.
+            `),
+        );
+    }
+
+    const releasesDirectory = await resolveVpsSelfUpdateReleasesDirectory();
+    if (!releasesDirectory) {
+        throw new NotAllowed(
+            spaceTrim(`
+                The releases directory with installed Agents Server versions could not be resolved on this server.
+            `),
+        );
+    }
+
+    const versionDirectory = resolve(releasesDirectory, normalizedVersionName);
+    const currentRepositoryDirectory = await resolveManagedPromptbookRepositoryDirectory();
+    if (currentRepositoryDirectory !== null && versionDirectory === currentRepositoryDirectory) {
+        throw new NotAllowed(
+            spaceTrim(`
+                The version \`${normalizedVersionName}\` is the currently deployed Agents Server version and cannot be deleted.
+            `),
+        );
+    }
+
+    try {
+        const versionDirectoryStats = await stat(versionDirectory);
+        if (!versionDirectoryStats.isDirectory()) {
+            throw new Error('Not a directory');
+        }
+    } catch {
+        throw new NotAllowed(
+            spaceTrim(`
+                The version \`${normalizedVersionName}\` is not installed in the releases directory.
+            `),
+        );
+    }
+
+    await rm(versionDirectory, { recursive: true, force: true });
+}

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/readAgentsServerFooterVersion.ts

@@ -0,0 +1,335 @@
+import { PROMPTBOOK_ENGINE_VERSION } from '../../../../../src/version';
+import {
+    readConfiguredVpsSelfUpdateOriginRepositoryUrl,
+    VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL,
+} from './vpsSelfUpdateOriginRepository';
+import { resolveManagedPromptbookRepositoryDirectory } from './vpsSelfUpdateConfiguration';
+import { abbreviateCommitSha, readCommitMetadataFromRepository, runGitInRepository } from './vpsSelfUpdateRepository';
+
+/**
+ * Git tag pattern used for Promptbook/Agents Server release tags.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const AGENTS_SERVER_VERSION_TAG_PATTERN = /^v?[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/u;
+
+/**
+ * Generated version tag used when the local Git checkout does not expose reachable tags.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const DEFAULT_AGENTS_SERVER_VERSION_TAG = `v${PROMPTBOOK_ENGINE_VERSION}`;
+
+/**
+ * How long the Git-derived footer version summary stays cached.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const AGENTS_SERVER_FOOTER_VERSION_CACHE_TTL_MILLISECONDS = 60 * 1000;
+
+/**
+ * Git tag match patterns accepted by `git describe`.
+ *
+ * @private constant of `vpsSelfUpdate`
+ */
+const GIT_DESCRIBE_VERSION_TAG_MATCH_ARGUMENTS = ['--match', 'v[0-9]*', '--match', '[0-9]*'] as const;
+
+/**
+ * Cached footer version promise shared by concurrent layout renders.
+ *
+ * @private variable of `vpsSelfUpdate`
+ */
+let cachedAgentsServerFooterVersionPromise: Promise<AgentsServerFooterVersion> | null = null;
+
+/**
+ * Expiration timestamp for {@link cachedAgentsServerFooterVersionPromise}.
+ *
+ * @private variable of `vpsSelfUpdate`
+ */
+let cachedAgentsServerFooterVersionExpiresAt = 0;
+
+/**
+ * Lightweight Agents Server version summary consumed by the shared footer.
+ *
+ * @private type of `vpsSelfUpdate`
+ */
+export type AgentsServerFooterVersion = {
+    /**
+     * Release tag shown as the base Agents Server version.
+     */
+    readonly versionTag: string;
+    /**
+     * Display label, optionally including the deployed commit short hash.
+     */
+    readonly label: string;
+    /**
+     * Browser URL of the backing Git repository.
+     */
+    readonly repositoryUrl: string;
+    /**
+     * Browser URL linked from the footer version text.
+     */
+    readonly versionUrl: string;
+    /**
+     * Current deployed commit hash.
+     */
+    readonly currentCommitSha: string | null;
+    /**
+     * Current deployed commit short hash.
+     */
+    readonly currentCommitShortSha: string | null;
+    /**
+     * Commit hash that the release tag points to.
+     */
+    readonly versionCommitSha: string | null;
+    /**
+     * Release commit author timestamp in ISO format.
+     */
+    readonly releasedAt: string | null;
+};
+
+/**
+ * Reads the footer version summary while caching the Git work outside the client footer render path.
+ *
+ * @returns Git-derived Agents Server version information safe to pass into the client footer.
+ *
+ * @private function of `vpsSelfUpdate`
+ */
+export async function readAgentsServerFooterVersion(): Promise<AgentsServerFooterVersion> {
+    const now = Date.now();
+    const cachedAgentsServerFooterVersion = cachedAgentsServerFooterVersionPromise;
+    const isCacheFresh = cachedAgentsServerFooterVersion !== null && cachedAgentsServerFooterVersionExpiresAt > now;
+
+    if (isCacheFresh) {
+        return cachedAgentsServerFooterVersion;
+    }
+
+    cachedAgentsServerFooterVersionPromise = readUncachedAgentsServerFooterVersion();
+    cachedAgentsServerFooterVersionExpiresAt = now + AGENTS_SERVER_FOOTER_VERSION_CACHE_TTL_MILLISECONDS;
+    return cachedAgentsServerFooterVersionPromise;
+}
+
+/**
+ * Formats the compact version label shown in the footer.
+ *
+ * @param options - Release tag and optional deployed commit short hash.
+ * @returns Footer version label.
+ *
+ * @private utility of `vpsSelfUpdate`
+ */
+export function formatAgentsServerFooterVersionLabel(options: {
+    readonly versionTag: string;
+    readonly currentCommitShortSha: string | null;
+}): string {
+    if (!options.currentCommitShortSha) {
+        return options.versionTag;
+    }
+
+    return `${options.versionTag} (${options.currentCommitShortSha})`;
+}
+
+/**
+ * Normalizes a Git repository clone URL to a browser URL.
+ *
+ * @param repositoryUrl - Git clone URL.
+ * @returns Browser URL for the repository.
+ *
+ * @private utility of `vpsSelfUpdate`
+ */
+export function normalizeGitRepositoryWebUrl(repositoryUrl: string): string {
+    const normalizedRepositoryUrl = repositoryUrl
+        .trim()
+        .replace(/^git\+/u, '')
+        .replace(/\.git$/u, '');
+    return normalizedRepositoryUrl || VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL.replace(/\.git$/u, '');
+}
+
+/**
+ * Normalizes a release version into the repository tag format.
+ *
+ * @param value - Raw tag or generated version.
+ * @returns Normalized version tag or `null` when the value is not a release tag.
+ *
+ * @private utility of `vpsSelfUpdate`
+ */
+export function normalizeAgentsServerVersionTag(value: string | null | undefined): string | null {
+    const trimmedValue = value?.trim() || '';
+    if (!AGENTS_SERVER_VERSION_TAG_PATTERN.test(trimmedValue)) {
+        return null;
+    }
+
+    return trimmedValue.startsWith('v') ? trimmedValue : `v${trimmedValue}`;
+}
+
+/**
+ * Resolves the URL linked from the footer version text.
+ *
+ * @param options - Repository URL, tag, current commit and comparison state.
+ * @returns Browser URL for the most specific Git reference.
+ *
+ * @private utility of `vpsSelfUpdate`
+ */
+export function resolveAgentsServerFooterVersionUrl(options: {
+    readonly repositoryUrl: string;
+    readonly versionTag: string;
+    readonly currentCommitSha: string | null;
+    readonly isCurrentCommitNewerThanVersionTag: boolean;
+}): string {
+    if (!options.repositoryUrl.startsWith('https://github.com/')) {
+        return options.repositoryUrl;
+    }
+
+    if (options.isCurrentCommitNewerThanVersionTag && options.currentCommitSha) {
+        return `${options.repositoryUrl}/commit/${options.currentCommitSha}`;
+    }
+
+    return `${options.repositoryUrl}/releases/tag/${encodeURIComponent(options.versionTag)}`;
+}
+
+/**
+ * Reads the footer version summary without using the module-level cache.
+ *
+ * @returns Git-derived Agents Server version information.
+ */
+async function readUncachedAgentsServerFooterVersion(): Promise<AgentsServerFooterVersion> {
+    const repositoryUrl = normalizeGitRepositoryWebUrl(await readFooterVersionOriginRepositoryUrl());
+    const repositoryDirectory = await resolveAgentsServerFooterRepositoryDirectory();
+
+    if (!repositoryDirectory) {
+        return createFallbackAgentsServerFooterVersion(repositoryUrl);
+    }
+
+    const [currentCommit, versionTag] = await Promise.all([
+        readCommitMetadataFromRepository(repositoryDirectory, 'HEAD'),
+        readAgentsServerVersionTagFromRepository(repositoryDirectory),
+    ]);
+    const versionCommit = await readCommitMetadataFromRepository(repositoryDirectory, `${versionTag}^{commit}`);
+    const currentCommitSha = currentCommit?.commitSha ?? readCurrentCommitShaFromEnvironment();
+    const currentCommitShortSha = abbreviateCommitSha(currentCommitSha);
+    const versionCommitSha = versionCommit?.commitSha ?? null;
+    const isCurrentCommitNewerThanVersionTag = Boolean(
+        currentCommitSha && versionCommitSha && currentCommitSha !== versionCommitSha,
+    );
+    const displayedCommitShortSha = isCurrentCommitNewerThanVersionTag ? currentCommitShortSha : null;
+
+    return {
+        versionTag,
+        label: formatAgentsServerFooterVersionLabel({
+            versionTag,
+            currentCommitShortSha: displayedCommitShortSha,
+        }),
+        repositoryUrl,
+        versionUrl: resolveAgentsServerFooterVersionUrl({
+            repositoryUrl,
+            versionTag,
+            currentCommitSha,
+            isCurrentCommitNewerThanVersionTag,
+        }),
+        currentCommitSha,
+        currentCommitShortSha,
+        versionCommitSha,
+        releasedAt: versionCommit?.authoredAt ?? null,
+    };
+}
+
+/**
+ * Reads the configured origin URL without letting optional VPS configuration block footer rendering.
+ *
+ * @returns Configured origin URL or the default Promptbook repository.
+ */
+async function readFooterVersionOriginRepositoryUrl(): Promise<string> {
+    try {
+        return await readConfiguredVpsSelfUpdateOriginRepositoryUrl();
+    } catch {
+        return VPS_SELF_UPDATE_DEFAULT_ORIGIN_REPOSITORY_URL;
+    }
+}
+
+/**
+ * Resolves a local Git checkout suitable for lightweight version metadata reads.
+ *
+ * @returns Repository directory or `null` when Git metadata is unavailable.
+ */
+async function resolveAgentsServerFooterRepositoryDirectory(): Promise<string | null> {
+    const managedRepositoryDirectory = await resolveManagedPromptbookRepositoryDirectory().catch(() => null);
+    const candidateDirectories = [
+        managedRepositoryDirectory,
+        process.env.PTBK_REPOSITORY_DIR?.trim() || null,
+        process.cwd(),
+    ];
+
+    for (const candidateDirectory of candidateDirectories) {
+        if (!candidateDirectory) {
+            continue;
+        }
+
+        const gitRepositoryRoot = await runGitInRepository(candidateDirectory, ['rev-parse', '--show-toplevel']);
+        if (gitRepositoryRoot) {
+            return candidateDirectory;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Reads the nearest reachable release tag for the deployed checkout.
+ *
+ * @param repositoryDirectory - Repository checkout path.
+ * @returns Normalized release tag.
+ */
+async function readAgentsServerVersionTagFromRepository(repositoryDirectory: string): Promise<string> {
+    const describedTag = await runGitInRepository(repositoryDirectory, [
+        'describe',
+        '--tags',
+        '--abbrev=0',
+        ...GIT_DESCRIBE_VERSION_TAG_MATCH_ARGUMENTS,
+        'HEAD',
+    ]);
+
+    return (
+        normalizeAgentsServerVersionTag(describedTag) ??
+        normalizeAgentsServerVersionTag(DEFAULT_AGENTS_SERVER_VERSION_TAG) ??
+        DEFAULT_AGENTS_SERVER_VERSION_TAG
+    );
+}
+
+/**
+ * Reads the deployed commit hash from public deployment metadata when local Git is unavailable.
+ *
+ * @returns Commit hash or `null`.
+ */
+function readCurrentCommitShaFromEnvironment(): string | null {
+    return process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA?.trim() || null;
+}
+
+/**
+ * Creates a resilient fallback when the server cannot inspect a Git checkout.
+ *
+ * @param repositoryUrl - Browser URL of the configured Git repository.
+ * @returns Fallback footer version summary.
+ */
+function createFallbackAgentsServerFooterVersion(repositoryUrl: string): AgentsServerFooterVersion {
+    const currentCommitSha = readCurrentCommitShaFromEnvironment();
+    const versionTag =
+        normalizeAgentsServerVersionTag(DEFAULT_AGENTS_SERVER_VERSION_TAG) ?? DEFAULT_AGENTS_SERVER_VERSION_TAG;
+
+    return {
+        versionTag,
+        label: formatAgentsServerFooterVersionLabel({
+            versionTag,
+            currentCommitShortSha: null,
+        }),
+        repositoryUrl,
+        versionUrl: resolveAgentsServerFooterVersionUrl({
+            repositoryUrl,
+            versionTag,
+            currentCommitSha,
+            isCurrentCommitNewerThanVersionTag: false,
+        }),
+        currentCommitSha,
+        currentCommitShortSha: abbreviateCommitSha(currentCommitSha),
+        versionCommitSha: null,
+        releasedAt: null,
+    };
+}