@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/utils/DeltaStorage.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Diff operation tuple: [operation, text]
+ * operation: -1 (delete), 0 (equal), 1 (insert)
+ */
+export type DiffTuple = [number, string];
+/**
+ * Diff statistics
+ */
+export interface DiffStats {
+    additions: number;
+    deletions: number;
+    unchanged: number;
+}
+/**
+ * DeltaStorage - Utility for creating and applying content diffs
+ *
+ * Uses the fast-diff library (Myers diff algorithm) to efficiently store
+ * page versions as deltas. Version 1 stores full content, subsequent versions
+ * store only the differences from the previous version.
+ *
+ * fast-diff returns an array of tuples: [operation, text]
+ * - operation: -1 (delete), 0 (equal), 1 (insert)
+ * - text: the text content
+ *
+ * @example
+ * const diff = DeltaStorage.createDiff("Hello world", "Hello ngdpbase");
+ * // Returns: [[0, "Hello "], [-1, "world"], [1, "ngdpbase"]]
+ *
+ * const reconstructed = DeltaStorage.applyDiff("Hello world", diff);
+ * // Returns: "Hello ngdpbase"
+ */
+export default class DeltaStorage {
+    /**
+     * Generate diff between old and new content
+     *
+     * Creates a diff using the Myers algorithm (similar to git).
+     * Returns an array of operations that transform oldContent into newContent.
+     *
+     * @param oldContent - Original content
+     * @param newContent - New content
+     * @returns Diff array from fast-diff
+     * @example
+     * const diff = DeltaStorage.createDiff("foo", "bar");
+     * // Returns: [[-1, "foo"], [1, "bar"]]
+     */
+    static createDiff(oldContent: string, newContent: string): DiffTuple[];
+    /**
+     * Apply a diff to base content to reconstruct a version
+     *
+     * Takes the base content and applies a diff array to reconstruct the target content.
+     * Used to reconstruct versions from delta storage.
+     *
+     * @param baseContent - Base content to apply diff to
+     * @param diff - Diff array from fast-diff
+     * @returns Reconstructed content
+     * @throws {TypeError} If inputs are invalid
+     * @example
+     * const base = "Hello world";
+     * const diff: DiffTuple[] = [[0, "Hello "], [-1, "world"], [1, "ngdpbase"]];
+     * const result = DeltaStorage.applyDiff(base, diff);
+     * // Returns: "Hello ngdpbase"
+     */
+    static applyDiff(baseContent: string, diff: DiffTuple[]): string;
+    /**
+     * Apply multiple diffs sequentially
+     *
+     * Applies a chain of diffs to reconstruct a version from v1.
+     * Used when retrieving versions > 2 in delta storage.
+     *
+     * @param v1Content - Version 1 (base) content
+     * @param diffArray - Array of diffs to apply sequentially
+     * @returns Final reconstructed content
+     * @throws {Error} If any diff application fails
+     * @example
+     * const v1 = "Version 1";
+     * const diffs: DiffTuple[][] = [
+     *   [[0, "Version "], [-1, "1"], [1, "2"]],  // v1 → v2
+     *   [[0, "Version "], [-1, "2"], [1, "3"]]   // v2 → v3
+     * ];
+     * const v3 = DeltaStorage.applyDiffChain(v1, diffs);
+     * // Returns: "Version 3"
+     */
+    static applyDiffChain(v1Content: string, diffArray: DiffTuple[][]): string;
+    /**
+     * Calculate SHA-256 hash of content
+     *
+     * Used for content integrity verification and deduplication.
+     * Stored in version metadata for verification.
+     *
+     * @param content - Content to hash
+     * @returns SHA-256 hash in hexadecimal format
+     */
+    static calculateHash(content: string): string;
+    /**
+     * Verify content integrity using hash
+     *
+     * Checks if the content hash matches the expected hash.
+     * Used to detect corruption in version storage.
+     *
+     * @param content - Content to verify
+     * @param expectedHash - Expected SHA-256 hash
+     * @returns True if hash matches, false otherwise
+     */
+    static verifyHash(content: string, expectedHash: string): boolean;
+    /**
+     * Calculate diff statistics
+     *
+     * Analyzes a diff to provide statistics about the changes.
+     * Useful for UI display and analytics.
+     *
+     * @param diff - Diff array from fast-diff
+     * @returns Statistics object
+     * @example
+     * const stats = DeltaStorage.getDiffStats(diff);
+     * // Returns: { additions: 10, deletions: 5, unchanged: 100 }
+     */
+    static getDiffStats(diff: DiffTuple[]): DiffStats;
+}

package/lib/src/utils/LocaleUtils.d.ts

@@ -0,0 +1,105 @@
+/**
+ * LocaleUtils - Utility functions for handling browser locale and internationalization
+ */
+/**
+ * Date format option for user preferences
+ */
+interface DateFormatOption {
+    value: string;
+    label: string;
+    description: string;
+}
+/**
+ * Supported locale information
+ */
+interface SupportedLocale {
+    code: string;
+    name: string;
+    dateFormat: string;
+    timeFormat: '12h' | '24h';
+}
+/**
+ * Locale utilities for handling browser locale and internationalization
+ */
+declare class LocaleUtils {
+    /**
+     * Parse Accept-Language header to get preferred locale
+     * @param acceptLanguage - Accept-Language header value
+     * @returns Best matching locale (e.g., 'en-US', 'fr-FR', 'de-DE')
+     */
+    static parseAcceptLanguage(acceptLanguage: string): string;
+    /**
+     * Normalize locale string to standard format
+     * @param locale - Raw locale string
+     * @returns Normalized locale (e.g., 'en-US', 'fr-FR')
+     */
+    static normalizeLocale(locale: string): string;
+    /**
+     * Get date format pattern based on locale
+     * @param locale - Locale string (e.g., 'en-US')
+     * @returns Date format pattern for user preferences
+     */
+    static getDateFormatFromLocale(locale: string): string;
+    /**
+     * Get time format preference based on locale
+     * @param locale - Locale string (e.g., 'en-US')
+     * @returns Time format preference ('12h' or '24h')
+     */
+    static getTimeFormatFromLocale(locale: string): '12h' | '24h';
+    /**
+     * Format date using specified locale
+     * @param date - Date to format
+     * @param locale - Locale string
+     * @returns Formatted date string
+     */
+    static formatDate(date: Date, locale?: string): string;
+    /**
+     * Format date using an explicit pattern string (e.g. 'yyyy-MM-dd').
+     * Supports the subset of patterns offered in the profile date-format picker.
+     * @param date - Date to format
+     * @param pattern - Format pattern ('yyyy-MM-dd', 'MM/dd/yyyy', 'dd/MM/yyyy', 'dd.MM.yyyy', 'yyyy/MM/dd')
+     * @param timezone - Optional IANA timezone (e.g. 'America/New_York', 'UTC')
+     * @returns Formatted date string
+     */
+    static formatDateWithPattern(date: Date, pattern: string, timezone?: string): string;
+    /**
+     * Format time honoring an explicit 12h/24h preference and optional timezone.
+     * @param date - Date to format
+     * @param timeFormat - '12h' or '24h'
+     * @param locale - Locale string (used for AM/PM labels in 12h mode)
+     * @param timezone - Optional IANA timezone
+     * @returns Formatted time string
+     */
+    static formatTimeWithPrefs(date: Date, timeFormat: string, locale?: string, timezone?: string): string;
+    /**
+     * Format time using specified locale
+     * @param date - Date to format
+     * @param locale - Locale string
+     * @returns Formatted time string
+     */
+    static formatTime(date: Date, locale?: string): string;
+    /**
+     * Get available date format options
+     * @returns Array of date format options
+     */
+    static getDateFormatOptions(): DateFormatOption[];
+    /**
+     * Get supported locales list
+     * @returns Array of supported locale objects
+     */
+    static getSupportedLocales(): SupportedLocale[];
+    /**
+     * Validate timezone string
+     * @param timezone - Timezone to validate
+     * @returns True if timezone is valid
+     */
+    static isValidTimezone(timezone: string): boolean;
+    /**
+     * Get timezone display name
+     * @param timezone - Timezone identifier (e.g., 'America/New_York')
+     * @param locale - Locale for display name (default: 'en-US')
+     * @returns Human-readable timezone name
+     */
+    static getTimezoneDisplayName(timezone: string, locale?: string): string;
+}
+export default LocaleUtils;

package/lib/src/utils/LocaleUtils.js

@@ -0,0 +1,294 @@
+/**
+ * LocaleUtils - Utility functions for handling browser locale and internationalization
+ */
+import logger from './logger.js';
+/**
+ * Locale utilities for handling browser locale and internationalization
+ */
+class LocaleUtils {
+    /**
+     * Parse Accept-Language header to get preferred locale
+     * @param acceptLanguage - Accept-Language header value
+     * @returns Best matching locale (e.g., 'en-US', 'fr-FR', 'de-DE')
+     */
+    static parseAcceptLanguage(acceptLanguage) {
+        if (!acceptLanguage || typeof acceptLanguage !== 'string') {
+            return 'en-US'; // Default fallback
+        }
+        // Parse Accept-Language header format: "en-US,en;q=0.9,fr;q=0.8"
+        const languages = acceptLanguage
+            .split(',')
+            .map(lang => {
+            const parts = lang.trim().split(';');
+            const locale = parts[0].trim();
+            const quality = parts[1] ? parseFloat(parts[1].split('=')[1]) : 1.0;
+            return { locale, quality };
+        })
+            .sort((a, b) => b.quality - a.quality); // Sort by quality score (highest first)
+        // Return the highest quality locale
+        const preferred = languages[0]?.locale || 'en-US';
+        // Normalize common locale formats
+        return this.normalizeLocale(preferred);
+    }
+    /**
+     * Normalize locale string to standard format
+     * @param locale - Raw locale string
+     * @returns Normalized locale (e.g., 'en-US', 'fr-FR')
+     */
+    static normalizeLocale(locale) {
+        if (!locale)
+            return 'en-US';
+        // Handle common formats
+        const normalized = locale.toLowerCase().replace('_', '-');
+        // Map common language codes to full locales
+        const localeMap = {
+            'en': 'en-US',
+            'fr': 'fr-FR',
+            'de': 'de-DE',
+            'es': 'es-ES',
+            'it': 'it-IT',
+            'pt': 'pt-BR',
+            'ja': 'ja-JP',
+            'ko': 'ko-KR',
+            'zh': 'zh-CN',
+            'ru': 'ru-RU',
+            'ar': 'ar-SA',
+            'hi': 'hi-IN'
+        };
+        // If it's just a language code, expand it
+        if (localeMap[normalized]) {
+            return localeMap[normalized];
+        }
+        // If it's already in lang-country format, capitalize country
+        const parts = normalized.split('-');
+        if (parts.length === 2) {
+            return `${parts[0]}-${parts[1].toUpperCase()}`;
+        }
+        return normalized || 'en-US';
+    }
+    /**
+     * Get date format pattern based on locale
+     * @param locale - Locale string (e.g., 'en-US')
+     * @returns Date format pattern for user preferences
+     */
+    static getDateFormatFromLocale(locale) {
+        const normalizedLocale = this.normalizeLocale(locale);
+        // Map locales to common date format preferences
+        const dateFormatMap = {
+            'en-US': 'MM/dd/yyyy', // American: 12/25/2023
+            'en-GB': 'dd/MM/yyyy', // British: 25/12/2023
+            'en-CA': 'dd/MM/yyyy', // Canadian: 25/12/2023
+            'fr-FR': 'dd/MM/yyyy', // French: 25/12/2023
+            'de-DE': 'dd.MM.yyyy', // German: 25.12.2023
+            'es-ES': 'dd/MM/yyyy', // Spanish: 25/12/2023
+            'it-IT': 'dd/MM/yyyy', // Italian: 25/12/2023
+            'pt-BR': 'dd/MM/yyyy', // Brazilian Portuguese: 25/12/2023
+            'ja-JP': 'yyyy/MM/dd', // Japanese: 2023/12/25
+            'ko-KR': 'yyyy. MM. dd.', // Korean: 2023. 12. 25.
+            'zh-CN': 'yyyy/MM/dd', // Chinese: 2023/12/25
+            'ru-RU': 'dd.MM.yyyy', // Russian: 25.12.2023
+            'ar-SA': 'dd/MM/yyyy', // Arabic: 25/12/2023
+            'hi-IN': 'dd/MM/yyyy' // Hindi: 25/12/2023
+        };
+        return dateFormatMap[normalizedLocale] || dateFormatMap['en-US'];
+    }
+    /**
+     * Get time format preference based on locale
+     * @param locale - Locale string (e.g., 'en-US')
+     * @returns Time format preference ('12h' or '24h')
+     */
+    static getTimeFormatFromLocale(locale) {
+        const normalizedLocale = this.normalizeLocale(locale);
+        // Most of the world uses 24-hour format, but some countries prefer 12-hour
+        const twelveHourLocales = [
+            'en-US', // United States
+            'en-CA', // Canada (mixed, but 12h common)
+            'en-AU', // Australia (mixed)
+            'en-NZ', // New Zealand (mixed)
+            'en-PH' // Philippines
+        ];
+        return twelveHourLocales.includes(normalizedLocale) ? '12h' : '24h';
+    }
+    /**
+     * Format date using specified locale
+     * @param date - Date to format
+     * @param locale - Locale string
+     * @returns Formatted date string
+     */
+    static formatDate(date, locale = 'en-US') {
+        if (!date || !(date instanceof Date)) {
+            return '';
+        }
+        const normalizedLocale = this.normalizeLocale(locale);
+        try {
+            return date.toLocaleDateString(normalizedLocale);
+        }
+        catch {
+            logger.warn(`Invalid locale '${normalizedLocale}', falling back to en-US`);
+            return date.toLocaleDateString('en-US');
+        }
+    }
+    /**
+     * Format date using an explicit pattern string (e.g. 'yyyy-MM-dd').
+     * Supports the subset of patterns offered in the profile date-format picker.
+     * @param date - Date to format
+     * @param pattern - Format pattern ('yyyy-MM-dd', 'MM/dd/yyyy', 'dd/MM/yyyy', 'dd.MM.yyyy', 'yyyy/MM/dd')
+     * @param timezone - Optional IANA timezone (e.g. 'America/New_York', 'UTC')
+     * @returns Formatted date string
+     */
+    static formatDateWithPattern(date, pattern, timezone) {
+        if (!date || !(date instanceof Date))
+            return '';
+        // Include time parts when the pattern contains time tokens (HH, mm, ss)
+        const needsTime = /HH|mm|ss/.test(pattern);
+        const opts = { year: 'numeric', month: '2-digit', day: '2-digit' };
+        if (needsTime) {
+            opts.hour = '2-digit';
+            opts.minute = '2-digit';
+            opts.second = '2-digit';
+            opts.hour12 = false;
+        }
+        if (timezone && this.isValidTimezone(timezone))
+            opts.timeZone = timezone;
+        try {
+            const parts = {};
+            for (const part of new Intl.DateTimeFormat('en-US', opts).formatToParts(date)) {
+                parts[part.type] = part.value;
+            }
+            // Intl returns hour as '00'-'23' but may use '24' for midnight in some locales;
+            // normalise to two-digit zero-padded.
+            const hour = (parts.hour ?? '00').padStart(2, '0');
+            const minute = (parts.minute ?? '00').padStart(2, '0');
+            const second = (parts.second ?? '00').padStart(2, '0');
+            return pattern
+                .replace('yyyy', parts.year ?? '')
+                .replace('MM', parts.month ?? '')
+                .replace('dd', parts.day ?? '')
+                .replace('HH', hour)
+                .replace('mm', minute)
+                .replace('ss', second);
+        }
+        catch {
+            return date.toLocaleDateString('en-US');
+        }
+    }
+    /**
+     * Format time honoring an explicit 12h/24h preference and optional timezone.
+     * @param date - Date to format
+     * @param timeFormat - '12h' or '24h'
+     * @param locale - Locale string (used for AM/PM labels in 12h mode)
+     * @param timezone - Optional IANA timezone
+     * @returns Formatted time string
+     */
+    static formatTimeWithPrefs(date, timeFormat, locale = 'en-US', timezone) {
+        if (!date || !(date instanceof Date))
+            return '';
+        const hour12 = timeFormat === '12h';
+        const opts = {
+            hour: hour12 ? 'numeric' : '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hour12
+        };
+        if (timezone && this.isValidTimezone(timezone))
+            opts.timeZone = timezone;
+        const normalizedLocale = this.normalizeLocale(locale);
+        try {
+            return date.toLocaleTimeString(normalizedLocale, opts);
+        }
+        catch {
+            return date.toLocaleTimeString('en-US', opts);
+        }
+    }
+    /**
+     * Format time using specified locale
+     * @param date - Date to format
+     * @param locale - Locale string
+     * @returns Formatted time string
+     */
+    static formatTime(date, locale = 'en-US') {
+        if (!date || !(date instanceof Date)) {
+            return '';
+        }
+        const normalizedLocale = this.normalizeLocale(locale);
+        try {
+            return date.toLocaleTimeString(normalizedLocale);
+        }
+        catch {
+            logger.warn(`Invalid locale '${normalizedLocale}', falling back to en-US`);
+            return date.toLocaleTimeString('en-US');
+        }
+    }
+    /**
+     * Get available date format options
+     * @returns Array of date format options
+     */
+    static getDateFormatOptions() {
+        return [
+            { value: 'auto', label: 'Auto (from locale)', description: 'Use locale-specific format' },
+            { value: 'MM/dd/yyyy', label: 'MM/dd/yyyy', description: '12/25/2023 (US format)' },
+            { value: 'dd/MM/yyyy', label: 'dd/MM/yyyy', description: '25/12/2023 (European format)' },
+            { value: 'dd.MM.yyyy', label: 'dd.MM.yyyy', description: '25.12.2023 (German format)' },
+            { value: 'yyyy/MM/dd', label: 'yyyy/MM/dd', description: '2023/12/25 (ISO-style)' },
+            { value: 'yyyy-MM-dd', label: 'yyyy-MM-dd', description: '2023-12-25 (ISO date)' },
+            { value: 'yyyy-MM-dd HH:mm', label: 'yyyy-MM-dd HH:mm', description: '2023-12-25 14:30 (ISO datetime)' }
+        ];
+    }
+    /**
+     * Get supported locales list
+     * @returns Array of supported locale objects
+     */
+    static getSupportedLocales() {
+        return [
+            { code: 'en-US', name: 'English (United States)', dateFormat: 'MM/dd/yyyy', timeFormat: '12h' },
+            { code: 'en-GB', name: 'English (United Kingdom)', dateFormat: 'dd/MM/yyyy', timeFormat: '24h' },
+            { code: 'fr-FR', name: 'Français (France)', dateFormat: 'dd/MM/yyyy', timeFormat: '24h' },
+            { code: 'de-DE', name: 'Deutsch (Deutschland)', dateFormat: 'dd.MM.yyyy', timeFormat: '24h' },
+            { code: 'es-ES', name: 'Español (España)', dateFormat: 'dd/MM/yyyy', timeFormat: '24h' },
+            { code: 'it-IT', name: 'Italiano (Italia)', dateFormat: 'dd/MM/yyyy', timeFormat: '24h' },
+            { code: 'pt-BR', name: 'Português (Brasil)', dateFormat: 'dd/MM/yyyy', timeFormat: '24h' },
+            { code: 'ja-JP', name: '日本語 (日本)', dateFormat: 'yyyy/MM/dd', timeFormat: '24h' },
+            { code: 'ko-KR', name: '한국어 (대한민국)', dateFormat: 'yyyy. MM. dd.', timeFormat: '24h' },
+            { code: 'zh-CN', name: '中文 (中国)', dateFormat: 'yyyy/MM/dd', timeFormat: '24h' },
+            { code: 'ru-RU', name: 'Русский (Россия)', dateFormat: 'dd.MM.yyyy', timeFormat: '24h' },
+            { code: 'ar-SA', name: 'العربية (السعودية)', dateFormat: 'dd/MM/yyyy', timeFormat: '24h' },
+            { code: 'hi-IN', name: 'हिन्दी (भारत)', dateFormat: 'dd/MM/yyyy', timeFormat: '24h' }
+        ];
+    }
+    /**
+     * Validate timezone string
+     * @param timezone - Timezone to validate
+     * @returns True if timezone is valid
+     */
+    static isValidTimezone(timezone) {
+        try {
+            // Test if timezone is supported by Intl.DateTimeFormat
+            new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get timezone display name
+     * @param timezone - Timezone identifier (e.g., 'America/New_York')
+     * @param locale - Locale for display name (default: 'en-US')
+     * @returns Human-readable timezone name
+     */
+    static getTimezoneDisplayName(timezone, locale = 'en-US') {
+        try {
+            const formatter = new Intl.DateTimeFormat(locale, {
+                timeZone: timezone,
+                timeZoneName: 'long'
+            });
+            const parts = formatter.formatToParts(new Date());
+            const timeZonePart = parts.find(part => part.type === 'timeZoneName');
+            return timeZonePart ? timeZonePart.value : timezone;
+        }
+        catch {
+            return timezone;
+        }
+    }
+}
+export default LocaleUtils;

package/lib/src/utils/PageNameMatcher.d.ts

@@ -0,0 +1,98 @@
+/**
+ * PageNameMatcher - Utility for matching page names with plural and case variations
+ *
+ * Implements JSPWiki-style plural matching to allow flexible page name resolution.
+ * For example, linking to "Page" will match both "Page" and "Pages".
+ *
+ * @example
+ * const matcher = new PageNameMatcher(true);
+ * matcher.findMatch('Page', ['Pages', 'Main']); // Returns 'Pages'
+ * matcher.findMatch('Categories', ['Category']); // Returns 'Category'
+ */
+export default class PageNameMatcher {
+    private matchEnglishPlurals;
+    private matchCamelCase;
+    /** Index mapping variation -> original page name for O(1) lookups */
+    private variationIndex;
+    /**
+     * Creates a new PageNameMatcher instance
+     *
+     * @param matchEnglishPlurals - Enable plural matching (default: true)
+     * @param matchCamelCase - Enable CamelCase splitting/joining matching (default: false)
+     */
+    constructor(matchEnglishPlurals?: boolean, matchCamelCase?: boolean);
+    /**
+     * Build an index from page names for fast O(1) lookups
+     * Call this once with all page names before doing many findMatch calls
+     *
+     * Uses two passes so that exact page names always take priority over
+     * plural/singular variants. Without this, "Plugin" would register "plugins"
+     * as a variation and steal the index entry from the real "Plugins" page.
+     *
+     * @param pageNames - Array of all existing page names
+     */
+    buildIndex(pageNames: string[]): void;
+    /**
+     * Clear the index (call when page list changes)
+     */
+    clearIndex(): void;
+    /**
+     * Normalize a page name for comparison (lowercase)
+     *
+     * @param pageName - The page name to normalize
+     * @returns Normalized page name
+     */
+    normalize(pageName: string): string;
+    /**
+     * Split a CamelCase name into separate words
+     * e.g., "HealthCare" → ["Health", "Care"], "XMLParser" → ["XML", "Parser"]
+     *
+     * Acronyms/abbreviations are kept as single units:
+     * e.g., "BCE", "USA", "HTML" → ["BCE"], ["USA"], ["HTML"]
+     * This prevents false matches where "550 BCE" and "330 BCE" would both
+     * generate the variation "b c e" and incorrectly match each other.
+     *
+     * Ordinal/numeric prefixes are also kept as single units:
+     * e.g., "5th Century" → ["5th", "Century"], "10th Century" → ["10th", "Century"]
+     * Without this, "5th" and "10th" both reduce to "th", causing all "Nth Century"
+     * pages to collide on the same CamelCase variation.
+     */
+    private splitCamelCase;
+    /**
+     * Join space-separated words into CamelCase
+     * e.g., "Health Care" → "HealthCare"
+     */
+    private joinCamelCase;
+    /**
+     * Get all possible plural/singular variations of a page name
+     *
+     * @param pageName - The base page name
+     * @returns Array of possible variations (all lowercase)
+     */
+    getVariations(pageName: string): string[];
+    /**
+     * Check if two page names match (considering plurals and case)
+     *
+     * @param name1 - First page name
+     * @param name2 - Second page name
+     * @returns True if the names match
+     */
+    matches(name1: string, name2: string): boolean;
+    /**
+     * Find a matching page name from a list of existing page names
+     *
+     * @param searchName - The page name to search for
+     * @param existingNames - Array of existing page names (ignored if index is built)
+     * @returns The matching page name, or null if not found
+     */
+    findMatch(searchName: string, existingNames: string[]): string | null;
+    /**
+     * Check if a page name conflicts with any existing pages (considering plurals)
+     * Used when creating new pages to prevent creating "Click" when "Clicks" exists
+     *
+     * @param newPageName - The new page name to check
+     * @param existingNames - Array of existing page names
+     * @returns The conflicting page name, or null if no conflict
+     */
+    findConflict(newPageName: string, existingNames: string[]): string | null;
+}

package/lib/src/utils/PathPreflight.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Preflight a configured filesystem path before anything tries to write to it.
+ *
+ * Detects ONE thing: a macOS `/Volumes/<X>/...` path whose mount is absent,
+ * where `fs.ensureDir` would otherwise crash the engine with an opaque
+ * `EACCES`. A mistyped path elsewhere is not caught at all — #645 tracks
+ * widening it.
+ *
+ * __The platform is injectable, and that is not a convenience.__ The check
+ * runs only on darwin, so on Linux CI the branch was unreachable: every
+ * assertion covering it was guarded by `if (process.platform === 'darwin')`
+ * and silently skipped, while `managerStatus.test.ts` asserted the degraded
+ * state unguarded and failed on every CI run. A test that can only pass on one
+ * developer's operating system is not a test of anything CI can protect, and a
+ * continuously-red check is one nobody reads.
+ *
+ * With the seam, the darwin logic is exercised on every platform, and the
+ * production default is still `process.platform`.
+ */
+export interface PathPreflightResult {
+    ok: boolean;
+    reason?: 'missing-mount';
+    missingMount?: string;
+    message?: string;
+}
+/** Test seams. Production passes none of these. */
+export interface PathPreflightOptions {
+    /**
+     * Which platform to check as. Defaults to the real one.
+     *
+     * Injected rather than stubbed on `process`, because mutating a global for
+     * the duration of a test leaks into anything running in parallel.
+     */
+    platform?: NodeJS.Platform;
+    /** How to test for a mounted directory. Defaults to `fs.statSync`. */
+    isDirectory?: (path: string) => boolean;
+}
+export declare function checkConfiguredPath(p: string | undefined | null, options?: PathPreflightOptions): PathPreflightResult;