@mdfriday/foundry 26.4.19 → 26.5.1

package/dist/types/internal/domain/workspace/entity/project.d.ts

@@ -1,6 +1,9 @@
 import { ProjectMetadata } from '../value-object/project-metadata';
 import { BuildHistoryEntry } from '../type';
 import { FileSystemRepository } from '../repository/file-system';
+/**
+ * Project Configuration Interface
+ */
 export interface ProjectConfig {
     baseURL?: string;
     title?: string;
@@ -13,37 +16,149 @@ export interface ProjectConfig {
     }>;
     [key: string]: any;
 }
+/**
+ * Project Entity
+ * Represents a single MDFriday project within a workspace
+ */
 export declare class Project {
     private metadata;
     private projectPath;
     private config;
     private fileSystemRepo;
     constructor(projectPath: string, metadata: ProjectMetadata, fileSystemRepo: FileSystemRepository);
+    /**
+     * Get project path
+     */
     getPath(): string;
+    /**
+     * Get project metadata
+     */
     getMetadata(): ProjectMetadata;
+    /**
+     * Get project ID
+     */
     getId(): string;
+    /**
+     * Get project name
+     */
     getName(): string;
+    /**
+     * Get project type
+     */
+    getType(): string;
+    /**
+     * Get workspace ID
+     */
     getWorkspaceId(): string | undefined;
+    /**
+     * Get build history
+     */
     getBuildHistory(): BuildHistoryEntry[];
+    /**
+     * Add build history entry
+     */
     addBuildHistory(entry: BuildHistoryEntry): void;
+    /**
+     * Get last build timestamp
+     */
     getLastBuildTime(): number | undefined;
+    /**
+     * Update project name
+     */
     updateName(name: string): void;
+    /**
+     * Load project configuration
+     */
     loadConfig(): Promise<ProjectConfig>;
+    /**
+     * Get project configuration (cached)
+     */
     getConfig(): ProjectConfig | null;
+    /**
+     * Get content directories (支持多语言)
+     * Returns absolute paths
+     */
     getContentDirs(): Promise<string[]>;
+    /**
+     * Get publish directory (output directory)
+     * Returns absolute path
+     */
     getPublishDir(): Promise<string>;
+    /**
+     * Get static directory
+     * Returns absolute path
+     */
     getStaticDir(): string;
+    /**
+     * Get default content language
+     */
     getDefaultLanguage(): Promise<string>;
+    /**
+     * Get all configured languages
+     */
     getLanguages(): Promise<string[]>;
+    /**
+     * Get project configuration file path
+     */
     getConfigPath(): string;
+    /**
+     * Get configuration value by key (supports nested keys with dot notation)
+     */
     getConfigValue(key: string): any;
+    /**
+     * Set configuration value (supports nested keys with dot notation)
+     */
     setConfigValue(key: string, value: any): void;
+    /**
+     * Set entire configuration object (replaces current config)
+     *
+     * This method replaces the entire configuration with the provided object.
+     * Useful for bulk updates to avoid race conditions from multiple writes.
+     */
     setConfig(config: ProjectConfig): void;
+    /**
+     * Unset configuration value (supports nested keys with dot notation)
+     */
     unsetConfigValue(key: string): boolean;
+    /**
+     * Save current configuration to file
+     */
     saveConfig(): Promise<void>;
     private getNestedValue;
     private setNestedValue;
     private deleteNestedValue;
+    /**
+     * 读取项目根目录下的文件
+     *
+     * @param filename - 文件名（相对于项目根目录），如 'kb.json'
+     * @param encoding - 编码格式，默认 'utf-8'
+     * @returns 文件内容
+     */
+    readFile(filename: string, encoding?: BufferEncoding): Promise<string>;
+    /**
+     * 写入项目根目录下的文件
+     * 若父目录不存在则自动创建
+     *
+     * @param filename - 文件名（相对于项目根目录），如 'kb.json'
+     * @param content - 文件内容
+     * @param encoding - 编码格式，默认 'utf-8'
+     */
+    writeFile(filename: string, content: string, encoding?: BufferEncoding): Promise<void>;
+    /**
+     * 检查项目根目录下的文件是否存在
+     *
+     * @param filename - 文件名（相对于项目根目录）
+     */
+    fileExists(filename: string): Promise<boolean>;
+    /**
+     * 获取项目根目录下文件的绝对路径
+     *
+     * @param filename - 文件名（相对于项目根目录）
+     */
+    getFilePath(filename: string): string;
+    /**
+     * Get project info for display
+     */
     getInfo(): {
         id: string;
         name: string;
@@ -53,38 +168,90 @@ export declare class Project {
         lastBuild?: Date;
         buildCount: number;
     };
+    /**
+     * Get snapshots directory path
+     */
     getSnapshotsDir(): string;
+    /**
+     * 检查项目是否有源文件夹链接
+     */
     hasSourceLinks(): boolean;
+    /**
+     * 获取内容链接信息
+     */
     getContentLinks(): Array<{
         sourcePath: string;
         languageCode: string;
         weight: number;
     }>;
+    /**
+     * 获取静态资源链接信息
+     */
     getStaticLink(): {
         sourcePath: string;
     } | null;
+    /**
+     * 获取文件链接信息（单文件项目）
+     */
     getFileLink(): {
         sourcePath: string;
         targetPath: string;
         isSymlink: boolean;
     } | null;
+    /**
+     * 设置内容链接
+     */
     setContentLinks(links: Array<{
         sourcePath: string;
         languageCode: string;
         weight: number;
     }>): void;
+    /**
+     * 设置静态资源链接
+     */
     setStaticLink(link: {
         sourcePath: string;
     } | null): void;
+    /**
+     * 添加内容链接
+     */
     addContentLink(sourcePath: string, languageCode: string, weight: number): void;
+    /**
+     * 获取默认内容源路径（weight 为 0）
+     */
     getDefaultContentSource(): string | null;
+    /**
+     * 获取所有内容源路径
+     */
     getAllContentSources(): string[];
+    /**
+     * 按语言代码获取内容源路径
+     */
     getContentSourceByLanguage(languageCode: string): string | null;
+    /**
+     * 获取项目支持的所有语言
+     */
     getSupportedLanguagesFromLinks(): string[];
+    /**
+     * 检查是否为链接项目（从外部文件夹创建）
+     */
     isLinkedProject(): boolean;
+    /**
+     * 获取所有链接的源路径（包括 fileLink 和 contentLinks）
+     * Returns absolute paths to original source files/folders
+     */
     getLinkDirs(): string[];
+    /**
+     * 获取 baseURL（从 Hugo config.json）
+     */
     getBaseURL(): Promise<string>;
+    /**
+     * 设置 baseURL（更新 Hugo config.json）
+     */
     setBaseURL(baseURL: string): Promise<void>;
+    /**
+     * 解析 baseURL 路径信息
+     */
     parseBaseURLPath(baseURL: string): {
         isRoot: boolean;
         pathParts: string[];
@@ -92,11 +259,17 @@ export declare class Project {
         finalDirName: string;
         relativeToPublic: string;
     };
+    /**
+     * 获取当前 baseURL 结构信息
+     */
     getBaseURLStructure(): {
         baseURL: string;
         createdAt: number;
         pathParts: string[];
     } | null;
+    /**
+     * 更新 baseURL 结构记录
+     */
     updateBaseURLStructure(info: {
         baseURL: string;
         createdAt: number;

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

@@ -3,6 +3,15 @@ import { ProjectRegistry } from '../type';
 import { Project } from './project';
 import { Authentication } from './authentication';
 import { FileSystemRepository } from '../repository/file-system';
+/**
+ * Workspace Entity (Aggregate Root)
+ *
+ * 聚合根：
+ * - 持有所有 Project entities
+ * - 持有 Authentication entity
+ * - 统一对外提供服务
+ * - 确保数据一致性
+ */
 export declare class Workspace {
     private readonly rootPath;
     private metadata;
@@ -10,33 +19,109 @@ export declare class Workspace {
     private authentication;
     private fileSystemRepo;
     constructor(rootPath: string, metadata: WorkspaceMetadata, projects: Map<string, Project>, authentication: Authentication, fileSystemRepo: FileSystemRepository);
+    /**
+     * Get workspace root path
+     */
     getPath(): string;
+    /**
+     * Get workspace metadata (Value Object)
+     */
     getMetadata(): WorkspaceMetadata;
+    /**
+     * Get workspace ID
+     */
     getId(): string;
+    /**
+     * Get workspace name
+     */
     getName(): string;
+    /**
+     * Get modules directory path
+     */
     getModulesDir(): string;
+    /**
+     * Get projects directory path
+     */
     getProjectsDir(): string;
+    /**
+     * Update workspace metadata (creates new Value Object)
+     */
     updateMetadata(updates: Parameters<WorkspaceMetadata['update']>[0]): void;
+    /**
+     * Update workspace name
+     */
     updateName(name: string): void;
+    /**
+     * Get all projects (entities)
+     */
     getProjects(): Project[];
+    /**
+     * Get project by ID
+     */
     getProject(projectId: string): Project | undefined;
+    /**
+     * Get project by name
+     */
     getProjectByName(name: string): Project | undefined;
+    /**
+     * Get project by ID or name
+     */
     findProject(idOrName: string): Project | undefined;
+    /**
+     * Check if project exists
+     */
     hasProject(projectId: string): boolean;
+    /**
+     * Add project to workspace (aggregate root responsibility)
+     */
     addProject(project: Project): void;
+    /**
+     * Remove project from workspace (aggregate root responsibility)
+     */
     removeProject(projectId: string): Project | null;
+    /**
+     * Get project count
+     */
     getProjectCount(): number;
+    /**
+     * Generate project registry from current project entities
+     * This is used by Repository for persistence
+     */
     getProjectRegistry(): ProjectRegistry;
+    /**
+     * Get authentication entity (file system manager)
+     */
     getAuthentication(): Authentication;
+    /**
+     * Check if workspace has authentication file
+     */
     hasAuthentication(): boolean;
+    /**
+     * Get workspace configuration file path
+     */
     getConfigPath(): string;
+    /**
+     * Get configuration value by key (supports nested keys with dot notation)
+     */
     getConfig(key: string): Promise<any>;
+    /**
+     * Get all workspace configuration
+     */
     getAllConfig(): Promise<any>;
+    /**
+     * Set configuration value (supports nested keys with dot notation)
+     */
     setConfig(key: string, value: any): Promise<void>;
+    /**
+     * Unset configuration value (supports nested keys with dot notation)
+     */
     unsetConfig(key: string): Promise<boolean>;
     private getNestedValue;
     private setNestedValue;
     private deleteNestedValue;
+    /**
+     * Get workspace info for display
+     */
     getInfo(): {
         id: string;
         name: string;

package/dist/types/internal/domain/workspace/factory/workspace-factory.d.ts

@@ -1,33 +1,73 @@
+/**
+ * Workspace Factory
+ *
+ * 负责构建和持久化 Workspace 聚合根
+ * - 从文件系统加载完整的 Workspace（包含所有 Project entities）
+ * - 创建新的 Workspace
+ * - 保存 Workspace 到文件系统
+ */
 import { Workspace } from '../entity/workspace';
 import { Project } from '../entity/project';
 import { FolderStructure } from '../value-object/folder-structure';
 import { WorkspaceRepository, ProjectRepository, SnapshotRepository, FileSystemRepository } from '../repository';
 import { SnapshotMetadata } from '../type';
 import type { IdentityStorageProvider } from '@internal/domain/identity/repository/index';
+/**
+ * Workspace Factory Options
+ */
 export interface WorkspaceFactoryOptions {
     workspaceRepo: WorkspaceRepository;
     projectRepo: ProjectRepository;
     snapshotRepo: SnapshotRepository;
     fileSystemRepo: FileSystemRepository;
 }
+/**
+ * Workspace Factory
+ */
 export declare class WorkspaceFactory {
     private workspaceRepo;
     private projectRepo;
     private snapshotRepo;
     private fileSystemRepo;
     constructor(options: WorkspaceFactoryOptions);
+    /**
+     * Load workspace from file system
+     * Returns fully constructed Workspace aggregate root with all Project entities
+     */
     load(rootPath: string): Promise<Workspace>;
+    /**
+     * Check if auth file exists
+     */
     private checkAuthFile;
+    /**
+     * Create a new workspace
+     */
     create(rootPath: string, options?: {
         name?: string;
         modulesDir?: string;
         projectsDir?: string;
     }): Promise<Workspace>;
+    /**
+     * Save workspace aggregate root to file system
+     */
     save(workspace: Workspace): Promise<void>;
+    /**
+     * Find workspace root by searching up the directory tree
+     */
     findWorkspaceRoot(startPath: string): Promise<string | null>;
+    /**
+     * Check if a path is a workspace
+     */
     isWorkspace(workspacePath: string): Promise<boolean>;
+    /**
+     * Load or find workspace from current directory
+     */
     loadOrFind(cwd?: string): Promise<Workspace>;
+    /**
+     * Create a new project in workspace
+     */
     createProject(workspace: Workspace, name: string, options?: {
+        type?: string;
         theme?: string;
         language?: string;
         contentDir?: string;
@@ -35,37 +75,104 @@ export declare class WorkspaceFactory {
         publishDir?: string;
         baseURL?: string;
     }): Promise<Project>;
+    /**
+     * Delete project from workspace
+     */
     deleteProject(workspace: Workspace, projectIdOrName: string, options?: {
         deleteFiles?: boolean;
     }): Promise<void>;
+    /**
+     * Create a new project from existing folder
+     *
+     * 扫描文件夹结构，识别 content、content.{lang}、static 文件夹
+     * 创建项目并链接到源文件夹
+     */
     createProjectFromFolder(workspace: Workspace, name: string, sourceFolderPath: string, options?: {
+        type?: string;
         theme?: string;
         language?: string;
     }): Promise<Project>;
+    /**
+     * Create a new project from a single file
+     *
+     * 支持从单个 Markdown 文件创建项目
+     * 优先尝试创建符号链接，失败时回退到文件拷贝
+     */
     createProjectFromFile(workspace: Workspace, name: string, sourceFilePath: string, options?: {
+        type?: string;
         theme?: string;
         language?: string;
     }): Promise<Project>;
+    /**
+     * 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>;
+    /**
+     * Create snapshot for a project
+     */
     createSnapshot(project: Project, snapshotName?: string): Promise<SnapshotMetadata>;
+    /**
+     * List snapshots for a project
+     */
     listSnapshots(project: Project): Promise<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<SnapshotMetadata>;
+    /**
+     * Create IdentityStorageProvider adapter for a workspace
+     *
+     * 依赖倒置实现：
+     * - Identity Domain 定义 IdentityStorageProvider 接口（它需要什么）
+     * - Workspace Domain 提供实现（如何存储）
+     * - 允许 Identity 将认证信息存储在 Workspace 中
+     */
     createIdentityStorage(workspace: Workspace): IdentityStorageProvider;
+    /**
+     * 在 public/ 目录下创建 baseURL 访问路径结构
+     *
+     * 例如：baseURL = "/blog/" 时，在 public/ 下创建 blog/ -> . (symlink)
+     */
     setupBaseURLStructure(project: Project): Promise<{
         serverRoot: string;
         baseURL: string;
         symlinkCreated: boolean;
     }>;
+    /**
+     * 清理 public/ 下的 baseURL 路径结构
+     */
     cleanBaseURLStructure(project: Project): Promise<void>;
+    /**
+     * 确保 baseURL 结构正确
+     * 检查 baseURL 是否变化，如需要则重新创建
+     */
     ensureBaseURLStructure(project: Project): Promise<{
         serverRoot: string;
         baseURL: string;
         recreated: boolean;
     }>;
+    /**
+     * Scan folder structure
+     *
+     * 扫描文件夹结构，识别 content、content.{lang}、static 文件夹
+     * 用于在创建项目前预览文件夹结构
+     */
     scanFolderStructure(folderPath: string): Promise<FolderStructure>;
     private createSampleContent;
 }