@promptbook/cli 0.113.0-1 → 0.113.0-10

package/apps/agents-server/src/utils/backup/serverBackup/createServerBackupManifest.ts

@@ -0,0 +1,82 @@
+import {
+    DEFAULT_SERVER_BACKUP_SECTION_KEYS,
+    type ServerBackupSectionDefinition,
+    type ServerBackupSectionKey,
+} from '../serverBackupSections';
+
+/**
+ * Stable archive format identifier for the user-facing backup layout.
+ *
+ * @private constant of `createServerBackupZipStream`
+ */
+const SERVER_BACKUP_FORMAT = 'promptbook-server-backup/v2';
+
+/**
+ * High-level manifest written into every server backup ZIP.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type ServerBackupManifest = {
+    /**
+     * Stable backup archive format identifier.
+     */
+    readonly format: typeof SERVER_BACKUP_FORMAT;
+    /**
+     * ISO timestamp when the archive was generated.
+     */
+    readonly generatedAt: string;
+    /**
+     * Whether the archive includes every default exportable section.
+     */
+    readonly isFullBackup: boolean;
+    /**
+     * Ordered list of exported section keys.
+     */
+    readonly selectedSections: ReadonlyArray<ServerBackupSectionKey>;
+    /**
+     * Human-readable section details for restore/debug tooling.
+     */
+    readonly sections: ReadonlyArray<{
+        readonly key: ServerBackupSectionKey;
+        readonly label: string;
+        readonly description: string;
+        readonly directoryName: string;
+        readonly selectionKind: ServerBackupSectionDefinition['selectionKind'];
+        readonly includesBooks: boolean;
+    }>;
+};
+
+/**
+ * Builds the high-level manifest describing one server backup archive.
+ *
+ * @param options - Generation timestamp and the resolved selection.
+ * @returns Manifest payload ready to serialize into `manifest.json`.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createServerBackupManifest(options: {
+    generatedAt: string;
+    selectedSectionKeys: ReadonlyArray<ServerBackupSectionKey>;
+    selectedSectionDefinitions: ReadonlyArray<ServerBackupSectionDefinition>;
+}): ServerBackupManifest {
+    const { generatedAt, selectedSectionKeys, selectedSectionDefinitions } = options;
+
+    return {
+        format: SERVER_BACKUP_FORMAT,
+        generatedAt,
+        isFullBackup:
+            selectedSectionKeys.length === DEFAULT_SERVER_BACKUP_SECTION_KEYS.length &&
+            DEFAULT_SERVER_BACKUP_SECTION_KEYS.every((sectionKey, index) => selectedSectionKeys[index] === sectionKey),
+        selectedSections: selectedSectionKeys,
+        sections: selectedSectionDefinitions.map(
+            ({ key, label, description, directoryName, selectionKind, includesBooks }) => ({
+                key,
+                label,
+                description,
+                directoryName,
+                selectionKind,
+                includesBooks,
+            }),
+        ),
+    };
+}

package/apps/agents-server/src/utils/backup/serverBackup/downloadBackupBinaryContent.ts

@@ -0,0 +1,39 @@
+/**
+ * Downloads one binary file for backup inclusion.
+ *
+ * @param url - Public binary URL to fetch.
+ * @returns Download result with either binary content or an explanatory error.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export async function downloadBackupBinaryContent(url: string | null): Promise<{
+    content: ArrayBuffer | null;
+    error: string | null;
+}> {
+    if (!url) {
+        return {
+            content: null,
+            error: 'Missing content URL.',
+        };
+    }
+
+    try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            return {
+                content: null,
+                error: `Failed to download content (${response.status} ${response.statusText}).`,
+            };
+        }
+
+        return {
+            content: await response.arrayBuffer(),
+            error: null,
+        };
+    } catch (error) {
+        return {
+            content: null,
+            error: error instanceof Error ? error.message : 'Unknown download error.',
+        };
+    }
+}

package/apps/agents-server/src/utils/backup/serverBackup/resolveFeedbackThreadMessages.ts

@@ -0,0 +1,53 @@
+import { isRecord } from './serverBackupRowUtilities';
+
+/**
+ * Parses the persisted feedback chat thread into the same array shape used by chat JSON exports.
+ *
+ * @param rawChatThread - Raw persisted feedback thread.
+ * @returns Parsed chat messages together with an optional raw fallback string.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function resolveFeedbackThreadMessages(rawChatThread: unknown): {
+    messages: Array<Record<string, unknown>>;
+    rawChatThreadText: string | null;
+} {
+    if (Array.isArray(rawChatThread)) {
+        return {
+            messages: rawChatThread.filter(isRecord),
+            rawChatThreadText: null,
+        };
+    }
+
+    if (typeof rawChatThread !== 'string') {
+        return {
+            messages: [],
+            rawChatThreadText: null,
+        };
+    }
+
+    const normalizedChatThreadText = rawChatThread.trim();
+    if (normalizedChatThreadText.length === 0) {
+        return {
+            messages: [],
+            rawChatThreadText: null,
+        };
+    }
+
+    try {
+        const parsed = JSON.parse(normalizedChatThreadText);
+        if (Array.isArray(parsed)) {
+            return {
+                messages: parsed.filter(isRecord),
+                rawChatThreadText: null,
+            };
+        }
+    } catch {
+        // Keep the original text below so the backup still preserves the source thread payload.
+    }
+
+    return {
+        messages: [],
+        rawChatThreadText: normalizedChatThreadText,
+    };
+}

package/apps/agents-server/src/utils/backup/serverBackup/serverBackupAttachments.ts

@@ -0,0 +1,151 @@
+import { resolveFeedbackThreadMessages } from './resolveFeedbackThreadMessages';
+import { normalizeOptionalText, resolveSerializableArray } from './serverBackupRowUtilities';
+import type { BackupAgentPreview, BackupUserPreview, ChatFeedbackRow, UserChatRow } from './serverBackupTypes';
+
+/**
+ * Attachment reference stored alongside exported files/media metadata.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type BackupAttachmentReference = {
+    readonly source: 'user-chat' | 'chat-feedback';
+    readonly messageIndex: number;
+    readonly messageId: string | null;
+    readonly attachmentName: string | null;
+    readonly sender: unknown;
+    readonly chatId?: string;
+    readonly chatTitle?: string | null;
+    readonly feedbackId?: number;
+    readonly user?: BackupUserPreview | null;
+    readonly agent?: BackupAgentPreview | null;
+};
+
+/**
+ * Builds one map of attachment URLs to the user-facing messages that reference them.
+ *
+ * @param options - Attachment map source data.
+ * @returns Attachment references keyed by URL.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createAttachmentReferencesByUrl(options: {
+    userChats: ReadonlyArray<UserChatRow>;
+    feedbackRows: ReadonlyArray<ChatFeedbackRow>;
+    userPreviewById: ReadonlyMap<number, BackupUserPreview>;
+    agentPreviewByPermanentId: ReadonlyMap<string, BackupAgentPreview>;
+    agentPreviewByName: ReadonlyMap<string, BackupAgentPreview>;
+}): Map<string, Array<BackupAttachmentReference>> {
+    const attachmentReferencesByUrl = new Map<string, Array<BackupAttachmentReference>>();
+
+    const appendReference = (url: string, reference: BackupAttachmentReference): void => {
+        const references = attachmentReferencesByUrl.get(url) || [];
+        references.push(reference);
+        attachmentReferencesByUrl.set(url, references);
+    };
+
+    for (const chat of options.userChats) {
+        const userPreview = options.userPreviewById.get(chat.userId) || null;
+        const agentPreview = options.agentPreviewByPermanentId.get(chat.agentPermanentId) || null;
+
+        for (const [messageIndex, message] of resolveSerializableArray(chat.messages).entries()) {
+            for (const attachment of resolveMessageAttachments(message)) {
+                appendReference(attachment.url, {
+                    source: 'user-chat',
+                    chatId: chat.id,
+                    chatTitle: chat.title,
+                    messageIndex,
+                    messageId: normalizeOptionalText((message as { id?: unknown }).id),
+                    attachmentName: attachment.name,
+                    sender: (message as { sender?: unknown }).sender ?? null,
+                    user: userPreview,
+                    agent: agentPreview,
+                });
+            }
+        }
+    }
+
+    for (const feedbackRow of options.feedbackRows) {
+        const agentPreview = options.agentPreviewByName.get(feedbackRow.agentName) || null;
+        const { messages } = resolveFeedbackThreadMessages(feedbackRow.chatThread);
+
+        for (const [messageIndex, message] of messages.entries()) {
+            for (const attachment of resolveMessageAttachments(message)) {
+                appendReference(attachment.url, {
+                    source: 'chat-feedback',
+                    feedbackId: feedbackRow.id,
+                    messageIndex,
+                    messageId: normalizeOptionalText((message as { id?: unknown }).id),
+                    attachmentName: attachment.name,
+                    sender: (message as { sender?: unknown }).sender ?? null,
+                    agent: agentPreview,
+                });
+            }
+        }
+    }
+
+    return attachmentReferencesByUrl;
+}
+
+/**
+ * Resolves attachment references for the provided URLs.
+ *
+ * @param attachmentReferencesByUrl - Attachment reference map keyed by URL.
+ * @param candidateUrls - Possible URLs for one backed-up file.
+ * @returns Flattened reference list.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function resolveAttachmentReferencesForUrls(
+    attachmentReferencesByUrl: ReadonlyMap<string, ReadonlyArray<BackupAttachmentReference>>,
+    candidateUrls: ReadonlyArray<string | null>,
+): Array<BackupAttachmentReference> {
+    const references: Array<BackupAttachmentReference> = [];
+
+    for (const candidateUrl of candidateUrls) {
+        const normalizedUrl = normalizeOptionalText(candidateUrl);
+        if (!normalizedUrl) {
+            continue;
+        }
+
+        const matches = attachmentReferencesByUrl.get(normalizedUrl) || [];
+        references.push(...matches);
+    }
+
+    return references;
+}
+
+/**
+ * Extracts normalized attachment previews from one serialized chat message.
+ *
+ * @param message - One serialized chat message candidate.
+ * @returns Normalized attachment previews with required URLs.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+function resolveMessageAttachments(message: Record<string, unknown>): Array<{
+    name: string | null;
+    url: string;
+}> {
+    const rawAttachments = message.attachments;
+    if (!Array.isArray(rawAttachments)) {
+        return [];
+    }
+
+    return rawAttachments.flatMap((attachment) => {
+        if (!attachment || typeof attachment !== 'object' || Array.isArray(attachment)) {
+            return [];
+        }
+
+        const url = normalizeOptionalText((attachment as { url?: unknown }).url);
+        if (!url) {
+            return [];
+        }
+
+        return [
+            {
+                name: normalizeOptionalText((attachment as { name?: unknown }).name),
+                url,
+            },
+        ];
+    });
+}

package/apps/agents-server/src/utils/backup/serverBackup/serverBackupContext.ts

@@ -0,0 +1,167 @@
+import { $getTableName } from '../../../database/$getTableName';
+import { $provideSupabaseForServer } from '../../../database/$provideSupabaseForServer';
+import type { AgentsServerDatabase } from '../../../database/schema';
+import { sortBackupRows } from './serverBackupRowUtilities';
+import type { AgentRow, ChatFeedbackRow, UserChatRow, UserRow } from './serverBackupTypes';
+
+/**
+ * JSON payload persisted for legacy table-backed exports.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type BackupTableFilePayload = {
+    /**
+     * Logical entity name from the generated schema types.
+     */
+    readonly entity: keyof AgentsServerDatabase['public']['Tables'];
+    /**
+     * Physical table name used by the current server installation.
+     */
+    readonly databaseTable: string;
+    /**
+     * Total number of exported rows.
+     */
+    readonly rowCount: number;
+    /**
+     * Ordered snapshot rows.
+     */
+    readonly rows: ReadonlyArray<Record<string, unknown>>;
+};
+
+/**
+ * Shared context with lazy-loaded table snapshots reused across multiple sections.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type ServerBackupContext = {
+    readonly supabase: ReturnType<typeof $provideSupabaseForServer>;
+    userRowsPromise?: Promise<Array<UserRow>>;
+    agentRowsPromise?: Promise<Array<AgentRow>>;
+    userChatRowsPromise?: Promise<Array<UserChatRow>>;
+    chatFeedbackRowsPromise?: Promise<Array<ChatFeedbackRow>>;
+};
+
+/**
+ * Creates the shared backup context with lazy table loaders.
+ *
+ * @param supabase - Server-side Supabase client.
+ * @returns Reusable backup context.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createServerBackupContext(
+    supabase: ReturnType<typeof $provideSupabaseForServer>,
+): ServerBackupContext {
+    return {
+        supabase,
+    };
+}
+
+/**
+ * Reads one logical table and converts it into a deterministic JSON backup payload.
+ *
+ * @param supabase - Server-side Supabase client.
+ * @param tableKey - Logical table key from the generated schema.
+ * @returns Serializable table payload for the archive.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export async function loadBackupTableFilePayload(
+    supabase: ReturnType<typeof $provideSupabaseForServer>,
+    tableKey: keyof AgentsServerDatabase['public']['Tables'],
+): Promise<BackupTableFilePayload> {
+    const tableName = await $getTableName(tableKey);
+    const result = await supabase.from(tableName).select('*');
+
+    if (result.error) {
+        throw new Error(`Unable to load backup table ${tableKey}: ${result.error.message}`);
+    }
+
+    const rows = sortBackupRows(
+        (((result.data || []) as unknown as Array<Record<string, unknown>>).map((row) => ({ ...row }))),
+    );
+
+    return {
+        entity: tableKey,
+        databaseTable: tableName,
+        rowCount: rows.length,
+        rows,
+    };
+}
+
+/**
+ * Reads one logical table into typed rows.
+ *
+ * @param supabase - Server-side Supabase client.
+ * @param tableKey - Logical table key from the generated schema.
+ * @returns Ordered table rows.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export async function loadTableRows<TableKey extends keyof AgentsServerDatabase['public']['Tables']>(
+    supabase: ReturnType<typeof $provideSupabaseForServer>,
+    tableKey: TableKey,
+): Promise<Array<AgentsServerDatabase['public']['Tables'][TableKey]['Row']>> {
+    const tableName = await $getTableName(tableKey);
+    const result = await supabase.from(tableName).select('*');
+
+    if (result.error) {
+        throw new Error(`Unable to load backup table ${String(tableKey)}: ${result.error.message}`);
+    }
+
+    return sortBackupRows((result.data || []) as unknown as Array<Record<string, unknown>>) as Array<
+        AgentsServerDatabase['public']['Tables'][TableKey]['Row']
+    >;
+}
+
+/**
+ * Lazily loads users once for the backup run.
+ *
+ * @param context - Shared backup context.
+ * @returns Cached user rows.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function loadUserRows(context: ServerBackupContext): Promise<Array<UserRow>> {
+    context.userRowsPromise = context.userRowsPromise || loadTableRows(context.supabase, 'User');
+    return context.userRowsPromise;
+}
+
+/**
+ * Lazily loads agents once for the backup run.
+ *
+ * @param context - Shared backup context.
+ * @returns Cached agent rows.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function loadAgentRows(context: ServerBackupContext): Promise<Array<AgentRow>> {
+    context.agentRowsPromise = context.agentRowsPromise || loadTableRows(context.supabase, 'Agent');
+    return context.agentRowsPromise;
+}
+
+/**
+ * Lazily loads user chats once for the backup run.
+ *
+ * @param context - Shared backup context.
+ * @returns Cached user-chat rows.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function loadUserChatRows(context: ServerBackupContext): Promise<Array<UserChatRow>> {
+    context.userChatRowsPromise = context.userChatRowsPromise || loadTableRows(context.supabase, 'UserChat');
+    return context.userChatRowsPromise;
+}
+
+/**
+ * Lazily loads feedback rows once for the backup run.
+ *
+ * @param context - Shared backup context.
+ * @returns Cached feedback rows.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function loadChatFeedbackRows(context: ServerBackupContext): Promise<Array<ChatFeedbackRow>> {
+    context.chatFeedbackRowsPromise = context.chatFeedbackRowsPromise || loadTableRows(context.supabase, 'ChatFeedback');
+    return context.chatFeedbackRowsPromise;
+}

package/apps/agents-server/src/utils/backup/serverBackup/serverBackupFilenames.ts

@@ -0,0 +1,161 @@
+import { sanitizeBackupPathSegment } from '../sanitizeBackupPathSegment';
+import { normalizeOptionalText } from './serverBackupRowUtilities';
+
+/**
+ * JSON file extension used by the per-entity exports.
+ *
+ * @private constant of `createServerBackupZipStream`
+ */
+const JSON_FILE_EXTENSION = '.json';
+
+/**
+ * Resolves the preferred binary backup filename while keeping the original file extension when available.
+ *
+ * @param fileName - Stored filename/path.
+ * @param fallbackUrl - Public file URL used when the filename is empty.
+ * @param fallbackStem - Deterministic fallback stem.
+ * @returns Safe filename for the ZIP archive.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function resolveBinaryBackupFilename(
+    fileName: string | null | undefined,
+    fallbackUrl: string | null | undefined,
+    fallbackStem: string,
+): string {
+    const rawBaseName =
+        resolvePathBasename(fileName, '') ||
+        resolvePathBasename(fallbackUrl, '') ||
+        fallbackStem;
+
+    return sanitizeBackupPathSegment(rawBaseName, fallbackStem);
+}
+
+/**
+ * Creates one human-readable backup filename stem from optional labels.
+ *
+ * @param labels - Preferred labels ordered by importance.
+ * @param fallbackStem - Deterministic fallback stem.
+ * @returns Safe filename stem without extension.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createBackupStem(
+    labels: ReadonlyArray<string | null | undefined>,
+    fallbackStem: string,
+): string {
+    const normalizedLabels = labels
+        .map((label) => normalizeOptionalText(label))
+        .filter((label): label is string => Boolean(label));
+
+    return sanitizeBackupPathSegment(
+        normalizedLabels.length > 0 ? normalizedLabels.join(' -- ') : fallbackStem,
+        fallbackStem,
+    );
+}
+
+/**
+ * Ensures one filename ends with `.json`.
+ *
+ * @param filenameStem - Filename stem or full filename.
+ * @returns JSON filename.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function ensureJsonFilename(filenameStem: string): string {
+    return filenameStem.endsWith(JSON_FILE_EXTENSION) ? filenameStem : `${filenameStem}${JSON_FILE_EXTENSION}`;
+}
+
+/**
+ * Creates the metadata sidecar filename for a JSON export file.
+ *
+ * @param jsonFilename - Main JSON filename.
+ * @returns Sidecar metadata filename.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createJsonMetadataFilename(jsonFilename: string): string {
+    return jsonFilename.endsWith(JSON_FILE_EXTENSION)
+        ? `${jsonFilename.slice(0, -JSON_FILE_EXTENSION.length)}.metadata.json`
+        : `${jsonFilename}.metadata.json`;
+}
+
+/**
+ * Creates the metadata sidecar filename for a binary export file.
+ *
+ * @param filename - Main binary filename.
+ * @returns Sidecar metadata filename.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createBinaryMetadataFilename(filename: string): string {
+    return `${filename}.metadata.json`;
+}
+
+/**
+ * Creates a unique filename inside one ZIP folder with deterministic suffixes.
+ *
+ * @param usedFilenames - Already allocated filenames in the folder.
+ * @param filename - Preferred filename candidate.
+ * @param suffixBase - Deterministic suffix base used on collisions.
+ * @returns Unique filename for the ZIP folder.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createUniqueBackupFilename(
+    usedFilenames: Set<string>,
+    filename: string,
+    suffixBase: string,
+): string {
+    if (!usedFilenames.has(filename)) {
+        usedFilenames.add(filename);
+        return filename;
+    }
+
+    const extensionIndex = filename.lastIndexOf('.');
+    const hasExtension = extensionIndex > 0;
+    const filenameBase = hasExtension ? filename.slice(0, extensionIndex) : filename;
+    const extension = hasExtension ? filename.slice(extensionIndex) : '';
+
+    for (let suffixIndex = 0; suffixIndex < Number.MAX_SAFE_INTEGER; suffixIndex += 1) {
+        const suffix = suffixIndex === 0 ? `--${suffixBase}` : `--${suffixBase}-${suffixIndex + 1}`;
+        const nextFilename = `${filenameBase}${suffix}${extension}`;
+
+        if (!usedFilenames.has(nextFilename)) {
+            usedFilenames.add(nextFilename);
+            return nextFilename;
+        }
+    }
+
+    throw new Error(`Unable to allocate unique backup filename for ${suffixBase}.`);
+}
+
+/**
+ * Resolves the basename from a stored path or URL.
+ *
+ * @param value - Stored path or URL.
+ * @param fallback - Fallback filename when no basename exists.
+ * @returns Basename without parent directories or query strings.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function resolvePathBasename(value: string | null | undefined, fallback: string): string {
+    const normalizedValue = normalizeOptionalText(value);
+    if (!normalizedValue) {
+        return fallback;
+    }
+
+    try {
+        const url = new URL(normalizedValue);
+        const urlPathSegments = url.pathname.split('/').filter(Boolean);
+        const urlBaseName = urlPathSegments[urlPathSegments.length - 1];
+        if (urlBaseName) {
+            return decodeURIComponent(urlBaseName);
+        }
+    } catch {
+        // Continue with plain path parsing below.
+    }
+
+    const pathSegments = normalizedValue.split(/[\\/]/).filter(Boolean);
+    return pathSegments[pathSegments.length - 1] || fallback;
+}