@mdfriday/foundry 26.4.19 → 26.5.1

package/dist/types/internal/infrastructure/persistence/node-snapshot-repository.d.ts

@@ -1,12 +1,40 @@
 import { SnapshotRepository } from '@internal/domain/workspace/repository';
 import { SnapshotMetadata } from '@internal/domain/workspace/type';
+/**
+ * Node.js implementation of Snapshot Repository
+ * Handles snapshot creation, listing, restoration and deletion using fs
+ */
 export declare class NodeSnapshotRepository implements SnapshotRepository {
+    /**
+     * Create a snapshot by copying output directory to snapshot storage
+     */
     createSnapshot(projectPath: string, snapshotId: string, outputDir: string): Promise<SnapshotMetadata>;
+    /**
+     * List all snapshots for a project
+     */
     listSnapshots(projectPath: string): Promise<SnapshotMetadata[]>;
+    /**
+     * Get snapshot metadata
+     */
     getSnapshot(projectPath: string, snapshotId: string): Promise<SnapshotMetadata>;
+    /**
+     * Restore a snapshot by copying from storage to output directory
+     */
     restoreSnapshot(projectPath: string, snapshotId: string, outputDir: string): Promise<void>;
+    /**
+     * Delete a snapshot
+     */
     deleteSnapshot(projectPath: string, snapshotId: string): Promise<void>;
+    /**
+     * Copy directory recursively
+     */
     private copyDirectory;
+    /**
+     * Get total size of directory in bytes
+     */
     private getDirectorySize;
+    /**
+     * Count files in directory recursively
+     */
     private countFiles;
 }

package/dist/types/internal/infrastructure/persistence/node-workspace-repository.d.ts

@@ -1,5 +1,11 @@
+/**
+ * Node.js File System Implementation of Workspace Repository
+ */
 import { WorkspaceRepository, ProjectRepository, WorkspaceMetadataData, ProjectMetadataData } from '@internal/domain/workspace/repository';
 import { ProjectRegistry } from '@internal/domain/workspace/type';
+/**
+ * Node.js implementation of WorkspaceRepository
+ */
 export declare class NodeWorkspaceRepository implements WorkspaceRepository {
     isWorkspace(workspacePath: string): Promise<boolean>;
     initWorkspaceStructure(workspacePath: string, modulesDir: string, projectsDir: string): Promise<void>;
@@ -8,6 +14,9 @@ export declare class NodeWorkspaceRepository implements WorkspaceRepository {
     saveProjectRegistry(workspacePath: string, registry: ProjectRegistry): Promise<void>;
     loadProjectRegistry(workspacePath: string): Promise<ProjectRegistry>;
 }
+/**
+ * Node.js implementation of ProjectRepository
+ */
 export declare class NodeProjectRepository implements ProjectRepository {
     isProject(projectPath: string): Promise<boolean>;
     initProjectStructure(projectPath: string, contentDir: string, staticDir: string, publishDir: string): Promise<void>;

package/dist/types/pkg/cahce/cache.d.ts

@@ -1,34 +1,90 @@
+/**
+ * 并发安全的缓存实现，专为站点构建场景优化
+ * 支持多个页面并发访问时避免重复创建相同对象
+ */
 export declare class ConcurrentCache<K, V> {
     private cache;
     private pendingPromises;
     private deletedKeys;
     constructor();
+    /**
+     * Get value from cache
+     */
     get(key: K): V | undefined;
+    /**
+     * Set value in cache
+     */
     set(key: K, value: V): void;
+    /**
+     * Check if key exists in cache
+     */
     has(key: K): boolean;
+    /**
+     * Check if key is currently being created
+     */
     isPending(key: K): boolean;
+    /**
+     * Remove key from cache
+     */
     delete(key: K): boolean;
+    /**
+     * Clear all cache entries and pending promises
+     */
     clear(): void;
+    /**
+     * Get cache size
+     */
     size(): number;
+    /**
+     * Get pending promises count
+     */
     pendingCount(): number;
+    /**
+     * 并发安全的获取或创建值
+     * 如果多个并发请求访问同一个key，只会创建一次
+     */
     getOrCreate(key: K, create: (key: K) => Promise<V>): Promise<V>;
+    /**
+     * 创建并缓存值
+     */
     private createAndCache;
+    /**
+     * 执行创建函数，包装错误处理
+     */
     private executeCreate;
+    /**
+     * 获取缓存统计信息
+     */
     getStats(): CacheStats;
+    /**
+     * 批量预加载数据
+     */
     preload(entries: Array<{
         key: K;
         create: (key: K) => Promise<V>;
     }>): Promise<void>;
 }
+/**
+ * 缓存统计信息
+ */
 export interface CacheStats {
     size: number;
     pendingCount: number;
     keys: unknown[];
     pendingKeys: unknown[];
 }
+/**
+ * DynaCache interface implementation
+ */
 export interface DynaCache<K, V> {
     getOrCreate(key: K, create: (key: K) => Promise<V>): Promise<V>;
     getStats?(): CacheStats;
 }
+/**
+ * 创建一个新的并发缓存实例
+ */
 export declare function createCache<K, V>(): ConcurrentCache<K, V>;
+/**
+ * 全局缓存实例，用于站点构建时的数据共享
+ */
 export declare const globalBuildCache: ConcurrentCache<string, any>;

package/dist/types/pkg/lang/data.d.ts

@@ -1,6 +1,27 @@
+/**
+ * Language Data
+ * Contains mapping of language codes to language names with direction support
+ */
 import { LanguageInfo } from './types';
+/**
+ * LTR (Left-to-Right) Languages
+ * Currently supported languages that read from left to right
+ */
 export declare const LTR_LANGUAGES: LanguageInfo[];
+/**
+ * RTL (Right-to-Left) Languages
+ * Languages that read from right to left (to be supported in the future)
+ */
 export declare const RTL_LANGUAGES: LanguageInfo[];
+/**
+ * All supported languages (LTR + RTL)
+ */
 export declare const ALL_LANGUAGES: LanguageInfo[];
+/**
+ * Create a map of language code to language info
+ */
 export declare const LANGUAGE_MAP: Record<string, LanguageInfo>;
+/**
+ * Create a simple code-to-name mapping
+ */
 export declare const CODE_NAME_MAP: Record<string, string>;

package/dist/types/pkg/lang/index.d.ts

@@ -1,18 +1,64 @@
+/**
+ * Language Package
+ * Basic language code to name mapping service with LTR/RTL support
+ */
 export type { LanguageDirection, LanguageInfo, LanguageService } from './types';
 export { LTR_LANGUAGES, RTL_LANGUAGES, ALL_LANGUAGES, LANGUAGE_MAP, CODE_NAME_MAP } from './data';
 export { DefaultLanguageService, getLanguageService, createLanguageService } from './service';
+/**
+ * Default language service instance
+ */
 export declare const lang: import("./types").LanguageService;
+/**
+ * Convenience functions using the default service
+ */
 export declare const languages: {
+    /**
+     * Get all language codes
+     */
     getAllCodes: () => string[];
+    /**
+     * Get all language names
+     */
     getAllNames: () => string[];
+    /**
+     * Get language codes by direction
+     */
     getCodesByDirection: (direction: "ltr" | "rtl") => string[];
+    /**
+     * Get language names by direction
+     */
     getNamesByDirection: (direction: "ltr" | "rtl") => string[];
+    /**
+     * Get code-name mapping
+     */
     getCodeNameMap: () => Record<string, string>;
+    /**
+     * Get code-name mapping by direction
+     */
     getCodeNameMapByDirection: (direction: "ltr" | "rtl") => Record<string, string>;
+    /**
+     * Get language name by code
+     */
     getNameByCode: (code: string) => string | undefined;
+    /**
+     * Get language info by code
+     */
     getLanguageInfo: (code: string) => import("./types").LanguageInfo | undefined;
+    /**
+     * Check if language is supported
+     */
     isSupported: (code: string) => boolean;
+    /**
+     * Get language direction
+     */
     getDirection: (code: string) => import("./types").LanguageDirection | undefined;
+    /**
+     * Check if language is LTR
+     */
     isLTR: (code: string) => boolean;
+    /**
+     * Check if language is RTL
+     */
     isRTL: (code: string) => boolean;
 };

package/dist/types/pkg/lang/service.d.ts

@@ -1,17 +1,66 @@
+/**
+ * Language Service Implementation
+ * Provides methods to query language information
+ */
 import { LanguageInfo, LanguageDirection, LanguageService } from './types';
+/**
+ * Default implementation of LanguageService
+ */
 export declare class DefaultLanguageService implements LanguageService {
+    /**
+     * Get all supported language codes
+     */
     getAllCodes(): string[];
+    /**
+     * Get all supported language names
+     */
     getAllNames(): string[];
+    /**
+     * Get language codes for a specific direction
+     */
     getCodesByDirection(direction: LanguageDirection): string[];
+    /**
+     * Get language names for a specific direction
+     */
     getNamesByDirection(direction: LanguageDirection): string[];
+    /**
+     * Get code-to-name mapping for all languages
+     */
     getCodeNameMap(): Record<string, string>;
+    /**
+     * Get code-to-name mapping for a specific direction
+     */
     getCodeNameMapByDirection(direction: LanguageDirection): Record<string, string>;
+    /**
+     * Get language name by code
+     */
     getNameByCode(code: string): string | undefined;
+    /**
+     * Get complete language information by code
+     */
     getLanguageInfo(code: string): LanguageInfo | undefined;
+    /**
+     * Check if a language code is supported
+     */
     isSupported(code: string): boolean;
+    /**
+     * Get language direction by code
+     */
     getDirection(code: string): LanguageDirection | undefined;
+    /**
+     * Check if a language is LTR (Left-to-Right)
+     */
     isLTR(code: string): boolean;
+    /**
+     * Check if a language is RTL (Right-to-Left)
+     */
     isRTL(code: string): boolean;
 }
+/**
+ * Get the singleton language service instance
+ */
 export declare function getLanguageService(): LanguageService;
+/**
+ * Create a new language service instance
+ */
 export declare function createLanguageService(): LanguageService;

package/dist/types/pkg/lang/types.d.ts

@@ -1,21 +1,50 @@
+/**
+ * Language Package Types
+ * Basic language code to name mapping with LTR/RTL support
+ */
+/**
+ * Language direction type
+ */
 export type LanguageDirection = 'ltr' | 'rtl';
+/**
+ * Language information interface
+ */
 export interface LanguageInfo {
+    /** Language code (ISO 639-1) */
     code: string;
+    /** Native language name */
     name: string;
+    /** Language direction */
     direction: LanguageDirection;
+    /** English name (optional, for reference) */
     englishName?: string;
 }
+/**
+ * Language service interface
+ */
 export interface LanguageService {
+    /** Get all language codes */
     getAllCodes(): string[];
+    /** Get all language names */
     getAllNames(): string[];
+    /** Get all language codes for a specific direction */
     getCodesByDirection(direction: LanguageDirection): string[];
+    /** Get all language names for a specific direction */
     getNamesByDirection(direction: LanguageDirection): string[];
+    /** Get code-name mapping for all languages */
     getCodeNameMap(): Record<string, string>;
+    /** Get code-name mapping for a specific direction */
     getCodeNameMapByDirection(direction: LanguageDirection): Record<string, string>;
+    /** Get language name by code */
     getNameByCode(code: string): string | undefined;
+    /** Get language information by code */
     getLanguageInfo(code: string): LanguageInfo | undefined;
+    /** Check if a language code is supported */
     isSupported(code: string): boolean;
+    /** Get language direction by code */
     getDirection(code: string): LanguageDirection | undefined;
+    /** Check if a language is LTR */
     isLTR(code: string): boolean;
+    /** Check if a language is RTL */
     isRTL(code: string): boolean;
 }

package/dist/types/pkg/log/http.d.ts

@@ -2,8 +2,24 @@ import { Logger } from './logger';
 export declare class HTTPErrorLogger {
     private logger;
     constructor(logger: Logger);
+    /**
+     * Process HTTP error messages and log them appropriately
+     * Similar to Go's httpErrorLog.Write method
+     */
     write(message: string): void;
+    /**
+     * Create a write stream compatible function for HTTP servers
+     * This can be used with HTTP server error handlers
+     */
     getWriteFunction(): (message: string) => void;
+    /**
+     * Create a Node.js compatible writable stream interface
+     * This allows the logger to be used where a writable stream is expected
+     */
     createWritableStream(): NodeJS.WritableStream;
 }
+/**
+ * Create a new HTTP error logger
+ * Similar to Go's NewHTTPErrorLog function
+ */
 export declare function NewHTTPErrorLogger(logger: Logger): HTTPErrorLogger;

package/dist/types/pkg/log/manager.d.ts

@@ -1,26 +1,83 @@
 import { Logger } from './logger';
 import { LogLevel, LoggerConfig } from './types';
+/**
+ * Global Logger Manager
+ * Manages logger instances across different domains with unified configuration
+ */
 export declare class LoggerManager {
     private static instance;
     private globalConfig;
     private loggers;
     private constructor();
+    /**
+     * Get the singleton instance of LoggerManager
+     */
     static getInstance(): LoggerManager;
+    /**
+     * Set global logger configuration
+     * This affects all new logger instances created after this call
+     */
     setGlobalConfig(config: Partial<LoggerConfig>): void;
+    /**
+     * Get global logger configuration
+     */
     getGlobalConfig(): LoggerConfig;
+    /**
+     * Get logger for a specific domain/component
+     * Creates and caches logger instances per domain
+     */
     getLogger(domain: string, additionalFields?: Record<string, any>): Logger;
+    /**
+     * Get logger for a specific domain with component information
+     */
     getComponentLogger(domain: string, component: string, additionalFields?: Record<string, any>): Logger;
+    /**
+     * Clear all cached loggers
+     * Useful when you want to force recreation with new configuration
+     */
     clearCache(): void;
+    /**
+     * Get all cached logger domains
+     */
     getCachedDomains(): string[];
+    /**
+     * Set log level for all existing and future loggers
+     */
     setLogLevel(level: LogLevel): void;
+    /**
+     * Enable or disable caller information for all loggers
+     */
     setCallerEnabled(enabled: boolean): void;
+    /**
+     * Set JSON format for all loggers
+     */
     setJsonFormat(enabled: boolean): void;
 }
 declare const globalLoggerManager: LoggerManager;
+/**
+ * Initialize global logger configuration
+ * Call this once at application startup
+ */
 export declare function initLogger(config: Partial<LoggerConfig>): void;
+/**
+ * Get logger for a domain
+ * Convenience function to avoid accessing LoggerManager directly
+ */
 export declare function getDomainLogger(domain: string, additionalFields?: Record<string, any>): Logger;
+/**
+ * Get logger for a specific component within a domain
+ */
 export declare function getComponentLogger(domain: string, component: string, additionalFields?: Record<string, any>): Logger;
+/**
+ * Set global log level
+ */
 export declare function setGlobalLogLevel(level: LogLevel): void;
+/**
+ * Enable or disable caller information globally
+ */
 export declare function setGlobalCallerEnabled(enabled: boolean): void;
+/**
+ * Set JSON format globally
+ */
 export declare function setGlobalJsonFormat(enabled: boolean): void;
 export { globalLoggerManager };

package/dist/types/pkg/maps/scratch.d.ts

@@ -1,13 +1,38 @@
+/**
+ * Scratch is a writable context used for stateful operations in Page/Node rendering.
+ * TypeScript equivalent of Go's maps.Scratch
+ */
 export declare class Scratch {
     private values;
     constructor();
+    /**
+     * Add will, for single values, add (using the + operator) the addend to the existing addend (if found).
+     * Supports numeric values and strings.
+     * If the first add for a key is an array or slice, then the next value(s) will be appended.
+     */
     add(key: string, newAddend: any): string;
     Add(key: string, newAddend: any): string;
+    /**
+     * Set stores a value with the given key in the Node context.
+     * This value can later be retrieved with Get.
+     */
     set(key: string, value: any): string;
     Set(key: string, value: any): string;
+    /**
+     * Delete deletes the given key.
+     */
     delete(key: string): string;
+    /**
+     * Get returns a value previously set by Add or Set.
+     */
     get(key: string): any;
     Get(key: string): any;
+    /**
+     * Values returns the raw backing map.
+     */
     getValues(): Map<string, any>;
+    /**
+     * SetInMap stores a value to a map with the given key in the Node context.
+     */
     setInMap(key: string, mapKey: string, value: any): string;
 }

package/dist/types/pkg/md/parser/item.d.ts

@@ -33,12 +33,12 @@ export declare class Item {
 export declare enum ItemType {
     tError = 0,
     tEOF = 1,
-    TypeLeadSummaryDivider = 2,
+    TypeLeadSummaryDivider = 2,// <!--more-->,  # more
     TypeFrontMatterYAML = 3,
     TypeFrontMatterTOML = 4,
     TypeFrontMatterJSON = 5,
     TypeFrontMatterORG = 6,
-    TypeIgnore = 7,
+    TypeIgnore = 7,// The BOM Unicode byte order marker and possibly others
     tLeftDelimScNoMarkup = 8,
     tRightDelimScNoMarkup = 9,
     tLeftDelimScWithMarkup = 10,
@@ -49,7 +49,7 @@ export declare enum ItemType {
     tScParam = 15,
     tScParamVal = 16,
     tIndentation = 17,
-    tText = 18,
+    tText = 18,// plain text
     tKeywordMarker = 19
 }
 export type Items = Item[];

package/dist/types/pkg/media/type.d.ts

@@ -1,14 +1,23 @@
 export interface SuffixInfo {
+    /** Suffix without the delimiter, e.g. "xml" */
     suffix: string;
+    /** Full suffix with delimiter, e.g. ".xml" */
     fullSuffix: string;
 }
 export declare class MediaType {
+    /** Full MIME type string, e.g. "application/rss+xml" */
     type: string;
+    /** Main type, e.g. "application" */
     mainType: string;
+    /** Subtype, e.g. "rss" */
     subType: string;
+    /** Delimiter before the suffix, e.g. "." */
     delimiter: string;
+    /** First suffix (not exposed to external JSON) */
     firstSuffix: SuffixInfo;
+    /** Optional MIME suffix after "+", e.g. "xml" */
     private mimeSuffix;
+    /** CSV of alternative suffixes, for internal comparison only */
     private suffixesCSV;
     constructor(init: {
         type: string;
@@ -19,7 +28,17 @@ export declare class MediaType {
         mimeSuffix: string;
         suffixesCSV: string;
     });
+    /**
+     * Returns the subtype part of the MIME type.
+     * If subType is empty, try to extract it from the full type string.
+     */
     sub(): string;
+    /**
+     * Returns the MIME suffix, e.g. "xml" from "application/rss+xml"
+     */
     getMimeSuffix(): string | undefined;
+    /**
+     * Returns the list of suffixes if defined.
+     */
     getSuffixList(): string[];
 }

package/dist/types/pkg/page-filter/index.d.ts

@@ -1,14 +1,43 @@
+/**
+ * 页面任务：包含语言和路径信息
+ */
 export interface PageTask {
     language: string;
     pagePath: string;
 }
+/**
+ * 全局页面过滤器
+ * 纯工具类，用于控制哪些页面需要处理
+ *
+ * 统一模式：始终使用 (language, pagePath) 对进行过滤
+ */
 declare class PageFilterManager {
     private filterSet;
     private currentLanguage;
+    /**
+     * 设置页面过滤器
+     * @param tasks Array of {language, pagePath}
+     */
     setFilter(tasks: PageTask[]): void;
+    /**
+     * 设置当前处理的语言
+     */
     setCurrentLanguage(language: string): void;
+    /**
+     * 清除过滤器
+     */
     clearFilter(): void;
+    /**
+     * 检查是否应该处理此页面 (O(1) 查找)
+     *
+     * @param language 语言代码
+     * @param pagePath 页面路径
+     * @returns true 如果应该处理，false 如果应该跳过
+     */
     shouldProcess(language: string, pagePath: string): boolean;
+    /**
+     * 获取过滤器大小
+     */
     getFilterSize(): number;
 }
 export declare const pageFilter: PageFilterManager;

package/dist/types/pkg/paths/index.d.ts

@@ -1,4 +1,13 @@
+/**
+ * Sanitize a string for use in URLs
+ */
 export declare function sanitize(input: string): string;
+/**
+ * Add context root to a path
+ */
 export declare function addContextRoot(root: string, path: string): string;
+/**
+ * Create a permalink by joining base URL and path
+ */
 export declare function makePermalink(baseURL: string, path: string): URL;
 export declare function dir(s: string): string;

package/dist/types/pkg/text/index.d.ts

@@ -1 +1,5 @@
+/**
+ * Remove accents from a string
+ * Converts characters like é, è, ë to e
+ */
 export declare function removeAccentsString(str: string): string;

package/dist/types/pkg/web/server/livereload-server.d.ts

@@ -1,4 +1,11 @@
 import { LiveReloadConfig, LiveReloadServer } from './types';
+/**
+ * Node.js 环境下的 LiveReload 服务器实现
+ * 使用 WebSocket 进行实时通信
+ *
+ * 对于 Electron 环境，请使用 ElectronLiveReloadServer
+ * 或通过 createLiveReloadServer() 工厂函数自动选择合适的实现
+ */
 export declare class FoundryLiveReloadServer implements LiveReloadServer {
     private httpServer;
     private wsServer;

package/dist/types/pkg/web/watcher/content-file-watcher.d.ts

@@ -8,6 +8,9 @@ export declare class ContentFileWatcher implements FileWatcher {
     private callbacks;
     private isSingleFileMode;
     constructor(config: WatcherConfig);
+    /**
+     * 检测是否所有路径都是单个文件
+     */
     private detectSingleFileMode;
     startWatching(): Promise<void>;
     onFileChange(callback: (events: FileChangeEvent[]) => Promise<void>): void;