@promptbook/cli 0.113.0-0 → 0.113.0-2

package/apps/agents-server/src/utils/getAdminChatTasksResponse/mapVpsSelfUpdateJobToAdminChatTask.ts

@@ -0,0 +1,84 @@
+import type { AdminChatTaskRecord } from '../chatTasksAdmin';
+import type { UserChatJobStatus } from '../userChat/UserChatJobRecord';
+import type { VpsSelfUpdateJobSnapshot } from '../vpsSelfUpdate';
+
+/**
+ * Stable synthetic task id used for the singleton standalone VPS self-update task row.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID = 'vps-self-update';
+
+/**
+ * Synthetic queue name used for the standalone VPS self-update task row.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_QUEUE_NAME = 'vps-self-update';
+
+/**
+ * Maps a persisted VPS self-update job snapshot to the admin task manager row shape.
+ *
+ * @param job - Latest persisted self-update job snapshot.
+ * @returns Task manager row or `null` when no self-update has ever been triggered on this server.
+ */
+export function mapVpsSelfUpdateJobToAdminChatTask(job: VpsSelfUpdateJobSnapshot): AdminChatTaskRecord | null {
+    const status = toAdminChatTaskStatus(job);
+    if (!status) {
+        return null;
+    }
+
+    const isTerminalStatus = status === 'COMPLETED' || status === 'FAILED';
+    const startedAt = job.startedAt;
+    const finishedAt = isTerminalStatus ? job.finishedAt || startedAt : null;
+    const updatedAt = finishedAt || startedAt || new Date().toISOString();
+    const errorSummary = job.errorMessage || null;
+    const currentStepDetails = job.currentStep || null;
+
+    return {
+        id: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
+        kind: 'VPS_SELF_UPDATE',
+        status,
+        createdAt: startedAt || updatedAt,
+        queuedAt: startedAt || updatedAt,
+        startedAt,
+        updatedAt,
+        finishedAt,
+        cancelRequestedAt: null,
+        pausedAt: null,
+        lastHeartbeatAt: null,
+        leaseExpiresAt: null,
+        recurrenceIntervalMs: null,
+        priority: null,
+        attemptCount: 1,
+        retryCount: 0,
+        lastErrorSummary: errorSummary,
+        lastErrorDetails: currentStepDetails,
+        userId: 0,
+        username: null,
+        agentPermanentId: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
+        agentName: job.targetEnvironment.label,
+        chatId: job.targetBranch || job.targetEnvironment.branch || VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
+        workerId: job.pid !== null ? String(job.pid) : null,
+        queueName: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_QUEUE_NAME,
+    };
+}
+
+/**
+ * Maps the shell-owned self-update status to the durable chat-task status enum used by the admin task manager.
+ *
+ * @param job - Persisted self-update job snapshot.
+ * @returns Equivalent durable chat-job status, or `null` when the job is idle (no run has been triggered yet).
+ */
+function toAdminChatTaskStatus(job: VpsSelfUpdateJobSnapshot): UserChatJobStatus | null {
+    switch (job.status) {
+        case 'running':
+            return 'RUNNING';
+        case 'succeeded':
+            return 'COMPLETED';
+        case 'failed':
+            return 'FAILED';
+        case 'idle':
+            return null;
+    }
+}

package/apps/agents-server/src/utils/getAdminChatTasksResponse.ts

@@ -1,8 +1,18 @@
 import { ensureUserChatTimeoutWorkerBootstrapped } from '@/src/utils/userChatTimeout/ensureUserChatTimeoutWorkerBootstrapped';
-import type { AdminChatTaskListResponse } from './chatTasksAdmin';
+import type { AdminChatTaskCounters, AdminChatTaskListResponse, AdminChatTaskRecord } from './chatTasksAdmin';
 import { getAdminChatTasks } from './getAdminChatTasksResponse/getAdminChatTasks';
-import { parseAdminChatTaskQuery } from './getAdminChatTasksResponse/parseAdminChatTaskQuery';
+import { mapVpsSelfUpdateJobToAdminChatTask } from './getAdminChatTasksResponse/mapVpsSelfUpdateJobToAdminChatTask';
+import { parseAdminChatTaskQuery, type ParsedAdminChatTaskQuery } from './getAdminChatTasksResponse/parseAdminChatTaskQuery';
 import { throttledAdminRecovery } from './getAdminChatTasksResponse/throttledAdminRecovery';
+import { listPagePreviewBrowserAdminTasks } from './pagePreviewBrowserSessions';
+import { readVpsSelfUpdateJobSnapshot } from './vpsSelfUpdate';
+
+/**
+ * Milliseconds in one hour.
+ *
+ * @private internal constant of `getAdminChatTasksResponse`
+ */
+const HOUR_IN_MILLISECONDS = 60 * 60 * 1000;
 
 /**
  * Successful task-manager response envelope.
@@ -53,13 +63,27 @@ export async function getAdminChatTasksResponse(
     await throttledAdminRecovery();
 
     const adminChatTasks = await getAdminChatTasks(parsedQuery);
+    const vpsSelfUpdateTask = await loadVpsSelfUpdateAdminChatTask();
+    const pagePreviewBrowserTasks = listPagePreviewBrowserAdminTasks();
+    const injectableTasks = [vpsSelfUpdateTask, ...pagePreviewBrowserTasks].filter(
+        (task): task is AdminChatTaskRecord => task !== null,
+    );
+    const injectedTasks = collectAdminChatTasksToInject(injectableTasks, parsedQuery);
+    const { items, total } = mergeInjectedAdminChatTasks({
+        databaseItems: adminChatTasks.items,
+        databaseTotal: adminChatTasks.total,
+        injectedTasks,
+        page: parsedQuery.page,
+        pageSize: parsedQuery.pageSize,
+    });
+    const counters = mergeInjectedAdminChatTaskCounters(adminChatTasks.counters, injectableTasks);
 
     return {
         status: 200,
         response: {
-            items: adminChatTasks.items,
-            counters: adminChatTasks.counters,
-            total: adminChatTasks.total,
+            items,
+            counters,
+            total,
             page: parsedQuery.page,
             pageSize: parsedQuery.pageSize,
             view: parsedQuery.view,
@@ -69,3 +93,195 @@ export async function getAdminChatTasksResponse(
         },
     };
 }
+
+/**
+ * Loads the currently persisted standalone VPS self-update task, if any.
+ *
+ * The read is defensive so a corrupt status file cannot block the admin task manager from rendering.
+ *
+ * @returns Injectable task record or `null` when no self-update has ever been triggered on this server.
+ */
+async function loadVpsSelfUpdateAdminChatTask(): Promise<AdminChatTaskRecord | null> {
+    try {
+        const jobSnapshot = await readVpsSelfUpdateJobSnapshot();
+        return mapVpsSelfUpdateJobToAdminChatTask(jobSnapshot);
+    } catch (error) {
+        console.error('[admin-chat-task] failed to load VPS self-update task snapshot', error);
+        return null;
+    }
+}
+
+/**
+ * Filters out injected tasks that do not belong to the requested admin task-manager view or search.
+ *
+ * @param injectableTasks - Synthetic task rows collected from process-local state.
+ * @param query - Parsed admin task-manager query.
+ * @returns Tasks to inject on top of the database-backed items.
+ */
+function collectAdminChatTasksToInject(
+    injectableTasks: ReadonlyArray<AdminChatTaskRecord>,
+    query: ParsedAdminChatTaskQuery,
+): ReadonlyArray<AdminChatTaskRecord> {
+    const nowTimestamp = Date.now();
+    return injectableTasks.filter(
+        (task) => matchesAdminChatTaskView(task, query, nowTimestamp) && matchesAdminChatTaskSearch(task, query.search),
+    );
+}
+
+/**
+ * Prepends the injected task rows to the paginated database items so the self-update stays visible on page 1.
+ *
+ * @param options - Merge inputs.
+ * @returns Merged items for the current page and the updated total row count.
+ */
+function mergeInjectedAdminChatTasks(options: {
+    readonly databaseItems: ReadonlyArray<AdminChatTaskRecord>;
+    readonly databaseTotal: number;
+    readonly injectedTasks: ReadonlyArray<AdminChatTaskRecord>;
+    readonly page: number;
+    readonly pageSize: number;
+}): { items: Array<AdminChatTaskRecord>; total: number } {
+    const total = options.databaseTotal + options.injectedTasks.length;
+
+    if (options.injectedTasks.length === 0) {
+        return { items: [...options.databaseItems], total };
+    }
+
+    if (options.page !== 1) {
+        return { items: [...options.databaseItems], total };
+    }
+
+    const items = [...options.injectedTasks, ...options.databaseItems].slice(0, options.pageSize);
+    return { items, total };
+}
+
+/**
+ * Adds injected tasks to the summary counters so the header metrics stay accurate.
+ *
+ * @param databaseCounters - Counters computed from durable database rows.
+ * @param injectedTasks - Synthetic task rows collected from process-local state.
+ * @returns Merged counters including the injected tasks.
+ */
+function mergeInjectedAdminChatTaskCounters(
+    databaseCounters: AdminChatTaskCounters,
+    injectedTasks: ReadonlyArray<AdminChatTaskRecord>,
+): AdminChatTaskCounters {
+    if (injectedTasks.length === 0) {
+        return databaseCounters;
+    }
+
+    const nowTimestamp = Date.now();
+    const injectedQueuedTimestamps = injectedTasks
+        .filter((task) => task.status === 'QUEUED')
+        .map((task) => Date.parse(task.queuedAt))
+        .filter((timestamp) => Number.isFinite(timestamp));
+    const oldestInjectedQueuedAgeMs =
+        injectedQueuedTimestamps.length === 0 ? null : nowTimestamp - Math.min(...injectedQueuedTimestamps);
+
+    return {
+        runningCount: databaseCounters.runningCount + injectedTasks.filter((task) => task.status === 'RUNNING').length,
+        queuedCount: databaseCounters.queuedCount + injectedTasks.filter((task) => task.status === 'QUEUED').length,
+        failedLast24hCount:
+            databaseCounters.failedLast24hCount +
+            injectedTasks.filter(
+                (task) =>
+                    task.status === 'FAILED' &&
+                    isIsoTimestampAtOrAfter(task.finishedAt, nowTimestamp - 24 * HOUR_IN_MILLISECONDS),
+            ).length,
+        oldestQueuedAgeMs: mergeOldestQueuedAge(databaseCounters.oldestQueuedAgeMs, oldestInjectedQueuedAgeMs),
+    };
+}
+
+/**
+ * Merges durable and injected queued-task ages.
+ *
+ * @param databaseOldestQueuedAgeMs - Oldest durable queued-task age.
+ * @param injectedOldestQueuedAgeMs - Oldest injected queued-task age.
+ * @returns Oldest queued age across both sources.
+ */
+function mergeOldestQueuedAge(
+    databaseOldestQueuedAgeMs: number | null,
+    injectedOldestQueuedAgeMs: number | null,
+): number | null {
+    if (databaseOldestQueuedAgeMs === null) {
+        return injectedOldestQueuedAgeMs;
+    }
+
+    if (injectedOldestQueuedAgeMs === null) {
+        return databaseOldestQueuedAgeMs;
+    }
+
+    return Math.max(databaseOldestQueuedAgeMs, injectedOldestQueuedAgeMs);
+}
+
+/**
+ * Returns whether the injected task belongs in the requested admin task-manager view.
+ *
+ * @param task - Injected task.
+ * @param query - Parsed admin task-manager query.
+ * @param nowTimestamp - Current epoch used for time-window filtering.
+ * @returns `true` when the task should be included.
+ */
+function matchesAdminChatTaskView(
+    task: AdminChatTaskRecord,
+    query: ParsedAdminChatTaskQuery,
+    nowTimestamp: number,
+): boolean {
+    switch (query.view) {
+        case 'running':
+            return task.status === 'RUNNING';
+        case 'queued':
+            return task.status === 'QUEUED';
+        case 'failed':
+            return (
+                task.status === 'FAILED' &&
+                isIsoTimestampAtOrAfter(task.finishedAt, nowTimestamp - 24 * HOUR_IN_MILLISECONDS)
+            );
+        case 'all':
+            return isIsoTimestampAtOrAfter(task.updatedAt, nowTimestamp - query.timeWindowHours * HOUR_IN_MILLISECONDS);
+        case 'active':
+        default:
+            return task.status === 'QUEUED' || task.status === 'RUNNING';
+    }
+}
+
+/**
+ * Returns whether the injected task matches the free-text admin search input.
+ *
+ * @param task - Injected task.
+ * @param search - Trimmed search text from the parsed query.
+ * @returns `true` when the task should be included.
+ */
+function matchesAdminChatTaskSearch(task: AdminChatTaskRecord, search: string): boolean {
+    if (!search) {
+        return true;
+    }
+
+    const normalizedSearch = search.toLowerCase();
+    if (task.id.toLowerCase().includes(normalizedSearch)) {
+        return true;
+    }
+    if (task.agentPermanentId.toLowerCase().includes(normalizedSearch)) {
+        return true;
+    }
+    if ((task.agentName || '').toLowerCase().includes(normalizedSearch)) {
+        return true;
+    }
+    return task.chatId.toLowerCase().includes(normalizedSearch);
+}
+
+/**
+ * Returns whether one ISO timestamp is at or after the given cutoff.
+ *
+ * @param timestampIso - Optional ISO timestamp.
+ * @param cutoffTimestamp - Epoch cutoff in milliseconds.
+ * @returns `true` when the timestamp is at or after the cutoff.
+ */
+function isIsoTimestampAtOrAfter(timestampIso: string | null, cutoffTimestamp: number): boolean {
+    if (!timestampIso) {
+        return false;
+    }
+
+    const timestamp = Date.parse(timestampIso);
+    return Number.isFinite(timestamp) && timestamp >= cutoffTimestamp;
+}

package/apps/agents-server/src/utils/pagePreviewBrowserSessions.ts

@@ -0,0 +1,234 @@
+import type { Page } from 'playwright';
+import type { AdminChatTaskRecord } from './chatTasksAdmin';
+import type { UserInfo } from './getCurrentUser';
+
+/**
+ * Prefix for browser-preview session identifiers created by the citation preview UI.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_SESSION_ID_PREFIX = 'page-preview-';
+
+/**
+ * Pattern accepted for client-created page-preview session identifiers.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_SESSION_ID_PATTERN = /^page-preview-[a-z0-9-]{16,80}$/;
+
+/**
+ * Queue name used when active browser previews are surfaced in the admin task manager.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_TASK_QUEUE_NAME = 'page-preview-browser';
+
+/**
+ * Agent label used by the task manager for browser-preview rows.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_TASK_AGENT_NAME = 'Browser preview';
+
+/**
+ * In-memory record for one live browser preview stream.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type PagePreviewBrowserSession = {
+    readonly id: string;
+    readonly url: string;
+    readonly userId: number;
+    readonly username: string | null;
+    readonly createdAt: string;
+    readonly startedAt: string;
+    readonly processId: number | null;
+    page: Page | null;
+    viewport: PagePreviewBrowserViewport | null;
+    updatedAt: string;
+    lastFrameAt: string | null;
+};
+
+/**
+ * Browser viewport used to convert pointer ratios into Playwright coordinates.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type PagePreviewBrowserViewport = {
+    readonly width: number;
+    readonly height: number;
+};
+
+/**
+ * Options used when registering one browser preview stream.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type RegisterPagePreviewBrowserSessionOptions = {
+    readonly sessionId: string;
+    readonly url: string;
+    readonly user: UserInfo;
+};
+
+/**
+ * Shared in-memory browser-preview registry.
+ *
+ * The route streams are short-lived and tied to the current Node process, so a
+ * durable database row would create stale task-manager entries after restarts.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const pagePreviewBrowserSessions = new Map<string, PagePreviewBrowserSession>();
+
+/**
+ * Creates a normalized page-preview browser session id.
+ *
+ * @param requestedSessionId - Optional client-created session id.
+ * @returns Valid session id or `null` when the supplied value is invalid.
+ */
+export function normalizePagePreviewBrowserSessionId(requestedSessionId: string | null): string | null {
+    if (!requestedSessionId) {
+        return null;
+    }
+
+    const normalizedSessionId = requestedSessionId.trim().toLowerCase();
+    return PAGE_PREVIEW_BROWSER_SESSION_ID_PATTERN.test(normalizedSessionId) ? normalizedSessionId : null;
+}
+
+/**
+ * Registers or replaces one active browser preview session.
+ *
+ * @param options - Session metadata.
+ * @returns Registered session snapshot.
+ */
+export function registerPagePreviewBrowserSession(
+    options: RegisterPagePreviewBrowserSessionOptions,
+): PagePreviewBrowserSession {
+    const now = new Date().toISOString();
+    const previousSession = pagePreviewBrowserSessions.get(options.sessionId);
+    if (previousSession?.page) {
+        void previousSession.page.close().catch(() => undefined);
+    }
+
+    const session: PagePreviewBrowserSession = {
+        id: options.sessionId,
+        url: options.url,
+        userId: options.user.id ?? 0,
+        username: options.user.username,
+        createdAt: now,
+        startedAt: now,
+        updatedAt: now,
+        lastFrameAt: null,
+        processId: typeof process.pid === 'number' ? process.pid : null,
+        page: null,
+        viewport: null,
+    };
+
+    pagePreviewBrowserSessions.set(options.sessionId, session);
+    return session;
+}
+
+/**
+ * Attaches the Playwright page used by one live browser preview.
+ *
+ * @param sessionId - Active session id.
+ * @param page - Playwright page bound to the stream.
+ * @param viewport - Viewport used by the stream.
+ */
+export function attachPagePreviewBrowserSessionPage(
+    sessionId: string,
+    page: Page,
+    viewport: PagePreviewBrowserViewport,
+): void {
+    const session = pagePreviewBrowserSessions.get(sessionId);
+    if (!session) {
+        return;
+    }
+
+    session.page = page;
+    session.viewport = viewport;
+    session.updatedAt = new Date().toISOString();
+}
+
+/**
+ * Marks that one stream frame has been delivered.
+ *
+ * @param sessionId - Active session id.
+ */
+export function markPagePreviewBrowserSessionFrame(sessionId: string): void {
+    const session = pagePreviewBrowserSessions.get(sessionId);
+    if (!session) {
+        return;
+    }
+
+    const now = new Date().toISOString();
+    session.lastFrameAt = now;
+    session.updatedAt = now;
+}
+
+/**
+ * Removes one browser preview session from the active registry.
+ *
+ * @param sessionId - Active session id.
+ */
+export function finishPagePreviewBrowserSession(sessionId: string): void {
+    pagePreviewBrowserSessions.delete(sessionId);
+}
+
+/**
+ * Returns the active browser preview session when owned by the current user.
+ *
+ * @param sessionId - Browser preview session id.
+ * @param user - Current authenticated user.
+ * @returns Session or `null` when missing or owned by a different user.
+ */
+export function findUserPagePreviewBrowserSession(
+    sessionId: string,
+    user: UserInfo,
+): PagePreviewBrowserSession | null {
+    const session = pagePreviewBrowserSessions.get(sessionId);
+    if (!session) {
+        return null;
+    }
+
+    if ((user.id ?? 0) !== session.userId || user.username !== session.username) {
+        return null;
+    }
+
+    return session;
+}
+
+/**
+ * Lists active browser preview sessions as admin task-manager rows.
+ *
+ * @returns Task-manager rows for streams currently attached to this process.
+ */
+export function listPagePreviewBrowserAdminTasks(): Array<AdminChatTaskRecord> {
+    return Array.from(pagePreviewBrowserSessions.values()).map((session) => ({
+        id: session.id,
+        kind: 'BROWSER_PREVIEW',
+        status: 'RUNNING',
+        createdAt: session.createdAt,
+        queuedAt: session.createdAt,
+        startedAt: session.startedAt,
+        updatedAt: session.updatedAt,
+        finishedAt: null,
+        cancelRequestedAt: null,
+        pausedAt: null,
+        lastHeartbeatAt: session.lastFrameAt,
+        leaseExpiresAt: null,
+        recurrenceIntervalMs: null,
+        priority: null,
+        attemptCount: 1,
+        retryCount: 0,
+        lastErrorSummary: null,
+        lastErrorDetails: session.url,
+        userId: session.userId,
+        username: session.username,
+        agentPermanentId: PAGE_PREVIEW_BROWSER_SESSION_ID_PREFIX,
+        agentName: PAGE_PREVIEW_BROWSER_TASK_AGENT_NAME,
+        chatId: session.url,
+        workerId: session.processId === null ? null : String(session.processId),
+        queueName: PAGE_PREVIEW_BROWSER_TASK_QUEUE_NAME,
+    }));
+}

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

@@ -1042,6 +1042,18 @@ function resolveVpsSelfUpdateStateDirectory(): string {
     return resolve(dirname(resolveVpsEnvironmentFilePath()), '.promptbook', 'self-update');
 }
 
+/**
+ * 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).
+ */
+export async function readVpsSelfUpdateJobSnapshot(): Promise<VpsSelfUpdateJobSnapshot> {
+    return readPersistedVpsSelfUpdateJob();
+}
+
 /**
  * Reads one persisted update-job snapshot from disk.
  *

package/esm/index.es.js

@@ -59,7 +59,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.113.0-0';
+const PROMPTBOOK_ENGINE_VERSION = '0.113.0-2';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -30182,9 +30182,10 @@ function buildAgentMessagePrompt(messageRelativePath, agentSystemMessage) {
 
                 [Up to 50,000 CZK](?message=We are posting an order up to 50,000 CZK)
                 [Up to 100,000 CZK](?message=We are posting an order up to 100,000 CZK)
-                [Over 100,000 CZK](?message=We are posting an order over 100,000 CZK)
+                [Over 100,000 CZK](?messageDraft=We are posting an order over 100,000 CZK)
                 \`\`\`
 
+                - You can use \`message\` for message that will be sent immediately after clicking the button, or \`messageDraft\` for message that will be prefilled in the input field for editing before sending.
 
                 ## This is how you should behave
 
@@ -54635,6 +54636,12 @@ const DEPRECATED_TOP_LEVEL_COMMAND_MESSAGES = {
     'start-agents-server': 'Use `ptbk agents-server start` instead.',
     'start-pipelines-server': OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
 };
+/**
+ * Raw top-level CLI arguments that print the Promptbook version.
+ *
+ * @private internal constant of `promptbookCli`
+ */
+const VERSION_OPTION_ARGUMENTS = new Set(['-v', '--version']);
 /**
  * Runs CLI utilities of Promptbook package
  *
@@ -54649,8 +54656,13 @@ async function promptbookCli() {
 
             `));
     }
-    const cliArguments = process.argv.slice(2);
-    const isVerbose = cliArguments.some((arg) => arg === '--verbose' || arg === '-v');
+    const commandLineArguments = process.argv.slice(2);
+    const isVersionRequested = isTopLevelVersionRequested(commandLineArguments);
+    if (isVersionRequested) {
+        console.info(PROMPTBOOK_ENGINE_VERSION);
+        return process.exit(0);
+    }
+    const isVerbose = commandLineArguments.some((argument) => argument === '--verbose' || argument === '-v');
     //     <- TODO: Can be this be done with commander before the commander commands are initialized?
     if (isVerbose) {
         console.info(colors.gray(`Promptbook CLI version ${PROMPTBOOK_ENGINE_VERSION} in ${__filename.split('\\').join('/')}`));
@@ -54679,12 +54691,21 @@ async function promptbookCli() {
     $deprecateTopLevelCommands(program);
     // TODO: [🧠] Should it be here or not> $addGlobalOptionsToCommand(program);
     program.commands.forEach($addGlobalOptionsToCommand);
-    if (cliArguments.length === 0) {
+    if (commandLineArguments.length === 0) {
         program.outputHelp();
         return process.exit(0);
     }
     program.parse(process.argv);
 }
+/**
+ * Checks whether the invocation asks for the root Promptbook CLI version.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function isTopLevelVersionRequested(commandLineArguments) {
+    const firstCommandLineArgument = commandLineArguments[0];
+    return firstCommandLineArgument !== undefined && VERSION_OPTION_ARGUMENTS.has(firstCommandLineArgument);
+}
 /**
  * Adds one deprecation notice to each configured top-level legacy command.
  */