Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

36.3 KB
Raw Blame
import { EDITOR_SETTINGS_DRAFT_KEYS, editorSettingsDraftFromSettings, type EditorSettingsDraftKey } from "./editorSettingsDraft";
import { DEFAULT_CUSTOM_THEME_COLORS, DEFAULT_CUSTOM_THEME_DDL_COLORS, DEFAULT_DESKTOP_SETTINGS, DEFAULT_EDITOR_SETTINGS, DEFAULT_TOOLBAR_ITEMS, normalizeDesktopSettings, normalizeEditorSettings, type DesktopSettings, type EditorSettings } from "@/stores/settingsStore";
import type { AppThemeMode } from "@/lib/app/appTheme";
import { EDITOR_MAX_FONT_SIZE, EDITOR_MIN_FONT_SIZE } from "@/lib/editor/editorZoom";
import { DATA_GRID_TYPE_COLOR_KEYS, DATA_GRID_TYPE_COLOR_SCHEME_AUTO_ID } from "@/lib/dataGrid/dataGridTypeColorScheme";
import { SHORTCUT_DEFINITIONS } from "@/lib/editor/shortcutRegistry";
import { DEFAULT_SQL_FORMATTER_RULE_SETTINGS, DEFAULT_SQL_FORMATTER_SETTINGS, isCompleteSqlFormatterSettings, type SqlFormatterOptionSettings, type SqlFormatterRuleSettings } from "@/lib/sql/sqlFormatterConfig";
import { SQL_VARIABLE_SYNTAX_KEYS } from "@/lib/sql/sqlVariableSyntax";

/**
 * Local backup / restore of application settings ("配置导入与导出").
 *
 * The transfer file is a versioned JSON document with a strict field
 * whitelist. The `settings.editor` section carries the dialog-managed editor
 * settings; the optional `settings.appearance` and `settings.desktop`
 * sections carry the app-wide theme mode and the preference-like desktop
 * settings. Connection data, saved SQL libraries, AI configuration and
 * device-specific paths are never part of the payload, and unknown fields in
 * an imported file are ignored instead of being written anywhere.
 */

export const SETTINGS_TRANSFER_FORMAT_VERSION = 1;

/** Upper bound for an import file; real settings files are a few dozen KB. */
export const MAX_SETTINGS_TRANSFER_FILE_BYTES = 5 * 1024 * 1024;

/**
 * Preference-like `DesktopSettings` keys eligible for transfer. Device-
 * specific paths (driver/plugin/agent/skill directories, saved-SQL sync dir)
 * and the one-shot `close_action_prompted` flag are deliberately excluded:
 * they are either meaningless on another machine or not a user preference.
 */
export const TRANSFERABLE_DESKTOP_SETTINGS_KEYS = [
  "show_tray_icon",
  "icon_theme",
  "quit_on_close",
  "debug_logging_enabled",
  "metadata_cache_max_memory_mb",
  "duckdb_worker_process_isolation",
  "duckdb_worker_max_processes",
  "sidebar_table_page_size",
] as const satisfies readonly (keyof DesktopSettings)[];

export type TransferableDesktopSettingsKey = (typeof TRANSFERABLE_DESKTOP_SETTINGS_KEYS)[number];

/** The transferable keys without their `null` "unset" variants. */
export type TransferableDesktopSettings = {
  [K in TransferableDesktopSettingsKey]: Exclude<DesktopSettings[K], null>;
};

/** Non-editor sections carried alongside the editor draft in the transfer file. */
export interface SettingsTransferExtras {
  /** App-wide light/dark/system mode from `settings.appearance`. */
  themeMode?: AppThemeMode;
  /** Preference-like desktop settings from `settings.desktop`. */
  desktopSettings?: Partial<TransferableDesktopSettings>;
}

/** Keeps only the whitelisted desktop keys, ignoring everything else. */
export function pickTransferableDesktopSettings(settings: Partial<DesktopSettings>): Partial<TransferableDesktopSettings> {
  const picked: Partial<TransferableDesktopSettings> = {};
  for (const key of TRANSFERABLE_DESKTOP_SETTINGS_KEYS) {
    const value = settings[key];
    if (value !== undefined && value !== null) picked[key] = value as never;
  }
  return picked;
}

export type SettingsTransferCategoryId = "appearance" | "editor" | "formatter" | "navigation" | "data" | "shortcuts" | "snippets" | "other";

export type SettingsTransferParseErrorCode = "too-large" | "invalid-json" | "unsupported-version" | "invalid-structure" | "empty-settings" | "invalid-fields";

export interface SettingsTransferParseError {
  code: SettingsTransferParseErrorCode;
  /** Offending format version, or the first invalid field names. */
  detail?: string;
}

export interface ParsedSettingsTransfer {
  formatVersion: number;
  appVersion?: string;
  exportedAt?: string;
  /** Validated, normalized values for exactly the keys present in the file. */
  editorSettings: Partial<EditorSettings>;
  /** Validated theme mode from the optional appearance section. */
  themeMode?: AppThemeMode;
  /** Validated desktop preferences for exactly the keys present in the file. */
  desktopSettings: Partial<TransferableDesktopSettings>;
  categories: SettingsTransferCategoryId[];
}

export interface SettingsTransferParseOptions {
  /**
   * Whether the platform-specific `settings.desktop` section applies. Web
   * callers pass false: those switches are desktop-only, so the section is
   * skipped the same way an older reader skips an unknown section — its
   * values are neither validated nor listed among the importable categories.
   */
  includeDesktopSettings?: boolean;
}

export interface SettingsTransferExportMeta {
  appVersion?: string;
}

export function buildSettingsTransferFilename(date = new Date()): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, "0");
  const day = String(date.getDate()).padStart(2, "0");
  return `dbx-settings-${year}-${month}-${day}.json`;
}

/**
 * Serializes the saved editor settings into the transfer format. The draft
 * helper provides the whitelist, deep cloning and per-key normalization, so
 * the payload never contains fields outside `EDITOR_SETTINGS_DRAFT_KEYS`.
 * The optional extras add the `appearance`/`desktop` sections; files written
 * by older versions simply lack them.
 */
export function serializeSettingsTransfer(settings: EditorSettings, meta: SettingsTransferExportMeta = {}, extras: SettingsTransferExtras = {}): string {
  const desktopSettings = extras.desktopSettings ? pickTransferableDesktopSettings(extras.desktopSettings) : {};
  const payload = {
    formatVersion: SETTINGS_TRANSFER_FORMAT_VERSION,
    app: { name: "dbx", ...(meta.appVersion ? { version: meta.appVersion } : {}) },
    exportedAt: new Date().toISOString(),
    settings: {
      editor: editorSettingsDraftFromSettings(settings),
      ...(extras.themeMode ? { appearance: { themeMode: extras.themeMode } } : {}),
      ...(Object.keys(desktopSettings).length > 0 ? { desktop: desktopSettings } : {}),
    },
  };
  return JSON.stringify(payload, null, 2);
}

const SETTINGS_TRANSFER_CATEGORY_ORDER: readonly SettingsTransferCategoryId[] = ["appearance", "editor", "formatter", "navigation", "data", "shortcuts", "snippets", "other"];

const SETTINGS_TRANSFER_CATEGORY_KEYS: Record<SettingsTransferCategoryId, readonly EditorSettingsDraftKey[]> = {
  appearance: ["fontFamily", "fontSize", "tableFontFamily", "uiFontFamily", "uiScale", "fontSmoothing", "theme", "customThemes", "activeCustomThemeId", "backgroundImage", "toolbarItems", "welcomePageMode", "webLogoPosition"],
  editor: [
    "executeMode",
    "defaultTransactionMode",
    "keepExplicitTransactionInAutoCommit",
    "executeAllOnBlankLine",
    "showExecutionTargetPicker",
    "showStatementRunButtons",
    "locateCursorOnGutterExecute",
    "showLineNumbers",
    "showCurrentStatementFrame",
    "showInsertValueHints",
    "showConnectionGroupPath",
    "autoAliasTables",
    "tableCompletionSchemaQualification",
    "insertSpaceAfterCompletion",
    "sqlServerSpaceConfirmsCompletion",
    "functionCompletionIncludeParams",
    "sequenceCompletionEnabled",
    "sortCompletionColumnsAlphabetically",
    "selectFirstCompletionOnOpen",
    "completionTriggerMode",
    "excludedCompletionItems",
    "wordWrap",
    "showWhitespace",
    "vimModeEnabled",
    "caretBrowsingEnabled",
    "doubleClickStringSelectionMode",
    "autoCloseBrackets",
    "restoreSqlFromSourcePasteEnabled",
    "sqlSemanticDiagnosticsMode",
    "confirmDangerousSqlExecution",
    "continueOnErrorOnBatch",
    "confirmUnsavedSqlClose",
    "appCloseUnsavedTabsMode",
    "savedSqlOpenTargetMode",
    "aiSqlApplyTargetMode",
    "prefillNewQueryWithSelect",
    "openQueryOnConnectionOpen",
    "generateSqlIncludeDatabaseName",
    "generateSqlQuoteIdentifiers",
    "formatSqlOnSqlFileSave",
    "ddlOpenMode",
    "showTableDdlHoverPreview",
    "tableHoverLookupMode",
    "sqlVariableSubstitutionEnabled",
    "sqlVariableSyntaxOverrides",
  ],
  formatter: ["sqlFormatter"],
  navigation: [
    "appLayout",
    "tabLayout",
    "tabPlacement",
    "tabGroupMode",
    "colorizeConnectionTabs",
    "colorizeConnectionTabsScope",
    "tabSortMode",
    "tabMaxWidth",
    "tabGroupRows",
    "sidebarActivation",
    "sidebarObjectDisplay",
    "routineSourceOpenMode",
    "sidebarTableSearchEnabled",
    "sidebarSearchOpenedDatabasesOnly",
    "autoSelectActiveSidebarNode",
    "sidebarPinDefaultDatabase",
    "sidebarBrowseObjectsOnDatabaseActivation",
    "openTabsRestoreMode",
    "autoReloadRestoredDataTabsOnOpen",
    "disconnectTabHandlingMode",
    "deleteConnectionTabHandlingMode",
    "rememberConnectionDatabaseOnDelete",
    "deepLinkConnectionConfirmMode",
    "dataTabReuseMode",
    "openDataTabsNextToActive",
    "openTablesInDetachedWindow",
    "clickTableNavigationTarget",
    "objectBrowserAutoOpenDetailPanel",
    "sidebarObjectInfoMode",
    "sidebarAllowHorizontalScroll",
    "sidebarShowTooltips",
    "sidebarIndent",
    "sidebarFontSize",
    "sidebarDensity",
    "sidebarHiddenTablePrefixes",
    "sidebarCopyTableNameSeparator",
    "sidebarCopyTableNameIncludeSchema",
  ],
  data: [
    "showColumnCommentsInHeader",
    "dataGridColumnCommentsInInfoArea",
    "showColumnTypesInHeader",
    "showColumnHeaderTooltips",
    "showResultSourceDatabase",
    "resultTabNamingMode",
    "resultTabPreferComments",
    "dataGridShowTransposeFieldMetadata",
    "dataGridTransposeMetadataInInfoColumn",
    "colorizeDataGridCellTypes",
    "dataGridTypeColorSchemes",
    "activeDataGridTypeColorSchemeId",
    "showIndexIndicatorsInHeader",
    "compactColumnHeaderActions",
    "dataGridQuickEntry",
    "dataGridFilterEditorView",
    "dataGridKeepFilterEditorExpanded",
    "dataGridTextFilterPanelHeight",
    "dataGridToolbarLayout",
    "defaultAutoKeepResults",
    "pinResultTabOnClick",
    "multiStatementDefaultView",
    "defaultExplainView",
    "dataGridAutoTransposeSingleRow",
    "dataGridCellDetailButtonVisible",
    "dataGridCellDetailDialogDefault",
    "dataGridCrosshairHighlight",
    "dataGridCrosshairRowBg",
    "dataGridCrosshairColBg",
    "dataGridStripedRows",
    "dataGridZebraRowBg",
    "flatteningMultiLineText",
    "dataGridShowWhitespace",
    "pageSize",
    "tableOpenPageSize",
    "tableOpenSortMode",
    "tableDatabaseSortDirection",
    "tableLocalSortDirection",
    "queryResultMaxRowsEnabled",
    "queryResultMaxRows",
    "externalSqlEditorMaxMb",
    "infiniteScroll",
    "regexMaxMatchCount",
    "autoCalculateTotalRows",
    "modelGenerationTemplates",
    "tableColumnTemplateFields",
    "redisKeyTemplates",
    "redisDatabaseDisplayLimit",
    "exportBatchSize",
    "preferredExportPath",
    "damengClientBinDir",
    "autoOpenExportFolder",
    "applyColumnFormattersOnExport",
    "csvQuoteMode",
    "csvNullMode",
    "queryResultExportFileNameSource",
    "exportRowLimitEnabled",
    "exportRowLimit",
    "queryExportKeysetOptimizationEnabled",
    "globalDateTimeDisplayFormat",
    "globalDateTimeExportFormat",
    "globalDateTimeImportFormat",
    "globalConnectTimeoutSecs",
    "globalQueryTimeoutSecs",
  ],
  shortcuts: ["shortcuts", "sqlShortcuts"],
  snippets: ["snippets", "snippetTriggerKey"],
  other: ["updateDownloadSource", "updateNotificationsEnabled", "autoDownloadUpdates", "autoUpdateApp", "autoUpdateDrivers", "autoUpdateJdbc", "autoUpdateMcp", "autoUpdatePlugins"],
};

const KEY_TO_CATEGORY = new Map<string, SettingsTransferCategoryId>();
for (const [category, keys] of Object.entries(SETTINGS_TRANSFER_CATEGORY_KEYS) as [SettingsTransferCategoryId, readonly EditorSettingsDraftKey[]][]) {
  for (const key of keys) KEY_TO_CATEGORY.set(key, category);
}

export function transferCategoryForKey(key: string): SettingsTransferCategoryId | undefined {
  return KEY_TO_CATEGORY.get(key);
}

export function collectTransferCategories(keys: readonly string[]): SettingsTransferCategoryId[] {
  const present = new Set<SettingsTransferCategoryId>();
  for (const key of keys) {
    const category = KEY_TO_CATEGORY.get(key);
    if (category) present.add(category);
  }
  return sortTransferCategories(present);
}

/** Orders category ids by their fixed display order. */
export function sortTransferCategories(categories: Iterable<SettingsTransferCategoryId>): SettingsTransferCategoryId[] {
  const present = new Set(categories);
  return SETTINGS_TRANSFER_CATEGORY_ORDER.filter((category) => present.has(category));
}

/** i18n keys used to render the affected categories in the import dialog. */
export const SETTINGS_TRANSFER_CATEGORY_LABEL_KEYS: Record<SettingsTransferCategoryId, string> = {
  appearance: "settings.appearanceTab",
  editor: "settings.editorTab",
  formatter: "settings.sqlFormatterTab",
  navigation: "settings.navigationTab",
  data: "settings.dataTab",
  shortcuts: "settings.shortcutsTab",
  snippets: "settings.snippetsTab",
  other: "settings.settingsTransferCategoryOther",
};

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

/**
 * UTF-8 needs 1–3 bytes per UTF-16 code unit, so the character count alone
 * settles every text outside the ambiguous expansion band. The precise byte
 * count — which allocates an encoded copy of the whole text — is only built
 * for inputs whose size could still tip over the limit after expansion.
 */
function exceedsSettingsTransferSizeLimit(text: string): boolean {
  if (text.length > MAX_SETTINGS_TRANSFER_FILE_BYTES) return true;
  if (text.length * 3 <= MAX_SETTINGS_TRANSFER_FILE_BYTES) return false;
  return new TextEncoder().encode(text).byteLength > MAX_SETTINGS_TRANSFER_FILE_BYTES;
}

function deepClone<T>(value: T): T {
  return JSON.parse(JSON.stringify(value)) as T;
}

function jsonKindOf(value: unknown): string {
  return Array.isArray(value) ? "array" : typeof value;
}

// Expected JSON kind per whitelisted key, derived from the defaults. The store
// normalizer is defensive but a few keys pass values through unchanged, so the
// kind check is what rejects wrong-typed fields (e.g. a string fontSize).
const EXPECTED_JSON_KINDS = new Map<string, string>(EDITOR_SETTINGS_DRAFT_KEYS.map((key) => [key, jsonKindOf((DEFAULT_EDITOR_SETTINGS as unknown as Record<string, unknown>)[key])]));

/**
 * Keys whose store normalizer keeps any non-nullish value as-is (only a
 * nullish fallback). For these, the round-trip equality check cannot catch a
 * bad value: `fontSize: 0` or `appLayout: "invalid"` would survive untouched
 * and later be persisted. Each entry restates the domain the settings UI and
 * the clamping helpers enforce, so importing an out-of-range number, a broken
 * enum or a non-boolean flag refuses the whole file instead.
 */
const PASS_THROUGH_BOOLEAN_KEYS = [
  "wordWrap",
  "showWhitespace",
  "showExecutionTargetPicker",
  "autoAliasTables",
  "functionCompletionIncludeParams",
  "sequenceCompletionEnabled",
  "fontSmoothing",
  "confirmDangerousSqlExecution",
  "confirmUnsavedSqlClose",
  "showColumnCommentsInHeader",
  "dataGridColumnCommentsInInfoArea",
  "dataGridTransposeMetadataInInfoColumn",
  "showColumnTypesInHeader",
  "showColumnHeaderTooltips",
  "showResultSourceDatabase",
  "resultTabPreferComments",
  "colorizeDataGridCellTypes",
  "showIndexIndicatorsInHeader",
  "compactColumnHeaderActions",
  "dataGridQuickEntry",
  "dataGridStripedRows",
  "flatteningMultiLineText",
  "dataGridShowWhitespace",
  "infiniteScroll",
  "autoCalculateTotalRows",
  "autoSelectActiveSidebarNode",
  "sidebarPinDefaultDatabase",
  "sidebarAllowHorizontalScroll",
  "sidebarShowTooltips",
  "updateNotificationsEnabled",
  "autoDownloadUpdates",
  "autoUpdateApp",
  "autoUpdateDrivers",
  "autoUpdateJdbc",
  "autoUpdateMcp",
  "autoUpdatePlugins",
] as const satisfies readonly EditorSettingsDraftKey[];

const PASS_THROUGH_FIELD_VALIDATORS: Partial<Record<EditorSettingsDraftKey, (value: unknown) => boolean>> = {
  // The editor font slider and the Ctrl+wheel zoom both clamp to this range.
  fontSize: (value) => typeof value === "number" && Number.isFinite(value) && value >= EDITOR_MIN_FONT_SIZE && value <= EDITOR_MAX_FONT_SIZE,
  welcomePageMode: (value) => value === "intro" || value === "workspace",
  aiSqlApplyTargetMode: (value) => value === "current" || value === "first" || value === "new",
  appLayout: (value) => value === "separated" || value === "classic",
  webLogoPosition: (value) => value === "left" || value === "right" || value === "hidden",
  resultTabNamingMode: (value) => value === "source" || value === "ordinal" || value === "comment",
  activeCustomThemeId: (value) => typeof value === "string" && value.trim().length > 0,
  sidebarDensity: (value) => value === "default" || value === "compact",
  // normalizeToolbarItems keeps unknown/typed values for every known key, so
  // each one must already be the boolean the UI writes, and no extra key may
  // appear.
  toolbarItems: (value) => isPlainObject(value) && Object.keys(DEFAULT_TOOLBAR_ITEMS).every((key) => typeof value[key] === "boolean") && Object.keys(value).every((key) => key in DEFAULT_TOOLBAR_ITEMS),
  ...Object.fromEntries(PASS_THROUGH_BOOLEAN_KEYS.map((key) => [key, (value: unknown) => typeof value === "boolean"])),
};

function isNonEmptyTrimmedString(value: unknown): value is string {
  return typeof value === "string" && value.trim().length > 0;
}

function isArrayOfShape(value: unknown, isItem: (item: unknown) => boolean): boolean {
  return Array.isArray(value) && value.every(isItem);
}

function isStringArray(value: unknown): boolean {
  return Array.isArray(value) && value.every((item) => typeof item === "string");
}

function isNonEmptyStringArray(value: unknown): boolean {
  return isStringArray(value) && (value as string[]).every((item) => item.trim().length > 0);
}

/** Required color keys of a custom editor theme, keyed by expected JSON kind. */
function valueKindShape(defaults: Record<string, unknown>): Record<string, string> {
  return Object.fromEntries(Object.entries(defaults).map(([key, value]) => [key, typeof value]));
}

const CUSTOM_THEME_COLORS_SHAPE = valueKindShape(DEFAULT_CUSTOM_THEME_COLORS as unknown as Record<string, unknown>);
const CUSTOM_THEME_DDL_COLORS_SHAPE = valueKindShape(DEFAULT_CUSTOM_THEME_DDL_COLORS as unknown as Record<string, unknown>);

/**
 * Optional color keys of a custom editor theme. They are absent from
 * DEFAULT_CUSTOM_THEME_COLORS, so the defaults-derived shape above cannot
 * cover them and a wrong-typed value (e.g. `background: {}`) would otherwise
 * pass validation and reach the persisted settings.
 */
const CUSTOM_THEME_OPTIONAL_COLOR_KEYS = ["background", "foreground", "activeLine", "selection", "cursor", "gutterBackground", "lineNumber", "matchingBracket"] as const;

function hasValidOptionalColorKinds(value: unknown): boolean {
  if (!isPlainObject(value)) return false;
  return CUSTOM_THEME_OPTIONAL_COLOR_KEYS.every((key) => value[key] === undefined || typeof value[key] === "string");
}

function hasRequiredValueKinds(value: unknown, shape: Record<string, string>): boolean {
  if (!isPlainObject(value)) return false;
  return Object.entries(shape).every(([key, kind]) => typeof value[key] === kind);
}

function isCustomThemeItem(value: unknown): boolean {
  return isPlainObject(value) && isNonEmptyTrimmedString(value.id) && isNonEmptyTrimmedString(value.name) && hasRequiredValueKinds(value.colors, CUSTOM_THEME_COLORS_SHAPE) && hasValidOptionalColorKinds(value.colors) && hasRequiredValueKinds(value.ddlColors, CUSTOM_THEME_DDL_COLORS_SHAPE);
}

// The store normalizer only writes #rrggbb values, matching normalizeDataGridTypeColors.
const DATA_GRID_TYPE_HEX_COLOR_RE = /^#[0-9a-fA-F]{6}$/;

function isDataGridTypeColorSchemeItem(value: unknown): boolean {
  if (!isPlainObject(value)) return false;
  // The auto id is the "follow the built-in palette" sentinel, never a scheme.
  if (!isNonEmptyTrimmedString(value.id) || value.id === DATA_GRID_TYPE_COLOR_SCHEME_AUTO_ID) return false;
  if (!isNonEmptyTrimmedString(value.name)) return false;
  const colors = value.colors;
  if (!isPlainObject(colors)) return false;
  return DATA_GRID_TYPE_COLOR_KEYS.every((key) => {
    const color = colors[key];
    return typeof color === "string" && DATA_GRID_TYPE_HEX_COLOR_RE.test(color);
  });
}

function isSqlSnippetItem(value: unknown): boolean {
  if (!isPlainObject(value)) return false;
  if (!isNonEmptyTrimmedString(value.id) || !isNonEmptyTrimmedString(value.label) || !isNonEmptyTrimmedString(value.prefix) || typeof value.body !== "string") return false;
  return value.enabled === undefined || typeof value.enabled === "boolean";
}

function isModelGenerationTemplatesShape(value: unknown): boolean {
  if (!Array.isArray(value)) return false;
  const ids = new Set<string>();
  return value.every((item) => {
    if (!isPlainObject(item) || typeof item.id !== "string" || !item.id || ids.has(item.id) || !isNonEmptyTrimmedString(item.name) || typeof item.extension !== "string" || !/^[a-zA-Z0-9]+$/.test(item.extension) || typeof item.body !== "string") return false;
    ids.add(item.id);
    return true;
  });
}

function isSqlShortcutActionItem(value: unknown): boolean {
  if (!isPlainObject(value)) return false;
  if (!isNonEmptyTrimmedString(value.id) || !isNonEmptyTrimmedString(value.label) || typeof value.shortcut !== "string" || typeof value.sql !== "string") return false;
  if (value.enabled !== undefined && typeof value.enabled !== "boolean") return false;
  if (value.kind !== undefined && value.kind !== "template" && value.kind !== "select-limit") return false;
  if (value.limit !== undefined && (typeof value.limit !== "number" || !Number.isFinite(value.limit))) return false;
  if (value.databaseTypes !== undefined) {
    if (!Array.isArray(value.databaseTypes) || !value.databaseTypes.every((item) => typeof item === "string" && item.trim().length > 0)) return false;
  }
  if (value.sqlByDatabaseType !== undefined) {
    if (!isPlainObject(value.sqlByDatabaseType)) return false;
    if (!Object.values(value.sqlByDatabaseType).every((sql) => typeof sql === "string")) return false;
  }
  return true;
}

const SHORTCUT_ACTION_IDS = new Set<string>(SHORTCUT_DEFINITIONS.map((definition) => definition.id));

/** Normalized shape: exactly the known action ids, each bound to a string. */
function isShortcutSettingsShape(value: unknown): boolean {
  return isPlainObject(value) && Object.entries(value).every(([key, entry]) => SHORTCUT_ACTION_IDS.has(key) && typeof entry === "string");
}

/** Raw shape: overrides for known actions must be strings; unknown keys stay ignored for forward compatibility. */
function isRawShortcutSettingsShape(value: unknown): boolean {
  return isPlainObject(value) && Object.entries(value).every(([key, entry]) => !SHORTCUT_ACTION_IDS.has(key) || typeof entry === "string");
}

/**
 * Raw shape: every known toolbar key must already be a boolean.
 * normalizeToolbarItems coerces `exclusiveRightSidebarPanels` with `!== false`
 * (and fills the rest with nullish defaults), so a non-boolean like "no" would
 * otherwise be silently turned into `true` and pass the normalized round-trip
 * check. Unknown keys stay ignored for forward compatibility.
 */
function isRawToolbarItemsShape(value: unknown): boolean {
  return isPlainObject(value) && Object.entries(value).every(([key, entry]) => !(key in DEFAULT_TOOLBAR_ITEMS) || typeof entry === "boolean");
}

const SQL_VARIABLE_SYNTAX_KEY_SET = new Set<string>(SQL_VARIABLE_SYNTAX_KEYS);

/**
 * Formatter option keys introduced after the settings-transfer format shipped
 * (v0.6.7). An export written before a key existed legitimately lacks it, so
 * requiring every current key would reject the entire file and discard every
 * other setting it carries — which is what happened when `commaPosition`
 * landed in v0.6.35. Absence is only tolerated for these keys, and only
 * because the version boundary is known; nothing is inferred about which
 * style the user meant. Every future formatter option must be added here.
 */
const SQL_FORMATTER_KEYS_ADDED_AFTER_TRANSFER_FORMAT = new Set<keyof SqlFormatterOptionSettings>(["commaPosition", "layoutStyle", ...(Object.keys(DEFAULT_SQL_FORMATTER_RULE_SETTINGS) as (keyof SqlFormatterRuleSettings)[])]);

/**
 * Complete-schema check that tolerates the absence of the post-transfer
 * formatter keys: present keys keep the strict check (valid value, no unknown
 * key), and the missing baseline-compatible ones are filled with their
 * defaults before delegating, so a payload missing a baseline key such as
 * `keywordCase` is still rejected.
 */
function isTransferableSqlFormatterSettings(value: unknown): boolean {
  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
  const filled: Record<string, unknown> = { ...(value as Record<string, unknown>) };
  for (const key of SQL_FORMATTER_KEYS_ADDED_AFTER_TRANSFER_FORMAT) {
    if (!(key in filled)) filled[key] = DEFAULT_SQL_FORMATTER_SETTINGS[key];
  }
  return isCompleteSqlFormatterSettings(filled);
}

function isSqlVariableSyntaxOverridesShape(value: unknown, isAllowedToggle: (toggle: unknown) => boolean): boolean {
  if (!isPlainObject(value)) return false;
  return Object.values(value).every((entry) => isPlainObject(entry) && Object.entries(entry).every(([key, toggle]) => SQL_VARIABLE_SYNTAX_KEY_SET.has(key) && isAllowedToggle(toggle)));
}

/**
 * Full nested-schema checks for the structured (array/object) fields, run on
 * the normalized value. The store normalizer only sanitizes some of them —
 * notably `normalizeEditorSettings` keeps `customThemes` items that lack
 * `id` or `name` — so without these checks a file like
 * `{"customThemes": [{}]}` would import cleanly and later corrupt the
 * persisted settings.
 */
const NESTED_FIELD_VALIDATORS: Partial<Record<EditorSettingsDraftKey, (value: unknown) => boolean>> = {
  customThemes: (value) => isArrayOfShape(value, isCustomThemeItem),
  dataGridTypeColorSchemes: (value) => isArrayOfShape(value, isDataGridTypeColorSchemeItem),
  tableColumnTemplateFields: isNonEmptyStringArray,
  shortcuts: isShortcutSettingsShape,
  sqlFormatter: isTransferableSqlFormatterSettings,
  sidebarHiddenTablePrefixes: isNonEmptyStringArray,
  redisKeyTemplates: isNonEmptyStringArray,
  snippets: (value) => isArrayOfShape(value, isSqlSnippetItem),
  modelGenerationTemplates: isModelGenerationTemplatesShape,
  sqlShortcuts: (value) => isArrayOfShape(value, isSqlShortcutActionItem),
  sqlVariableSyntaxOverrides: (value) => isSqlVariableSyntaxOverridesShape(value, (toggle) => typeof toggle === "boolean"),
};

/**
 * The same nested schemas applied to the raw file values before
 * normalization. This rejects payloads the normalizer would silently repair
 * by dropping entries or substituting defaults — importing those would
 * overwrite the user's data (custom schemes, snippets, formatter options, …)
 * with sanitized defaults instead of surfacing the malformed file. Running
 * them before the normalizer also keeps `normalizeEditorSettings` from
 * throwing on malformed containers it does not sanitize (e.g. a null item
 * inside `customThemes`).
 */
const RAW_STRUCTURED_FIELD_VALIDATORS: Partial<Record<EditorSettingsDraftKey, (value: unknown) => boolean>> = {
  customThemes: (value) => isArrayOfShape(value, isCustomThemeItem),
  dataGridTypeColorSchemes: (value) => isArrayOfShape(value, isDataGridTypeColorSchemeItem),
  tableColumnTemplateFields: isStringArray,
  shortcuts: isRawShortcutSettingsShape,
  toolbarItems: isRawToolbarItemsShape,
  sqlFormatter: isTransferableSqlFormatterSettings,
  sidebarHiddenTablePrefixes: isStringArray,
  redisKeyTemplates: isStringArray,
  snippets: (value) => isArrayOfShape(value, isSqlSnippetItem),
  modelGenerationTemplates: isModelGenerationTemplatesShape,
  sqlShortcuts: (value) => isArrayOfShape(value, isSqlShortcutActionItem),
  sqlVariableSyntaxOverrides: (value) => isSqlVariableSyntaxOverridesShape(value, (toggle) => typeof toggle === "boolean"),
};

/**
 * Parses and validates an imported settings file. Validation is all-or-
 * nothing: the caller only receives values once every whitelisted field in
 * the file passed the checks, so a rejected file can never partially modify
 * the settings draft.
 *
 * Raw JSON-kind and raw structured checks (see
 * RAW_STRUCTURED_FIELD_VALIDATORS) run first, before the normalizer, so a
 * malformed container is reported as `invalid-fields` instead of throwing
 * inside a store normalizer. Scalar values (boolean/number/string) must
 * survive the store's own normalizer unchanged — an out-of-domain enum or a
 * clamped number comes back different and rejects the import. Pass-through
 * fields (see PASS_THROUGH_FIELD_VALIDATORS) get an explicit domain check
 * instead, because the normalizer keeps them as-is. Objects and arrays are
 * sanitized through the same normalizer and must additionally satisfy a full
 * nested schema (see NESTED_FIELD_VALIDATORS): malformed nested payloads are
 * rejected instead of being silently repaired or persisted.
 */
export function parseSettingsTransferFile(text: string, options: SettingsTransferParseOptions = {}): { ok: true; value: ParsedSettingsTransfer } | { ok: false; error: SettingsTransferParseError } {
  if (exceedsSettingsTransferSizeLimit(text)) {
    return { ok: false, error: { code: "too-large" } };
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(text);
  } catch {
    return { ok: false, error: { code: "invalid-json" } };
  }
  if (!isPlainObject(parsed)) return { ok: false, error: { code: "invalid-structure" } };

  const formatVersion = parsed.formatVersion;
  if (typeof formatVersion !== "number" || !Number.isInteger(formatVersion) || formatVersion !== SETTINGS_TRANSFER_FORMAT_VERSION) {
    return { ok: false, error: { code: "unsupported-version", detail: typeof formatVersion === "number" ? String(formatVersion) : undefined } };
  }

  const settings = parsed.settings;
  if (!isPlainObject(settings)) return { ok: false, error: { code: "invalid-structure" } };
  const editor = settings.editor;
  if (editor !== undefined && !isPlainObject(editor)) return { ok: false, error: { code: "invalid-structure" } };
  const appearance = settings.appearance;
  if (appearance !== undefined && !isPlainObject(appearance)) return { ok: false, error: { code: "invalid-structure" } };
  const includeDesktop = options.includeDesktopSettings !== false;
  const desktop = settings.desktop;
  if (includeDesktop && desktop !== undefined && !isPlainObject(desktop)) return { ok: false, error: { code: "invalid-structure" } };

  // App-wide theme mode from the optional appearance section. Only the three
  // canonical modes are accepted; legacy soft-* values normalize before they
  // ever reach a transfer file.
  let themeMode: AppThemeMode | undefined;
  if (isPlainObject(appearance) && appearance.themeMode !== undefined) {
    const value = appearance.themeMode;
    if (value === "light" || value === "dark" || value === "system") {
      themeMode = value;
    } else {
      return { ok: false, error: { code: "invalid-fields", detail: "appearance.themeMode" } };
    }
  }

  // Desktop preferences from the optional desktop section, skipped whole on
  // platforms where the switches do not exist. Unknown keys are ignored like
  // in the editor section; the accepted values must survive the store
  // normalizer unchanged, so a clamped number (duckdb worker processes) or an
  // out-of-domain enum (icon theme) rejects the whole file instead of being
  // silently repaired.
  const desktopKeys = includeDesktop && isPlainObject(desktop) ? TRANSFERABLE_DESKTOP_SETTINGS_KEYS.filter((key) => key in desktop) : [];
  const importedDesktop: Partial<TransferableDesktopSettings> = {};
  if (desktopKeys.length > 0 && isPlainObject(desktop)) {
    const desktopProbe: Record<string, unknown> = { ...DEFAULT_DESKTOP_SETTINGS };
    for (const key of desktopKeys) {
      const raw = desktop[key];
      if (typeof raw !== typeof DEFAULT_DESKTOP_SETTINGS[key]) {
        return { ok: false, error: { code: "invalid-fields", detail: `desktop.${key}` } };
      }
      desktopProbe[key] = raw;
    }
    const normalizedDesktop = normalizeDesktopSettings(desktopProbe as Partial<DesktopSettings>);
    for (const key of desktopKeys) {
      if (normalizedDesktop[key] !== desktop[key]) {
        return { ok: false, error: { code: "invalid-fields", detail: `desktop.${key}` } };
      }
      importedDesktop[key] = normalizedDesktop[key] as never;
    }
  }

  // Old exports used the inverse `dataGridAutoHideFilterBuilder` flag. Keep
  // accepting it, but normalize it into the single current preference before
  // applying the strict whitelist below.
  if (isPlainObject(editor) && !("dataGridKeepFilterEditorExpanded" in editor) && typeof editor.dataGridAutoHideFilterBuilder === "boolean") {
    editor.dataGridKeepFilterEditorExpanded = !editor.dataGridAutoHideFilterBuilder;
  }

  const editorObject = isPlainObject(editor) ? editor : {};
  const presentKeys = EDITOR_SETTINGS_DRAFT_KEYS.filter((key) => key in editorObject);
  if (presentKeys.length === 0 && desktopKeys.length === 0 && themeMode === undefined) return { ok: false, error: { code: "empty-settings" } };

  // Validate the raw file values BEFORE the normalizer runs. Some store
  // normalizers assume well-formed containers (e.g. customThemes items must
  // expose `name`) and throw on malformed input instead of sanitizing it, so
  // a broken file must be rejected here and surface as `invalid-fields`
  // rather than crashing the parse.
  const invalidKeys: string[] = [];
  for (const key of presentKeys) {
    const raw = editorObject[key];
    if (jsonKindOf(raw) !== EXPECTED_JSON_KINDS.get(key)) {
      invalidKeys.push(key);
      continue;
    }
    const rawValidator = RAW_STRUCTURED_FIELD_VALIDATORS[key];
    if (rawValidator && !rawValidator(raw)) {
      invalidKeys.push(key);
    }
  }
  if (invalidKeys.length > 0) {
    return { ok: false, error: { code: "invalid-fields", detail: invalidKeys.slice(0, 5).join(", ") } };
  }

  // Run the imported values through the same normalizer the store applies on
  // load. Defaults are cloned first so the shared constant can never be
  // mutated by a malformed file.
  const probe = deepClone(DEFAULT_EDITOR_SETTINGS) as EditorSettings;
  for (const key of presentKeys) {
    (probe as unknown as Record<string, unknown>)[key] = editorObject[key];
  }
  const normalized = normalizeEditorSettings(probe);

  const imported: Partial<EditorSettings> = {};
  for (const key of presentKeys) {
    const raw = editorObject[key];
    const value = (normalized as unknown as Record<string, unknown>)[key];
    const validator = PASS_THROUGH_FIELD_VALIDATORS[key] ?? NESTED_FIELD_VALIDATORS[key];
    if (validator && !validator(value)) {
      invalidKeys.push(key);
      continue;
    }
    if (typeof raw === "boolean" || typeof raw === "number" || typeof raw === "string") {
      if (typeof raw !== typeof value || value !== raw) {
        invalidKeys.push(key);
        continue;
      }
      imported[key as EditorSettingsDraftKey] = deepClone(value) as never;
    } else if (Array.isArray(raw)) {
      if (!Array.isArray(value)) {
        invalidKeys.push(key);
        continue;
      }
      imported[key as EditorSettingsDraftKey] = deepClone(value) as never;
    } else if (isPlainObject(raw)) {
      if (!isPlainObject(value)) {
        invalidKeys.push(key);
        continue;
      }
      imported[key as EditorSettingsDraftKey] = deepClone(value) as never;
    } else {
      invalidKeys.push(key);
    }
  }
  if (invalidKeys.length > 0) {
    return { ok: false, error: { code: "invalid-fields", detail: invalidKeys.slice(0, 5).join(", ") } };
  }

  const app = isPlainObject(parsed.app) ? parsed.app : {};
  const rawAppVersion = typeof app.version === "string" ? app.version.trim() : "";
  const rawExportedAt = typeof parsed.exportedAt === "string" ? parsed.exportedAt : "";

  const categories = new Set(collectTransferCategories(Object.keys(imported)));
  if (themeMode !== undefined) categories.add("appearance");
  if (desktopKeys.length > 0) categories.add("other");

  return {
    ok: true,
    value: {
      formatVersion: SETTINGS_TRANSFER_FORMAT_VERSION,
      ...(rawAppVersion ? { appVersion: rawAppVersion } : {}),
      ...(rawExportedAt ? { exportedAt: rawExportedAt } : {}),
      editorSettings: imported,
      ...(themeMode !== undefined ? { themeMode } : {}),
      desktopSettings: importedDesktop,
      categories: sortTransferCategories(categories),
    },
  };
}