@mdfriday/foundry 26.4.19 → 26.5.1

package/dist/types/internal/application/worker/pool-manager.d.ts

@@ -1,24 +1,67 @@
 import { WorkerTask, WorkerResponse } from './worker-main';
+/**
+ * Worker 池配置
+ */
 export interface WorkerPoolConfig {
     workerCount?: number;
     maxQueueSize?: number;
 }
+/**
+ * Worker 环境类型
+ */
 export type WorkerEnvironment = 'node' | 'browser';
+/**
+ * Worker 池管理器
+ * 负责创建和管理 Worker 池，支持 Node.js 和浏览器环境
+ */
 export declare class WorkerPoolManager {
     private pool;
     private environment;
     private workerCount;
     constructor(config?: WorkerPoolConfig);
+    /**
+     * 检测当前运行环境
+     *
+     * 优先检测 Worker 支持能力，而不仅仅依赖 process 对象的存在
+     * 这样可以正确识别 Electron/Obsidian 环境（有 Node.js API 但只支持 Web Workers）
+     */
     private detectEnvironment;
+    /**
+     * 计算最佳 Worker 数量
+     */
     private calculateOptimalWorkerCount;
+    /**
+     * 初始化 Worker 池
+     *
+     * 包含回退机制：如果 Node.js Worker Threads 初始化失败，
+     * 自动回退到 Web Workers（用于 Electron/Obsidian 等环境）
+     */
     initialize(): Promise<void>;
+    /**
+     * 初始化 Node.js Worker 池
+     */
     private initializeNodePool;
+    /**
+     * 初始化浏览器 Worker 池
+     *
+     * 在浏览器环境中，我们不使用文件，而是直接传递函数给 workerpool
+     * workerpool 会自动将函数序列化并在 Worker 中执行
+     */
     private initializeBrowserPool;
+    /**
+     * 执行 Worker 任务
+     */
     exec(task: WorkerTask): Promise<WorkerResponse>;
+    /**
+     * 获取池统计信息
+     */
     getStats(): {
         environment: WorkerEnvironment;
         workerCount: number;
         poolStats: any;
     } | null;
+    /**
+     * 清理 Worker 池
+     */
     terminate(): Promise<void>;
 }

package/dist/types/internal/application/worker/worker-browser.d.ts

@@ -1,3 +1,9 @@
+/**
+ * 浏览器 Web Worker 入口（特殊版本）
+ *
+ * 这个 Worker 运行在 Blob URL 中，通过 postMessage 与主线程通信
+ * 主包的代码通过消息传递或共享内存访问
+ */
 declare const self: {
     addEventListener: (type: string, listener: (event: any) => void) => void;
     postMessage: (message: any) => void;

package/dist/types/internal/application/worker/worker-main.d.ts

@@ -1,14 +1,26 @@
 import { PageTask } from '@pkg/page-filter';
+/**
+ * Worker 任务类型
+ */
 export type WorkerTaskType = 'init' | 'process-batch' | 'stats' | 'cleanup';
+/**
+ * Worker 任务
+ */
 export interface WorkerTask {
     type: WorkerTaskType;
     projDir?: string;
     moduleDir?: string;
     pageTasks?: PageTask[];
 }
+/**
+ * Worker 响应
+ */
 export interface WorkerResponse {
     success: boolean;
     data?: any;
     error?: string | undefined;
 }
+/**
+ * 处理 Worker 任务的主函数
+ */
 export declare function handleWorkerTask(task: WorkerTask): Promise<WorkerResponse>;

package/dist/types/internal/application/worker/worker-state.d.ts

@@ -1,4 +1,7 @@
 import { PageTask } from '@pkg/page-filter';
+/**
+ * 批量渲染结果
+ */
 export interface BatchRenderResult {
     success: boolean;
     processedCount: number;
@@ -6,14 +9,34 @@ export interface BatchRenderResult {
     duration: number;
     errors: string[];
 }
+/**
+ * Worker 状态管理器
+ * 负责初始化和维护 Worker 的 SSG 环境
+ * 每个 Worker 初始化一次，然后复用来处理多个批次
+ */
 export declare class WorkerState {
     private projDir;
     private moduleDir;
     private initialized;
     constructor(projDir: string, moduleDir: string);
+    /**
+     * 初始化 Worker 环境（只执行一次）
+     */
     initialize(): Promise<void>;
+    /**
+     * 处理一个批次的页面任务
+     * 运行完整的 SSG 流程，但通过过滤器只处理指定任务
+     *
+     * @param pageTasks - 包含语言和路径信息的任务列表
+     */
     processBatch(pageTasks: PageTask[]): Promise<BatchRenderResult>;
+    /**
+     * 清理资源
+     */
     cleanup(): Promise<void>;
+    /**
+     * 获取统计信息
+     */
     getStats(): {
         initialized: boolean;
         projDir: string;

package/dist/types/internal/application/workspace.d.ts

@@ -1,38 +1,136 @@
+/**
+ * Application Layer: Workspace Management Service
+ *
+ * 职责：
+ * - 协调多个 domain 之间的交互
+ * - 提供应用级服务（如 Identity 需要 Workspace 存储）
+ * - 不包含业务逻辑（业务逻辑在 Domain 层）
+ */
 import { WorkspaceFactory, Workspace, Project } from '@internal/domain/workspace';
+/**
+ * Application Service Options
+ */
 export interface WorkspaceAppServiceOptions {
     workspaceFactory: WorkspaceFactory;
 }
+/**
+ * Workspace Application Service
+ *
+ * 提供应用层的 Workspace 服务
+ */
 export declare class WorkspaceAppService {
     private workspaceFactory;
     constructor(options: WorkspaceAppServiceOptions);
+    /**
+     * Load workspace from path
+     */
     loadWorkspace(path?: string): Promise<Workspace>;
+    /**
+     * Create new workspace
+     */
     createWorkspace(path: string, options?: Parameters<WorkspaceFactory['create']>[1]): Promise<Workspace>;
+    /**
+     * Save workspace
+     */
     saveWorkspace(workspace: Workspace): Promise<void>;
+    /**
+     * Find workspace root
+     */
     findWorkspaceRoot(startPath?: string): Promise<string | null>;
+    /**
+     * Create project in workspace
+     */
     createProject(workspace: Workspace, name: string, options?: Parameters<WorkspaceFactory['createProject']>[2]): Promise<Project>;
+    /**
+     * Create project from existing folder
+     *
+     * 扫描文件夹结构，识别 content、content.{lang}、static 文件夹
+     * 创建项目并链接到源文件夹
+     */
     createProjectFromFolder(workspace: Workspace, name: string, sourceFolderPath: string, options?: Parameters<WorkspaceFactory['createProjectFromFolder']>[3]): Promise<Project>;
     createProjectFromFile(workspace: Workspace, name: string, sourceFilePath: string, options?: Parameters<WorkspaceFactory['createProjectFromFile']>[3]): Promise<Project>;
+    /**
+     * Delete project from workspace
+     */
     deleteProject(workspace: Workspace, projectIdOrName: string, options?: Parameters<WorkspaceFactory['deleteProject']>[2]): Promise<void>;
+    /**
+     * Load workspace and find project by name or path
+     * Common pattern used by many CLI commands
+     *
+     * 统一行为：
+     * 1. 如果传入 projectNameOrPath，先按项目名查找
+     * 2. 如果按名字找不到，尝试按路径查找（可能是绝对路径）
+     * 3. 如果没传入参数，使用当前目录查找
+     */
     loadWorkspaceAndProject(projectNameOrPath?: string, workspacePath?: string): Promise<{
         workspace: Workspace;
         project: Project;
     }>;
+    /**
+     * Create snapshot for project
+     */
     createSnapshot(project: Project, snapshotName?: string): Promise<import("@internal/domain/workspace").SnapshotMetadata>;
+    /**
+     * List snapshots for project
+     */
     listSnapshots(project: Project): Promise<import("@internal/domain/workspace").SnapshotMetadata[]>;
+    /**
+     * Restore snapshot
+     */
     restoreSnapshot(project: Project, snapshotId: string, outputDir?: string): Promise<void>;
+    /**
+     * Delete snapshot
+     */
     deleteSnapshot(project: Project, snapshotId: string): Promise<void>;
+    /**
+     * Get snapshot metadata
+     */
     getSnapshot(project: Project, snapshotId: string): Promise<import("@internal/domain/workspace").SnapshotMetadata>;
+    /**
+     * Load a single project by path
+     */
     loadProject(projectPath: string): Promise<Project>;
+    /**
+     * Save a single project
+     */
     saveProject(project: Project): Promise<void>;
+    /**
+     * Find project root from current directory
+     */
     findProjectRoot(startPath: string): Promise<string | null>;
+    /**
+     * Scan folder structure
+     *
+     * 扫描文件夹结构，识别 content、content.{lang}、static 文件夹
+     * 用于在创建项目前预览文件夹结构
+     */
     scanFolderStructure(folderPath: string): Promise<import("@internal/domain/workspace").FolderStructure>;
+    /**
+     * Create IdentityStorageProvider for a workspace
+     *
+     * 跨域协调：
+     * - Identity Domain 定义需要什么存储能力 (IdentityStorageProvider)
+     * - Workspace Domain 提供实现
+     * - Application Layer 负责组装
+     */
     createIdentityStorage(workspace: Workspace): import("../domain/identity").IdentityStorageProvider;
+    /**
+     * 设置项目的 baseURL 路径结构
+     * 在 public/ 目录下创建对应的 symlink 结构
+     */
     setupProjectBaseURLStructure(project: Project): Promise<{
         serverRoot: string;
         baseURL: string;
         symlinkCreated: boolean;
     }>;
+    /**
+     * 清理项目的 baseURL 路径结构
+     */
     cleanProjectBaseURLStructure(project: Project): Promise<void>;
+    /**
+     * 确保项目的 baseURL 路径结构正确
+     * 检查 baseURL 是否变化，如需要则重新创建
+     */
     ensureProjectBaseURLStructure(project: Project): Promise<{
         serverRoot: string;
         baseURL: string;

package/dist/types/internal/domain/config/entity/config.d.ts

@@ -8,6 +8,10 @@ import { Language } from './language';
 import { Taxonomy } from './taxonomy';
 import { Dir } from "./dir";
 import { Markdown } from './markdown';
+/**
+ * Config entity that aggregates all configuration components
+ * Matches the golang version structure
+ */
 export declare class Config {
     private configSourceFs;
     private provider;
@@ -24,16 +28,52 @@ export declare class Config {
     getProvider(): Provider;
     theme(): string;
     getDir(): Dir;
+    /**
+     * Get Root entity
+     */
     getRoot(): Root;
+    /**
+     * Get Module entity
+     */
     getModule(): Module;
+    /**
+     * Get Service entity
+     */
     getService(): Service;
+    /**
+     * Get Social entity
+     */
     getSocial(): Social;
+    /**
+     * Get Language entity (optional)
+     */
     getLanguage(): Language;
+    /**
+     * Get Taxonomy entity (optional)
+     */
     getTaxonomy(): Taxonomy;
+    /**
+     * Get Markdown entity
+     */
     getMarkdown(): Markdown;
+    /**
+     * Set Language entity
+     */
     setLanguage(language: Language): void;
+    /**
+     * Set Taxonomy entity
+     */
     setTaxonomy(taxonomy: Taxonomy): void;
+    /**
+     * Set Markdown entity
+     */
     setMarkdown(markdown: Markdown): void;
+    /**
+     * Validate the configuration
+     */
     validate(): boolean;
 }
+/**
+ * Creates a new Config instance
+ */
 export declare function newConfig(configSourceFs: Fs, provider: Provider, root: Root, dir: Dir, module: Module, service: Service, social: Social, language: Language, taxonomy: Taxonomy, markdown: Markdown): Config;

package/dist/types/internal/domain/config/entity/language.d.ts

@@ -1,23 +1,74 @@
 import { LanguageConfig } from '../type';
+/**
+ * Language entity holds language configuration
+ */
 export declare class Language {
     private defaultLang;
     private configs;
     private indices;
     constructor(configs: Record<string, LanguageConfig>);
+    /**
+     * Calculate default language based on weight (smallest weight wins)
+     */
     private calculateDefaultLanguage;
+    /**
+     * Get all language configurations
+     */
     languages(): LanguageConfig[];
+    /**
+     * Get default language
+     */
     defaultLanguage(): string;
+    /**
+     * Check if a language is valid
+     */
     isLanguageValid(lang: string): boolean;
+    /**
+     * Get other language keys (excluding default)
+     */
     otherLanguageKeys(): string[];
+    /**
+     * Get relative directory for a language
+     */
     getRelDir(name: string, langKey: string): string;
+    /**
+     * Validate language configuration
+     */
     validate(): boolean;
+    /**
+     * Set language indices (ordered list)
+     */
     private setIndices;
+    /**
+     * Get language keys in order
+     */
     languageKeys(): string[];
+    /**
+     * Get language indexes
+     */
     languageIndexes(): number[];
+    /**
+     * Get language index by language code
+     */
     getLanguageIndex(lang: string): number;
+    /**
+     * Get language by index
+     */
     getLanguageByIndex(idx: number): string;
+    /**
+     * Get language name by language code
+     */
     getLanguageName(lang: string): string;
+    /**
+     * Get language configuration by language code
+     */
     getLanguageConfig(lang: string): LanguageConfig | undefined;
+    /**
+     * Get all language configurations
+     */
     getConfigs(): Record<string, LanguageConfig>;
 }
+/**
+ * Create a new Language instance from provider data
+ */
 export declare function newLanguage(data: any): Language;

package/dist/types/internal/domain/config/entity/markdown.d.ts

@@ -1,16 +1,52 @@
 import { MarkdownConfig, MarkdownPlugins } from '../type';
+/**
+ * Markdown entity holds markdown renderer configuration
+ */
 export declare class Markdown {
     private markdownConfig;
     constructor(markdownConfig: MarkdownConfig);
+    /**
+     * Check if internal markdown renderer should be used
+     */
     useInternalRenderer(): boolean;
+    /**
+     * Check if wikilink plugin is enabled
+     */
     isWikilinkEnabled(): boolean;
+    /**
+     * Check if tag plugin is enabled
+     */
     isTagEnabled(): boolean;
+    /**
+     * Check if callout plugin is enabled
+     */
     isCalloutEnabled(): boolean;
+    /**
+     * Check if LaTeX plugin is enabled
+     */
     isLatexEnabled(): boolean;
+    /**
+     * Check if Mermaid plugin is enabled
+     */
     isMermaidEnabled(): boolean;
+    /**
+     * Get the markdown configuration
+     */
     getMarkdownConfig(): MarkdownConfig;
+    /**
+     * Get plugin configuration
+     */
     getPlugins(): MarkdownPlugins;
+    /**
+     * Check if any plugin is enabled
+     */
     hasEnabledPlugins(): boolean;
+    /**
+     * Validate the markdown configuration
+     */
     validate(): boolean;
 }
+/**
+ * Create a new Markdown instance from provider data
+ */
 export declare function newMarkdown(data: any): Markdown;

package/dist/types/internal/domain/config/entity/module.d.ts

@@ -1,16 +1,52 @@
 import { ModuleConfig } from '../type';
+/**
+ * Module entity holds module configuration
+ */
 export declare class Module {
     private moduleConfig;
     constructor(moduleConfig: ModuleConfig);
+    /**
+     * Get import paths from module imports
+     */
     importPaths(): string[];
+    /**
+     * Get the module configuration
+     */
     getModuleConfig(): ModuleConfig;
+    /**
+     * Get all imports
+     */
     getImports(): import("../type").Import[];
+    /**
+     * Get all mounts
+     */
     getMounts(): import("../type").Mount[];
+    /**
+     * Get import count
+     */
     importCount(): number;
+    /**
+     * Get mount count
+     */
     mountCount(): number;
+    /**
+     * Check if module has imports
+     */
     hasImports(): boolean;
+    /**
+     * Check if module has mounts
+     */
     hasMounts(): boolean;
+    /**
+     * Find import by path
+     */
     findImport(path: string): import("../type").Import | undefined;
+    /**
+     * Find mount by source
+     */
     findMount(source: string): import("../type").Mount | undefined;
 }
+/**
+ * Create a new Module instance from provider data
+ */
 export declare function newModule(data: any): Module;

package/dist/types/internal/domain/config/entity/root.d.ts

@@ -1,18 +1,57 @@
 import { RootConfig } from '../type';
+/**
+ * Root entity holds the root configuration
+ */
 export declare class Root {
     private rootConfig;
     private rootParams;
     constructor(rootConfig: RootConfig, rootParams?: Record<string, any>);
+    /**
+     * Get the default theme
+     */
     defaultTheme(): string;
+    /**
+     * Get the compiled timeout duration
+     */
     compiledTimeout(): number;
+    /**
+     * Get the base URL
+     */
     baseUrl(): string;
+    /**
+     * Get configuration parameters
+     */
     configParams(): Record<string, any>;
+    /**
+     * Get site title
+     */
     siteTitle(): string;
+    /**
+     * Get the root configuration
+     */
     getRootConfig(): RootConfig;
+    /**
+     * Get theme list
+     */
     getThemes(): string[];
+    /**
+     * Get default content language
+     */
     getDefaultContentLanguage(): string;
+    /**
+     * Check if drafts should be built
+     */
     shouldBuildDrafts(): boolean;
+    /**
+     * Check if future content should be built
+     */
     shouldBuildFuture(): boolean;
+    /**
+     * Check if expired content should be built
+     */
     shouldBuildExpired(): boolean;
 }
+/**
+ * Create a new Root instance from provider data
+ */
 export declare function newRoot(data: any, params?: Record<string, any>): Root;

package/dist/types/internal/domain/config/entity/service.d.ts

@@ -1,19 +1,55 @@
 import { ServiceConfig } from '../type';
+/**
+ * Service entity holds service configuration
+ */
 export declare class Service {
     private serviceConfig;
     constructor(serviceConfig: ServiceConfig);
+    /**
+     * Check if Google Analytics is enabled
+     */
     isGoogleAnalyticsEnabled(): boolean;
+    /**
+     * Get Google Analytics ID
+     */
     googleAnalyticsID(): string;
+    /**
+     * Check if Google Analytics should respect Do Not Track
+     */
     isGoogleAnalyticsRespectDoNotTrack(): boolean;
+    /**
+     * Check if Disqus is enabled
+     */
     isDisqusEnabled(): boolean;
     disqusShortname(): string;
     isXRespectDoNotTrack(): boolean;
     isXDisableInlineCSS(): boolean;
+    /**
+     * Get RSS limit
+     */
     rssLimit(): number;
+    /**
+     * Get the service configuration
+     */
     getServiceConfig(): ServiceConfig;
+    /**
+     * Get Google Analytics configuration
+     */
     getGoogleAnalytics(): import("../type").GoogleAnalytics;
+    /**
+     * Get Disqus configuration
+     */
     getDisqus(): import("../type").Disqus;
+    /**
+     * Get RSS configuration
+     */
     getRSS(): import("../type").RSS;
+    /**
+     * Check if any service is enabled
+     */
     hasEnabledServices(): boolean;
 }
+/**
+ * Create a new Service instance from provider data
+ */
 export declare function newService(data: any): Service;