@promptbook/cli 0.112.0-138 → 0.112.0-140

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

@@ -1,7 +1,9 @@
+import { ParseError } from '@promptbook-local/core';
 import JSZip from 'jszip';
 import { $getTableName } from '../../database/$getTableName';
 import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
 import type { AgentsServerDatabase } from '../../database/schema';
+import { buildFolderTree, collectDescendantFolderIds } from '../agentOrganization/folderTree';
 import { sanitizeBackupPathSegment } from './sanitizeBackupPathSegment';
 
 /**
@@ -96,6 +98,18 @@ export type BooksBackupZipStream = {
     readonly stream: NodeJS.ReadableStream;
 };
 
+/**
+ * Options for appending book entries into an existing ZIP archive.
+ */
+export type AppendBooksBackupEntriesToZipOptions = {
+    /**
+     * Optional folder id used as the export root.
+     *
+     * When provided, only agents from this folder and its descendants are exported, with paths relative to this folder.
+     */
+    readonly rootFolderId?: number;
+};
+
 /**
  * Appends all exported books into a target ZIP folder while preserving the Agents Server folder tree.
  *
@@ -104,8 +118,13 @@ export type BooksBackupZipStream = {
  *
  * @param zip - ZIP archive being assembled.
  * @param archiveRootPath - ZIP folder path where books should be written.
+ * @param options - Optional folder scope for the exported books.
  */
-export async function appendBooksBackupEntriesToZip(zip: JSZip, archiveRootPath: string): Promise<void> {
+export async function appendBooksBackupEntriesToZip(
+    zip: JSZip,
+    archiveRootPath: string,
+    options: AppendBooksBackupEntriesToZipOptions = {},
+): Promise<void> {
     const supabase = $provideSupabaseForServer();
     const agentTable = await $getTableName('Agent');
     const folderTable = await $getTableName('AgentFolder');
@@ -125,8 +144,11 @@ export async function appendBooksBackupEntriesToZip(zip: JSZip, archiveRootPath:
 
     const agents = (agentsResult.data || []) as BackupAgentRow[];
     const folders = (foldersResult.data || []) as BackupFolderRow[];
+    const agentsForExport =
+        options.rootFolderId === undefined ? agents : filterAgentsByRootFolder(agents, folders, options.rootFolderId);
     const folderSegmentById = buildFolderSegmentById(folders);
     const resolveFolderPath = createFolderPathResolver(folders, folderSegmentById);
+    const resolveArchiveFolderPath = createArchiveFolderPathResolver(resolveFolderPath, options.rootFolderId);
 
     // Keep the root directory explicit even when there are no agents.
     if (archiveRootPath) {
@@ -136,12 +158,12 @@ export async function appendBooksBackupEntriesToZip(zip: JSZip, archiveRootPath:
     const relativeFilePaths = new Set<string>();
     const folderPathByAgentId = new Map<number, string>();
 
-    for (const agent of agents) {
-        const folderPath = resolveFolderPath(agent.folderId ?? null).join('/');
+    for (const agent of agentsForExport) {
+        const folderPath = resolveArchiveFolderPath(agent.folderId ?? null).join('/');
         folderPathByAgentId.set(agent.id, folderPath);
     }
 
-    const sortedAgents = [...agents].sort((left, right) =>
+    const sortedAgents = [...agentsForExport].sort((left, right) =>
         compareAgents(
             left,
             right,
@@ -151,7 +173,7 @@ export async function appendBooksBackupEntriesToZip(zip: JSZip, archiveRootPath:
     );
 
     for (const agent of sortedAgents) {
-        const folderSegments = resolveFolderPath(agent.folderId ?? null);
+        const folderSegments = resolveArchiveFolderPath(agent.folderId ?? null);
         const initialBookFilename = createInitialBookFilename(agent);
         const relativePath = createUniqueBookRelativePath(relativeFilePaths, folderSegments, initialBookFilename, agent.id);
         zip.file(createArchivePath(archiveRootPath, relativePath), agent.agentSource || '');
@@ -169,6 +191,55 @@ function createArchivePath(archiveRootPath: string, relativePath: string): strin
     return archiveRootPath ? `${archiveRootPath}/${relativePath}` : relativePath;
 }
 
+/**
+ * Filters agents to a selected folder subtree.
+ *
+ * @param agents - All loaded agent rows.
+ * @param folders - All loaded folder rows.
+ * @param rootFolderId - Folder id selected as the export root.
+ * @returns Agents assigned to the root folder or its descendant folders.
+ */
+function filterAgentsByRootFolder(
+    agents: ReadonlyArray<BackupAgentRow>,
+    folders: ReadonlyArray<BackupFolderRow>,
+    rootFolderId: number,
+): BackupAgentRow[] {
+    const { folderById, childrenByParentId } = buildFolderTree([...folders]);
+    if (!folderById.has(rootFolderId)) {
+        throw new ParseError(`Folder \`${rootFolderId}\` was not found.`);
+    }
+
+    const scopedFolderIds = new Set(collectDescendantFolderIds(rootFolderId, childrenByParentId));
+
+    return agents.filter((agent) => agent.folderId !== null && scopedFolderIds.has(agent.folderId));
+}
+
+/**
+ * Creates a path resolver for full exports or folder-relative exports.
+ *
+ * @param resolveFolderPath - Full folder-path resolver.
+ * @param rootFolderId - Optional folder id selected as the export root.
+ * @returns Folder-path resolver for archive entry paths.
+ */
+function createArchiveFolderPathResolver(
+    resolveFolderPath: (folderId: number | null) => string[],
+    rootFolderId: number | undefined,
+): (folderId: number | null) => string[] {
+    if (rootFolderId === undefined) {
+        return resolveFolderPath;
+    }
+
+    const rootFolderPath = resolveFolderPath(rootFolderId);
+
+    return (folderId: number | null): string[] => {
+        if (folderId === null) {
+            return [];
+        }
+
+        return resolveFolderPath(folderId).slice(rootFolderPath.length);
+    };
+}
+
 /**
  * Builds a download-ready stream with all books organized by the Agents Server folder tree.
  *

package/apps/agents-server/src/utils/chatExport/renderHtmlToPdfOnServer.ts

@@ -1,6 +1,12 @@
 import { createServerChromiumLaunchOptions } from '@/src/tools/createServerChromiumLaunchOptions';
 import { chromium } from 'playwright';
 
+/**
+ * URL protocols that can be allowed through the PDF renderer request
+ * interception because they cannot reach a server-side network destination.
+ */
+const CHAT_EXPORT_PDF_ALLOWED_REQUEST_PROTOCOLS = new Set(['about:', 'data:']);
+
 /**
  * Browser viewport used while rendering standalone HTML exports to PDF.
  */
@@ -32,6 +38,16 @@ export async function renderHtmlToPdfOnServer(html: string): Promise<Buffer> {
         const page = await browser.newPage();
 
         try {
+            await page.route('**/*', async (route) => {
+                const requestUrl = route.request().url();
+
+                if (isAllowedPdfRendererRequestUrl(requestUrl)) {
+                    await route.continue();
+                    return;
+                }
+
+                await route.abort('blockedbyclient');
+            });
             await page.setViewportSize(CHAT_EXPORT_PDF_VIEWPORT);
             await page.emulateMedia({ media: 'print' });
             await page.setContent(html, { waitUntil: 'load' });
@@ -52,3 +68,19 @@ export async function renderHtmlToPdfOnServer(html: string): Promise<Buffer> {
         await browser.close();
     }
 }
+
+/**
+ * Returns whether a Playwright request can proceed while rendering a chat export PDF.
+ *
+ * @param requestUrl - URL reported by Playwright for one intercepted request.
+ * @returns Whether the request cannot reach an external or internal network host.
+ *
+ * @private internal helper of `renderHtmlToPdfOnServer`
+ */
+function isAllowedPdfRendererRequestUrl(requestUrl: string): boolean {
+    try {
+        return CHAT_EXPORT_PDF_ALLOWED_REQUEST_PROTOCOLS.has(new URL(requestUrl).protocol);
+    } catch {
+        return false;
+    }
+}

package/apps/agents-server/src/utils/chatExport/sanitizeChatPdfExportHtml.ts

@@ -0,0 +1,193 @@
+import { JSDOM } from 'jsdom';
+import { assertSafeUrl } from '../assertSafeUrl';
+
+/**
+ * URL-bearing HTML attributes that can appear in standalone chat export markup.
+ *
+ * @private internal constant of chat PDF export sanitization
+ */
+const CHAT_PDF_EXPORT_URL_ATTRIBUTE_NAMES = new Set(['href', 'poster', 'src', 'xlink:href']);
+
+/**
+ * Protocols that cannot make the PDF renderer issue server-side network requests.
+ *
+ * @private internal constant of chat PDF export sanitization
+ */
+const CHAT_PDF_EXPORT_NON_NETWORK_PROTOCOLS = new Set(['about:', 'data:']);
+
+/**
+ * Link-only protocols that are safe to keep on anchors because Playwright does not fetch them while rendering.
+ *
+ * @private internal constant of chat PDF export sanitization
+ */
+const CHAT_PDF_EXPORT_LINK_ONLY_PROTOCOLS = new Set(['mailto:', 'tel:']);
+
+/**
+ * Matches CSS `url(...)` values inside inline styles and style blocks.
+ *
+ * @private internal constant of chat PDF export sanitization
+ */
+const CHAT_PDF_EXPORT_CSS_URL_FUNCTION_REGEX = /url\(\s*(['"]?)(.*?)\1\s*\)/gi;
+
+/**
+ * Parses the generated standalone chat export HTML and removes URL attributes
+ * that would let Chromium reach private or unsupported destinations while
+ * rendering the PDF.
+ *
+ * Markdown message bodies are already sanitized by the shared `renderMarkdown`
+ * DOMPurify pipeline; this pass covers structured export URLs such as avatars,
+ * citations, attachments, and markdown image `src` attributes after HTML
+ * generation.
+ *
+ * @param html - Standalone chat export HTML generated by `buildChatHtml`.
+ * @returns HTML safe to pass into the server-side PDF renderer.
+ *
+ * @private internal utility of the Agents Server chat PDF export route
+ */
+export function sanitizeChatPdfExportHtml(html: string): string {
+    const dom = new JSDOM(html);
+    const { document } = dom.window;
+
+    for (const element of Array.from(document.querySelectorAll('*'))) {
+        sanitizeChatPdfExportElementUrlAttributes(element);
+        sanitizeChatPdfExportStyleAttribute(element);
+    }
+
+    for (const styleElement of Array.from(document.querySelectorAll('style'))) {
+        styleElement.textContent = sanitizeChatPdfExportCssUrls(styleElement.textContent || '');
+    }
+
+    return dom.serialize();
+}
+
+/**
+ * Removes unsafe URL attributes from one element.
+ *
+ * @param element - HTML element to sanitize.
+ *
+ * @private internal helper of `sanitizeChatPdfExportHtml`
+ */
+function sanitizeChatPdfExportElementUrlAttributes(element: Element): void {
+    for (const attributeName of element.getAttributeNames()) {
+        const normalizedAttributeName = attributeName.toLowerCase();
+
+        if (!CHAT_PDF_EXPORT_URL_ATTRIBUTE_NAMES.has(normalizedAttributeName)) {
+            continue;
+        }
+
+        const attributeValue = element.getAttribute(attributeName);
+
+        if (
+            attributeValue !== null &&
+            !isSafeChatPdfExportUrl(attributeValue, isChatPdfExportNetworkRequestAttribute(element, attributeName))
+        ) {
+            element.removeAttribute(attributeName);
+        }
+    }
+}
+
+/**
+ * Removes unsafe CSS `url(...)` values from one inline style attribute.
+ *
+ * @param element - HTML element whose style attribute should be sanitized.
+ *
+ * @private internal helper of `sanitizeChatPdfExportHtml`
+ */
+function sanitizeChatPdfExportStyleAttribute(element: Element): void {
+    const styleValue = element.getAttribute('style');
+
+    if (styleValue === null) {
+        return;
+    }
+
+    element.setAttribute('style', sanitizeChatPdfExportCssUrls(styleValue));
+}
+
+/**
+ * Replaces unsafe CSS `url(...)` functions with `none` so Chromium has no
+ * private/internal resource to request while keeping unrelated inline styles.
+ *
+ * @param cssValue - CSS text from a style attribute or style element.
+ * @returns CSS text without unsafe URL functions.
+ *
+ * @private internal helper of `sanitizeChatPdfExportHtml`
+ */
+function sanitizeChatPdfExportCssUrls(cssValue: string): string {
+    return cssValue.replace(CHAT_PDF_EXPORT_CSS_URL_FUNCTION_REGEX, (rawMatch: string, _quote: string, url: string) => {
+        if (isSafeChatPdfExportUrl(url, true)) {
+            return rawMatch;
+        }
+
+        return 'none';
+    });
+}
+
+/**
+ * Returns whether an attribute value can be kept in the PDF-rendered HTML.
+ *
+ * Absolute HTTP(S) URLs are checked through the Agents Server SSRF guard.
+ * Relative resource URLs are removed because server-side rendering has no
+ * trusted origin for them, while relative anchor links remain useful inside the
+ * PDF table of sources.
+ *
+ * @param rawUrl - Raw attribute or CSS URL value.
+ * @param isNetworkRequestAttribute - Whether Chromium could fetch this value during rendering.
+ * @returns Whether the URL value is safe to keep.
+ *
+ * @private internal helper of `sanitizeChatPdfExportHtml`
+ */
+function isSafeChatPdfExportUrl(rawUrl: string, isNetworkRequestAttribute: boolean): boolean {
+    const trimmedUrl = rawUrl.trim();
+
+    if (trimmedUrl === '' || trimmedUrl.startsWith('#')) {
+        return true;
+    }
+
+    const absoluteUrl = trimmedUrl.startsWith('//') ? `https:${trimmedUrl}` : trimmedUrl;
+    let parsedUrl: URL;
+    try {
+        parsedUrl = new URL(absoluteUrl);
+    } catch {
+        return !isNetworkRequestAttribute;
+    }
+
+    if (parsedUrl.protocol === 'http:' || parsedUrl.protocol === 'https:') {
+        try {
+            assertSafeUrl(absoluteUrl);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    if (CHAT_PDF_EXPORT_NON_NETWORK_PROTOCOLS.has(parsedUrl.protocol)) {
+        return true;
+    }
+
+    return !isNetworkRequestAttribute && CHAT_PDF_EXPORT_LINK_ONLY_PROTOCOLS.has(parsedUrl.protocol);
+}
+
+/**
+ * Returns whether one URL attribute can trigger a network request during PDF rendering.
+ *
+ * @param element - Element that owns the attribute.
+ * @param attributeName - URL-bearing attribute name.
+ * @returns Whether Chromium may fetch the attribute while rendering.
+ *
+ * @private internal helper of `sanitizeChatPdfExportHtml`
+ */
+function isChatPdfExportNetworkRequestAttribute(element: Element, attributeName: string): boolean {
+    const normalizedAttributeName = attributeName.toLowerCase();
+
+    if (normalizedAttributeName === 'src' || normalizedAttributeName === 'poster') {
+        return true;
+    }
+
+    if (normalizedAttributeName === 'xlink:href') {
+        return true;
+    }
+
+    return normalizedAttributeName === 'href' && element.tagName.toLowerCase() !== 'a';
+}
+
+// Note: [🟢] Code for Agents Server chat PDF export sanitization should never be published into packages that could be imported into browser environment

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

@@ -16,15 +16,20 @@ const GENERATED_USER_PASSWORD_HASH_PLACEHOLDER = 'auto-generated-user';
 const ENV_ADMIN_PASSWORD_HASH_PLACEHOLDER = 'env-admin-managed';
 
 /**
- * Database row shape for the `User` table.
+ * User row shape needed for request identity resolution.
  */
-type UserRow = AgentsServerDatabase['public']['Tables']['User']['Row'];
+type UserIdentityRow = Pick<AgentsServerDatabase['public']['Tables']['User']['Row'], 'id' | 'username' | 'isAdmin'>;
 
 /**
  * Database insert shape for the `User` table.
  */
 type UserInsert = AgentsServerDatabase['public']['Tables']['User']['Insert'];
 
+/**
+ * Supabase projection for user fields needed by request identity resolution.
+ */
+const USER_IDENTITY_SELECT_COLUMNS = 'id, username, isAdmin';
+
 /**
  * Identity resolved for the current request, including database user id.
  */
@@ -109,7 +114,11 @@ export async function ensureChatHistoryIdentity(): Promise<boolean> {
 /**
  * Attempts to find an existing user row by username and creates one when missing.
  */
-async function findOrCreateUserRow(username: string, isAdmin: boolean, passwordHash: string): Promise<UserRow> {
+async function findOrCreateUserRow(
+    username: string,
+    isAdmin: boolean,
+    passwordHash: string,
+): Promise<UserIdentityRow> {
     const existing = await findUserRowByUsername(username);
     if (existing) {
         return existing;
@@ -154,22 +163,26 @@ function isDuplicateUsernameCreateError(error: unknown): boolean {
 /**
  * Finds one user row by its username.
  */
-async function findUserRowByUsername(username: string): Promise<UserRow | null> {
+async function findUserRowByUsername(username: string): Promise<UserIdentityRow | null> {
     const supabase = $provideSupabaseForServer();
     const tableName = await $getTableName('User');
-    const { data, error } = await supabase.from(tableName).select('*').eq('username', username).maybeSingle();
+    const { data, error } = await supabase
+        .from(tableName)
+        .select(USER_IDENTITY_SELECT_COLUMNS)
+        .eq('username', username)
+        .maybeSingle();
 
     if (error) {
         throw new Error(`Failed to resolve user "${username}": ${error.message}`);
     }
 
-    return (data as UserRow | null) || null;
+    return (data as UserIdentityRow | null) || null;
 }
 
 /**
  * Inserts a new user row for the provided username.
  */
-async function insertUserRow(payload: UserInsert): Promise<UserRow> {
+async function insertUserRow(payload: UserInsert): Promise<UserIdentityRow> {
     const supabase = $provideSupabaseForServer();
     const tableName = await $getTableName('User');
     const now = new Date().toISOString();
@@ -180,7 +193,7 @@ async function insertUserRow(payload: UserInsert): Promise<UserRow> {
             createdAt: payload.createdAt ?? now,
             updatedAt: payload.updatedAt ?? now,
         })
-        .select('*')
+        .select(USER_IDENTITY_SELECT_COLUMNS)
         .maybeSingle();
 
     if (error) {
@@ -195,5 +208,5 @@ async function insertUserRow(payload: UserInsert): Promise<UserRow> {
         throw new Error(`Failed to insert user "${payload.username}".`);
     }
 
-    return data as UserRow;
+    return data as UserIdentityRow;
 }

package/apps/agents-server/src/utils/externalChatRunner/processExternalUserChatJob.ts

@@ -7,6 +7,7 @@ import { getUserChat } from '../userChat/getUserChat';
 import { getUserChatJobById } from '../userChat/getUserChatJobById';
 import { persistUserChatJobTerminalState } from '../userChat/persistUserChatJobTerminalState';
 import { provideUserChatJobTable } from '../userChat/provideUserChatJobTable';
+import { createUserChatRunnerProgressCard } from '../userChat/createUserChatRunnerProgressCard';
 import { updateUserChatAssistantMessage } from '../userChat/updateUserChatAssistantMessage';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { UserChatJobRow } from '../userChat/UserChatJobRow';
@@ -196,6 +197,10 @@ async function enqueueExternalUserChatJob(job: UserChatJobRecord): Promise<Proce
             isComplete: false,
             lifecycleState: 'running',
             lifecycleError: undefined,
+            progressCard: createUserChatRunnerProgressCard({
+                runnerKind: 'external',
+                phase: 'queued_for_runner',
+            }),
         }),
     });
 

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

@@ -3,21 +3,35 @@ import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForSer
 import type { AgentsServerDatabase } from '@/src/database/schema';
 
 /**
- * Database row shape for `User`.
+ * User row shape needed by durable chat execution.
  */
-type UserRow = AgentsServerDatabase['public']['Tables']['User']['Row'];
+type UserByIdRow = Pick<
+    AgentsServerDatabase['public']['Tables']['User']['Row'],
+    'id' | 'username' | 'isAdmin' | 'profileImageUrl'
+>;
+
+/**
+ * Supabase projection for user fields needed by durable chat execution.
+ */
+const USER_BY_ID_SELECT_COLUMNS = 'id, username, isAdmin, profileImageUrl';
 
 /**
  * Loads one user row by database id.
+ *
+ * @private internal Agents Server user lookup helper
  */
-export async function getUserById(userId: number): Promise<UserRow | null> {
+export async function getUserById(userId: number): Promise<UserByIdRow | null> {
     const supabase = $provideSupabaseForServer();
     const tableName = await $getTableName('User');
-    const { data, error } = await supabase.from(tableName).select('*').eq('id', userId).maybeSingle();
+    const { data, error } = await supabase
+        .from(tableName)
+        .select(USER_BY_ID_SELECT_COLUMNS)
+        .eq('id', userId)
+        .maybeSingle();
 
     if (error) {
         throw new Error(`Failed to resolve user "${userId}": ${error.message}`);
     }
 
-    return (data as UserRow | null) || null;
+    return (data as UserByIdRow | null) || null;
 }

package/apps/agents-server/src/utils/localChatRunner/processLocalUserChatJob.ts

@@ -9,6 +9,7 @@ import { getUserChat } from '../userChat/getUserChat';
 import { getUserChatJobById } from '../userChat/getUserChatJobById';
 import { persistUserChatJobTerminalState } from '../userChat/persistUserChatJobTerminalState';
 import { provideUserChatJobTable } from '../userChat/provideUserChatJobTable';
+import { createUserChatRunnerProgressCard } from '../userChat/createUserChatRunnerProgressCard';
 import { updateUserChatAssistantMessage } from '../userChat/updateUserChatAssistantMessage';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { UserChatJobRow } from '../userChat/UserChatJobRow';
@@ -188,6 +189,10 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
             isComplete: false,
             lifecycleState: 'running',
             lifecycleError: undefined,
+            progressCard: createUserChatRunnerProgressCard({
+                runnerKind: 'local',
+                phase: 'queued_for_runner',
+            }),
         }),
     });
 

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

@@ -103,6 +103,16 @@ export type MetadataConfigurationImportPlan = {
     readonly defaultKeysToReset: ReadonlyArray<string>;
 };
 
+/**
+ * Options controlling standalone metadata import behavior.
+ */
+export type MetadataConfigurationImportPlanOptions = {
+    /**
+     * When true, built-in metadata keys missing from the import payload keep their current persisted value.
+     */
+    readonly isDefaultResetSkipped?: boolean;
+};
+
 /**
  * Summary returned after importing metadata.
  */
@@ -152,18 +162,23 @@ export async function createMetadataConfigurationExport(): Promise<MetadataConfi
  * Imports standalone metadata JSON into the current server database.
  *
  * @param payload - Parsed JSON import payload.
+ * @param options - Import behavior options.
  * @returns Import summary for the UI.
  */
 export async function importMetadataConfigurationPayload(
     payload: unknown,
+    options: MetadataConfigurationImportPlanOptions = {},
 ): Promise<MetadataConfigurationImportSummary> {
-    const importPlan = createMetadataConfigurationImportPlan(payload);
+    const importPlan = createMetadataConfigurationImportPlan(payload, options);
     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]);
+        const { error } = await supabase
+            .from(tableName)
+            .delete()
+            .in('key', [...importPlan.defaultKeysToReset]);
 
         if (error) {
             throw new DatabaseError(
@@ -247,9 +262,13 @@ export function createMetadataConfigurationExportFilename(serverName: string | n
  * Validates and normalizes a standalone metadata import payload.
  *
  * @param payload - Parsed JSON import payload.
+ * @param options - Import behavior options.
  * @returns Import plan ready for persistence.
  */
-export function createMetadataConfigurationImportPlan(payload: unknown): MetadataConfigurationImportPlan {
+export function createMetadataConfigurationImportPlan(
+    payload: unknown,
+    options: MetadataConfigurationImportPlanOptions = {},
+): MetadataConfigurationImportPlan {
     if (!payload || typeof payload !== 'object') {
         throw new ParseError('Metadata import must be a JSON object.');
     }
@@ -268,10 +287,12 @@ export function createMetadataConfigurationImportPlan(payload: unknown): Metadat
     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));
+    const defaultKeysToReset = options.isDefaultResetSkipped
+        ? []
+        : 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)),
@@ -377,11 +398,7 @@ function normalizeMetadataConfigurationImportEntry(
         throw new ParseError(`Metadata entry \`${key}\` has invalid \`value\`; expected a string.`);
     }
 
-    if (
-        isNoteProvided &&
-        typeof rawMetadataEntryRecord.note !== 'string' &&
-        rawMetadataEntryRecord.note !== null
-    ) {
+    if (isNoteProvided && typeof rawMetadataEntryRecord.note !== 'string' && rawMetadataEntryRecord.note !== null) {
         throw new ParseError(`Metadata entry \`${key}\` has invalid \`note\`; expected a string or null.`);
     }
 
@@ -396,9 +413,7 @@ function normalizeMetadataConfigurationImportEntry(
     }
 
     const value = isValueProvided ? (rawMetadataEntryRecord.value as string) : metadataDefinition!.value;
-    const note = isNoteProvided
-        ? (rawMetadataEntryRecord.note as string | null)
-        : metadataDefinition?.note ?? null;
+    const note = isNoteProvided ? (rawMetadataEntryRecord.note as string | null) : metadataDefinition?.note ?? null;
     const validationError = validateMetadataValue(key, value);
 
     if (validationError) {
@@ -420,7 +435,8 @@ function normalizeMetadataConfigurationImportEntry(
  */
 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;
+    const defaultServerName =
+        getMetadataDefinition(SERVER_NAME_METADATA_KEY)?.value ?? DEFAULT_METADATA_EXPORT_FILENAME_STEM;
 
     return metadataRow?.value.trim() || defaultServerName;
 }