@promptbook/cli 0.112.0-134 → 0.112.0-136

package/apps/agents-server/src/utils/backup/createBooksBackupZipStream.ts

@@ -129,7 +129,9 @@ export async function appendBooksBackupEntriesToZip(zip: JSZip, archiveRootPath:
     const resolveFolderPath = createFolderPathResolver(folders, folderSegmentById);
 
     // Keep the root directory explicit even when there are no agents.
-    zip.folder(archiveRootPath);
+    if (archiveRootPath) {
+        zip.folder(archiveRootPath);
+    }
 
     const relativeFilePaths = new Set<string>();
     const folderPathByAgentId = new Map<number, string>();
@@ -152,10 +154,21 @@ export async function appendBooksBackupEntriesToZip(zip: JSZip, archiveRootPath:
         const folderSegments = resolveFolderPath(agent.folderId ?? null);
         const initialBookFilename = createInitialBookFilename(agent);
         const relativePath = createUniqueBookRelativePath(relativeFilePaths, folderSegments, initialBookFilename, agent.id);
-        zip.file(`${archiveRootPath}/${relativePath}`, agent.agentSource || '');
+        zip.file(createArchivePath(archiveRootPath, relativePath), agent.agentSource || '');
     }
 }
 
+/**
+ * Joins an optional archive root with one relative path.
+ *
+ * @param archiveRootPath - Optional ZIP folder root.
+ * @param relativePath - Book path relative to the selected root.
+ * @returns ZIP-safe path without a leading slash.
+ */
+function createArchivePath(archiveRootPath: string, relativePath: string): string {
+    return archiveRootPath ? `${archiveRootPath}/${relativePath}` : relativePath;
+}
+
 /**
  * Builds a download-ready stream with all books organized by the Agents Server folder tree.
  *

package/apps/agents-server/src/utils/defaultAgents/loadDefaultAgentBooks.ts

@@ -4,6 +4,13 @@ import type { string_book } from '../../../../../src/book-2.0/agent-source/strin
 import { DatabaseError } from '../../../../../src/errors/DatabaseError';
 import { spaceTrim } from 'spacetrim';
 
+/**
+ * Folder name on disk that contains the bundled `.core` agent books.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export const CORE_AGENT_DIRECTORY_NAME = '.core';
+
 /**
  * Options for loading bundled default agent books.
  *
@@ -42,14 +49,49 @@ export async function loadDefaultAgentBooks(
     options: LoadDefaultAgentBooksOptions = {},
 ): Promise<ReadonlyArray<string_book>> {
     const defaultAgentDirectory = await resolveDefaultAgentDirectory(options);
-    const directoryEntries = await readdir(defaultAgentDirectory);
-    const defaultAgentFilenames = directoryEntries
+    return loadAgentBooksFromDirectory(defaultAgentDirectory);
+}
+
+/**
+ * Loads all bundled `.core` agent books in deterministic filename order.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Sorted core agent sources, or an empty list when the `.core` subfolder is absent.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export async function loadCoreAgentBooks(
+    options: LoadDefaultAgentBooksOptions = {},
+): Promise<ReadonlyArray<string_book>> {
+    const defaultAgentDirectory = await resolveDefaultAgentDirectory(options);
+    const coreAgentDirectory = resolve(defaultAgentDirectory, CORE_AGENT_DIRECTORY_NAME);
+
+    try {
+        await access(coreAgentDirectory);
+    } catch {
+        return [];
+    }
+
+    return loadAgentBooksFromDirectory(coreAgentDirectory);
+}
+
+/**
+ * Reads `.book` files from one directory in deterministic filename order.
+ *
+ * @param agentDirectory - Absolute path to the directory containing `.book` files.
+ * @returns Sorted agent sources.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+async function loadAgentBooksFromDirectory(agentDirectory: string): Promise<ReadonlyArray<string_book>> {
+    const directoryEntries = await readdir(agentDirectory);
+    const agentFilenames = directoryEntries
         .filter((entry) => entry.toLowerCase().endsWith('.book'))
         .sort((leftFilename, rightFilename) => leftFilename.localeCompare(rightFilename));
 
     return Promise.all(
-        defaultAgentFilenames.map(async (filename) => {
-            const filePath = resolve(defaultAgentDirectory, filename);
+        agentFilenames.map(async (filename) => {
+            const filePath = resolve(agentDirectory, filename);
             return (await readFile(filePath, 'utf-8')) as string_book;
         }),
     );

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

@@ -0,0 +1,36 @@
+import { findAgentByIdentifier, findOwnedAgentByIdentifier, type OwnedAgentRow } from './agentOwnership';
+import { getCurrentUser } from './getCurrentUser';
+import { isUserAdmin } from './isUserAdmin';
+
+/**
+ * Loads one agent for the current caller, enforcing ownership-or-admin write access.
+ *
+ * Resolution order:
+ * 1. Anonymous callers receive `null` so routes can return `403`.
+ * 2. Owners are matched via {@link findOwnedAgentByIdentifier} using the authenticated user id.
+ * 3. Administrators (resolved via {@link isUserAdmin}) fall through to {@link findAgentByIdentifier} so they can manage any agent — including legacy `ADMIN_PASSWORD` admins that have no database user id.
+ *
+ * @param identifier - Permanent id or agent name supplied by the route.
+ * @returns Matching agent row when the caller owns it or is an administrator, otherwise `null`.
+ *
+ * @private internal helper of Agents Server route handlers
+ */
+export async function findAgentForCallerWriteAccess(identifier: string): Promise<OwnedAgentRow | null> {
+    const [currentUser, isAdmin] = await Promise.all([getCurrentUser(), isUserAdmin()]);
+    if (!currentUser) {
+        return null;
+    }
+
+    if (typeof currentUser.id === 'number') {
+        const ownedAgent = await findOwnedAgentByIdentifier(currentUser.id, identifier);
+        if (ownedAgent) {
+            return ownedAgent;
+        }
+    }
+
+    if (!isAdmin) {
+        return null;
+    }
+
+    return findAgentByIdentifier(identifier);
+}

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

@@ -1,27 +1,6 @@
 import { string_promptbook_server_url } from '@promptbook-local/types';
 import { getMetadataMap } from '../database/getMetadata';
 
-/**
- * Options that tweak the behavior of `getFederatedServers`.
- *
- * @public exported from `apps/agents-server`
- */
-export type GetFederatedServersOptions = {
-    /**
-     * When set, hide the core server from the resulting list if the metadata flag requests it.
-     *
-     * @private Internal toggle for UI surfaces that should hide the core server.
-     */
-    readonly excludeHiddenCoreServer?: boolean;
-};
-
-/**
- * Metadata key storing the core server URL.
- *
- * @private
- */
-const CORE_SERVER_METADATA_KEY = 'CORE_SERVER';
-
 /**
  * Metadata key storing the comma-separated federated servers list.
  *
@@ -29,67 +8,17 @@ const CORE_SERVER_METADATA_KEY = 'CORE_SERVER';
  */
 const FEDERATED_SERVERS_METADATA_KEY = 'FEDERATED_SERVERS';
 
-/**
- * Metadata key indicating whether the core server should be hidden from UI lists.
- *
- * @private
- */
-const IS_CORE_SERVER_HIDDEN_METADATA_KEY = 'IS_CORE_SERVER_HIDDEN';
-
 /**
  * Reads FEDERATED_SERVERS metadata and returns a normalized list of server URLs.
  *
  * @public exported from `apps/agents-server`
  */
-export async function getFederatedServers(options?: GetFederatedServersOptions): Promise<string_promptbook_server_url[]> {
-    const metadata = await getMetadataMap([
-        FEDERATED_SERVERS_METADATA_KEY,
-        CORE_SERVER_METADATA_KEY,
-        IS_CORE_SERVER_HIDDEN_METADATA_KEY,
-    ]);
+export async function getFederatedServers(): Promise<string_promptbook_server_url[]> {
+    const metadata = await getMetadataMap([FEDERATED_SERVERS_METADATA_KEY]);
     const federatedServersString = metadata[FEDERATED_SERVERS_METADATA_KEY] || '';
-    const rawCoreServer = metadata[CORE_SERVER_METADATA_KEY] || '';
-    const coreServer = rawCoreServer.trim() as string_promptbook_server_url;
 
-    if (!coreServer) {
-        throw new Error('Missing CORE_SERVER metadata value');
-    }
-
-    const federatedServers = federatedServersString
+    return federatedServersString
         .split(',')
         .map((server) => server.trim())
         .filter((server): server is string_promptbook_server_url => server !== '');
-
-    const allServers = [coreServer, ...federatedServers];
-    if (options?.excludeHiddenCoreServer && isCoreServerHidden(metadata)) {
-        const normalizedCoreServer = normalizeServerUrl(coreServer);
-        return allServers.filter((server) => normalizeServerUrl(server) !== normalizedCoreServer);
-    }
-
-    return allServers;
-}
-
-/**
- * Determines if the metadata flag explicitly hides the core server from UI lists.
- *
- * @param metadata - Metadata map containing IS_CORE_SERVER_HIDDEN value.
- * @returns Whether the core server should be hidden.
- *
- * @private Internal helper for filtering UI-friendly lists.
- */
-function isCoreServerHidden(metadata: Record<string, string | null>): boolean {
-    const rawValue = metadata[IS_CORE_SERVER_HIDDEN_METADATA_KEY] || '';
-    return rawValue.trim().toLowerCase() === 'true';
-}
-
-/**
- * Normalizes a server URL by trimming trailing slashes for comparison purposes.
- *
- * @param value - Raw server URL.
- * @returns Normalized server URL.
- *
- * @private Internal helper used when filtering hidden servers.
- */
-function normalizeServerUrl(value: string): string {
-    return value.replace(/\/+$/, '');
 }

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

@@ -1,14 +1,20 @@
 import { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES } from '../../../../servers';
 import { string_agent_url } from '../../../../src/_packages/types.index'; // <- [🚾]
-import { getMetadata } from '../database/getMetadata';
+import { resolveCurrentOrInternalServerOrigin } from './resolveCurrentOrInternalServerOrigin';
 
 /**
- * Reads FEDERATED_SERVERS metadata and returns a normalized list of server URLs.
+ * Resolves the URL of one well-known agent (Adam, Teacher, ...) hosted locally in the `.core` folder of the current Agents Server.
+ *
+ * @param agentName - Logical well-known agent identifier.
+ * @returns Absolute URL of the well-known agent on the current server.
+ *
+ * @private utility of Agents Server
  */
 export async function getWellKnownAgentUrl(
     agentName: keyof typeof CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES,
 ): Promise<string_agent_url> {
-    const coreServer = (await getMetadata('CORE_SERVER'))!;
+    const localServerOrigin = await resolveCurrentOrInternalServerOrigin();
+    const normalizedServerOrigin = localServerOrigin.replace(/\/+$/g, '');
 
-    return `${coreServer}agents/${CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES[agentName]}` as string_agent_url;
+    return `${normalizedServerOrigin}/agents/${CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES[agentName]}` as string_agent_url;
 }

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

@@ -0,0 +1,426 @@
+import { spaceTrim } from 'spacetrim';
+import { DatabaseError } from '../../../../src/errors/DatabaseError';
+import { ParseError } from '../../../../src/errors/ParseError';
+import { normalizeToKebabCase } from '../../../../src/utils/normalization/normalize-to-kebab-case';
+import { removeEmojis } from '../../../../src/utils/normalization/removeEmojis';
+import { PROMPTBOOK_ENGINE_VERSION, type string_promptbook_version } from '../../../../src/version';
+import { $getTableName } from '../database/$getTableName';
+import { $provideSupabaseForServer } from '../database/$provideSupabaseForServer';
+import { invalidateMetadataCache } from '../database/getMetadata';
+import { getMetadataDefinition, metadataDefaults, validateMetadataValue } from '../database/metadataDefaults';
+import type { AgentsServerDatabase } from '../database/schema';
+
+/**
+ * Metadata key containing the human-readable server name.
+ */
+const SERVER_NAME_METADATA_KEY = 'SERVER_NAME';
+
+/**
+ * Fallback filename stem used when the server name cannot produce a safe name.
+ */
+const DEFAULT_METADATA_EXPORT_FILENAME_STEM = 'promptbook-agents-server';
+
+/**
+ * Filename suffix required for standalone metadata exports.
+ */
+const METADATA_EXPORT_FILENAME_SUFFIX = '.metadata.json';
+
+/**
+ * Minimal metadata row shape needed by import/export helpers.
+ */
+type MetadataConfigurationRow = Pick<
+    AgentsServerDatabase['public']['Tables']['Metadata']['Row'],
+    'key' | 'value' | 'note'
+>;
+
+/**
+ * Metadata row persisted during import.
+ */
+type MetadataConfigurationImportRow = {
+    /**
+     * Metadata key.
+     */
+    readonly key: string;
+
+    /**
+     * Metadata value to persist.
+     */
+    readonly value: string;
+
+    /**
+     * Metadata note to persist.
+     */
+    readonly note: string | null;
+};
+
+/**
+ * One entry inside the standalone metadata export JSON.
+ */
+export type MetadataConfigurationExportEntry = {
+    /**
+     * Metadata key.
+     */
+    readonly key: string;
+
+    /**
+     * Metadata value, omitted when it matches the built-in default.
+     */
+    readonly value?: string;
+
+    /**
+     * Metadata note, omitted when it matches the built-in default note.
+     */
+    readonly note?: string | null;
+};
+
+/**
+ * Standalone metadata export JSON payload.
+ */
+export type MetadataConfigurationExportPayload = {
+    /**
+     * Promptbook engine version that generated the export.
+     */
+    readonly promptbookVersion: string_promptbook_version;
+
+    /**
+     * Metadata entries with default fields omitted.
+     */
+    readonly metadata: ReadonlyArray<MetadataConfigurationExportEntry>;
+};
+
+/**
+ * Prepared metadata import plan before it touches the database.
+ */
+export type MetadataConfigurationImportPlan = {
+    /**
+     * Rows that should be inserted or updated.
+     */
+    readonly rowsToUpsert: ReadonlyArray<MetadataConfigurationImportRow>;
+
+    /**
+     * Default-backed keys absent from the import and therefore reset by deleting persisted rows.
+     */
+    readonly defaultKeysToReset: ReadonlyArray<string>;
+};
+
+/**
+ * Summary returned after importing metadata.
+ */
+export type MetadataConfigurationImportSummary = {
+    /**
+     * Number of metadata rows inserted or updated from the import file.
+     */
+    readonly importedCount: number;
+
+    /**
+     * Number of built-in metadata keys reset to default.
+     */
+    readonly resetCount: number;
+};
+
+/**
+ * Full metadata export result used by the API route.
+ */
+export type MetadataConfigurationExportResult = {
+    /**
+     * Browser download filename.
+     */
+    readonly filename: string;
+
+    /**
+     * JSON payload to send to the browser.
+     */
+    readonly payload: MetadataConfigurationExportPayload;
+};
+
+/**
+ * Creates a standalone metadata export from the current server database.
+ *
+ * @returns Export filename and payload.
+ */
+export async function createMetadataConfigurationExport(): Promise<MetadataConfigurationExportResult> {
+    const metadataRows = await loadMetadataConfigurationRows();
+    const serverName = resolveServerNameFromMetadataRows(metadataRows);
+
+    return {
+        filename: createMetadataConfigurationExportFilename(serverName),
+        payload: createMetadataConfigurationExportPayload(metadataRows),
+    };
+}
+
+/**
+ * Imports standalone metadata JSON into the current server database.
+ *
+ * @param payload - Parsed JSON import payload.
+ * @returns Import summary for the UI.
+ */
+export async function importMetadataConfigurationPayload(
+    payload: unknown,
+): Promise<MetadataConfigurationImportSummary> {
+    const importPlan = createMetadataConfigurationImportPlan(payload);
+    const supabase = $provideSupabaseForServer();
+    const tableName = await $getTableName('Metadata');
+    const nowIso = new Date().toISOString();
+
+    if (importPlan.defaultKeysToReset.length > 0) {
+        const { error } = await supabase.from(tableName).delete().in('key', [...importPlan.defaultKeysToReset]);
+
+        if (error) {
+            throw new DatabaseError(
+                spaceTrim(`
+                    Failed to reset metadata keys to their defaults.
+
+                    ${error.message}
+                `),
+            );
+        }
+    }
+
+    if (importPlan.rowsToUpsert.length > 0) {
+        const { error } = await supabase.from(tableName).upsert(
+            importPlan.rowsToUpsert.map((row) => ({
+                ...row,
+                updatedAt: nowIso,
+            })),
+            {
+                onConflict: 'key',
+            },
+        );
+
+        if (error) {
+            throw new DatabaseError(
+                spaceTrim(`
+                    Failed to import metadata configuration.
+
+                    ${error.message}
+                `),
+            );
+        }
+    }
+
+    invalidateMetadataCache();
+
+    return {
+        importedCount: importPlan.rowsToUpsert.length,
+        resetCount: importPlan.defaultKeysToReset.length,
+    };
+}
+
+/**
+ * Creates the standalone export payload from metadata rows.
+ *
+ * @param metadataRows - Persisted metadata rows.
+ * @param promptbookVersion - Promptbook version to include in the export.
+ * @returns JSON payload with default fields omitted.
+ */
+export function createMetadataConfigurationExportPayload(
+    metadataRows: ReadonlyArray<MetadataConfigurationRow>,
+    promptbookVersion: string_promptbook_version = PROMPTBOOK_ENGINE_VERSION,
+): MetadataConfigurationExportPayload {
+    const metadata = metadataRows
+        .flatMap((metadataRow) => {
+            const exportEntry = createMetadataConfigurationExportEntry(metadataRow);
+            return exportEntry ? [exportEntry] : [];
+        })
+        .sort((leftEntry, rightEntry) => leftEntry.key.localeCompare(rightEntry.key));
+
+    return {
+        promptbookVersion,
+        metadata,
+    };
+}
+
+/**
+ * Creates a browser-safe metadata export filename from the server name.
+ *
+ * @param serverName - Human-readable server name.
+ * @returns Kebab-case metadata export filename.
+ */
+export function createMetadataConfigurationExportFilename(serverName: string | null | undefined): string {
+    const normalizedServerName = normalizeToKebabCase(removeEmojis(serverName || ''));
+    const filenameStem = normalizedServerName || DEFAULT_METADATA_EXPORT_FILENAME_STEM;
+
+    return `${filenameStem}${METADATA_EXPORT_FILENAME_SUFFIX}`;
+}
+
+/**
+ * Validates and normalizes a standalone metadata import payload.
+ *
+ * @param payload - Parsed JSON import payload.
+ * @returns Import plan ready for persistence.
+ */
+export function createMetadataConfigurationImportPlan(payload: unknown): MetadataConfigurationImportPlan {
+    if (!payload || typeof payload !== 'object') {
+        throw new ParseError('Metadata import must be a JSON object.');
+    }
+
+    const payloadRecord = payload as Record<string, unknown>;
+
+    if (typeof payloadRecord.promptbookVersion !== 'string' || payloadRecord.promptbookVersion.trim() === '') {
+        throw new ParseError('Metadata import is missing `promptbookVersion`.');
+    }
+
+    if (!Array.isArray(payloadRecord.metadata)) {
+        throw new ParseError('Metadata import must contain a `metadata` array.');
+    }
+
+    const importedMetadataKeys = new Set<string>();
+    const rowsToUpsert = payloadRecord.metadata.map((rawMetadataEntry, index) =>
+        normalizeMetadataConfigurationImportEntry(rawMetadataEntry, index, importedMetadataKeys),
+    );
+    const defaultKeysToReset = metadataDefaults
+        .map((metadataDefinition) => metadataDefinition.key)
+        .filter((metadataKey) => !importedMetadataKeys.has(metadataKey))
+        .sort((leftKey, rightKey) => leftKey.localeCompare(rightKey));
+
+    return {
+        rowsToUpsert: rowsToUpsert.sort((leftRow, rightRow) => leftRow.key.localeCompare(rightRow.key)),
+        defaultKeysToReset,
+    };
+}
+
+/**
+ * Loads all persisted metadata rows from the current server database.
+ *
+ * @returns Metadata rows sorted by key.
+ */
+async function loadMetadataConfigurationRows(): Promise<Array<MetadataConfigurationRow>> {
+    const supabase = $provideSupabaseForServer();
+    const tableName = await $getTableName('Metadata');
+    const { data, error } = await supabase.from(tableName).select('key, value, note').order('key');
+
+    if (error) {
+        throw new DatabaseError(
+            spaceTrim(`
+                Failed to load metadata configuration.
+
+                ${error.message}
+            `),
+        );
+    }
+
+    return ((data ?? []) as Array<MetadataConfigurationRow>).sort((leftRow, rightRow) =>
+        leftRow.key.localeCompare(rightRow.key),
+    );
+}
+
+/**
+ * Creates one export entry while omitting fields that match defaults.
+ *
+ * @param metadataRow - Persisted metadata row.
+ * @returns Export entry or `null` when both value and note are default.
+ */
+function createMetadataConfigurationExportEntry(
+    metadataRow: MetadataConfigurationRow,
+): MetadataConfigurationExportEntry | null {
+    const metadataDefinition = getMetadataDefinition(metadataRow.key);
+    const defaultNote = metadataDefinition?.note ?? null;
+    const isValueDefault = Boolean(metadataDefinition) && metadataRow.value === metadataDefinition!.value;
+    const isNoteDefault = metadataRow.note === defaultNote;
+    const exportEntry: MetadataConfigurationExportEntry = {
+        key: metadataRow.key,
+    };
+
+    if (!isValueDefault) {
+        (exportEntry as { value: string }).value = metadataRow.value;
+    }
+
+    if (!isNoteDefault) {
+        (exportEntry as { note: string | null }).note = metadataRow.note;
+    }
+
+    const isValueExported = Object.prototype.hasOwnProperty.call(exportEntry, 'value');
+    const isNoteExported = Object.prototype.hasOwnProperty.call(exportEntry, 'note');
+
+    if (!isValueExported && !isNoteExported) {
+        return null;
+    }
+
+    return exportEntry;
+}
+
+/**
+ * Normalizes one metadata import entry.
+ *
+ * @param rawMetadataEntry - Untrusted entry from the import JSON.
+ * @param index - Zero-based entry index for error messages.
+ * @param importedMetadataKeys - Mutable set used to reject duplicates and compute resets.
+ * @returns Metadata row ready for persistence.
+ */
+function normalizeMetadataConfigurationImportEntry(
+    rawMetadataEntry: unknown,
+    index: number,
+    importedMetadataKeys: Set<string>,
+): MetadataConfigurationImportRow {
+    if (!rawMetadataEntry || typeof rawMetadataEntry !== 'object') {
+        throw new ParseError(`Metadata entry #${index + 1} must be an object.`);
+    }
+
+    const rawMetadataEntryRecord = rawMetadataEntry as Record<string, unknown>;
+    const rawKey = rawMetadataEntryRecord.key;
+    if (typeof rawKey !== 'string' || rawKey.trim() === '') {
+        throw new ParseError(`Metadata entry #${index + 1} is missing a non-empty \`key\`.`);
+    }
+
+    const key = rawKey.trim();
+    const isDuplicateKey = importedMetadataKeys.has(key);
+    if (isDuplicateKey) {
+        throw new ParseError(`Metadata import contains duplicate key \`${key}\`.`);
+    }
+    importedMetadataKeys.add(key);
+
+    const metadataDefinition = getMetadataDefinition(key);
+    const isValueProvided = Object.prototype.hasOwnProperty.call(rawMetadataEntryRecord, 'value');
+    const isNoteProvided = Object.prototype.hasOwnProperty.call(rawMetadataEntryRecord, 'note');
+
+    if (isValueProvided && typeof rawMetadataEntryRecord.value !== 'string') {
+        throw new ParseError(`Metadata entry \`${key}\` has invalid \`value\`; expected a string.`);
+    }
+
+    if (
+        isNoteProvided &&
+        typeof rawMetadataEntryRecord.note !== 'string' &&
+        rawMetadataEntryRecord.note !== null
+    ) {
+        throw new ParseError(`Metadata entry \`${key}\` has invalid \`note\`; expected a string or null.`);
+    }
+
+    if (!isValueProvided && !metadataDefinition) {
+        throw new ParseError(
+            spaceTrim(`
+                Metadata entry \`${key}\` is missing \`value\`.
+
+                Only built-in metadata keys can omit default values.
+            `),
+        );
+    }
+
+    const value = isValueProvided ? (rawMetadataEntryRecord.value as string) : metadataDefinition!.value;
+    const note = isNoteProvided
+        ? (rawMetadataEntryRecord.note as string | null)
+        : metadataDefinition?.note ?? null;
+    const validationError = validateMetadataValue(key, value);
+
+    if (validationError) {
+        throw new ParseError(validationError);
+    }
+
+    return {
+        key,
+        value,
+        note,
+    };
+}
+
+/**
+ * Resolves server name for the export filename from persisted metadata or defaults.
+ *
+ * @param metadataRows - Persisted metadata rows.
+ * @returns Server name candidate.
+ */
+function resolveServerNameFromMetadataRows(metadataRows: ReadonlyArray<MetadataConfigurationRow>): string {
+    const metadataRow = metadataRows.find((candidateRow) => candidateRow.key === SERVER_NAME_METADATA_KEY);
+    const defaultServerName = getMetadataDefinition(SERVER_NAME_METADATA_KEY)?.value ?? DEFAULT_METADATA_EXPORT_FILENAME_STEM;
+
+    return metadataRow?.value.trim() || defaultServerName;
+}