@mdfriday/foundry 26.4.20 → 26.5.1

package/dist/types/internal/domain/workspace/repository/file-system.d.ts

@@ -1,45 +1,184 @@
+/**
+ * FileSystem Repository Interface
+ *
+ * 定义文件系统操作接口，由 Infrastructure 层实现
+ * 支持不同环境（Node.js, Obsidian）
+ */
+/**
+ * 文件夹扫描结果
+ */
 export interface FolderScanResult {
+    /**
+     * 文件夹路径
+     */
     path: string;
+    /**
+     * 文件夹名称
+     */
     name: string;
+    /**
+     * 是否为文件夹
+     */
     isDirectory: boolean;
+    /**
+     * 是否为文件
+     */
     isFile: boolean;
 }
+/**
+ * 内容文件夹信息
+ */
 export interface ContentFolderInfo {
+    /**
+     * 文件夹路径
+     */
     path: string;
+    /**
+     * 语言代码（如 'en', 'zh', 'ja'）
+     */
     languageCode: string;
+    /**
+     * 权重（用于排序，'content' 为 0，其他为 1）
+     */
     weight: number;
 }
+/**
+ * 静态资源文件夹信息
+ */
 export interface StaticFolderInfo {
+    /**
+     * 文件夹路径
+     */
     path: string;
 }
+/**
+ * 文件夹结构扫描结果
+ */
 export interface FolderStructure {
+    /**
+     * 根文件夹路径
+     */
     rootPath: string;
+    /**
+     * 内容文件夹列表（支持多语言）
+     */
     contentFolders: ContentFolderInfo[];
+    /**
+     * 静态资源文件夹
+     */
     staticFolder: StaticFolderInfo | null;
+    /**
+     * 是否为结构化文件夹（包含 content 或 static）
+     */
     isStructured: boolean;
 }
+/**
+ * 符号链接操作结果
+ */
 export interface SymlinkResult {
+    /**
+     * 源路径
+     */
     source: string;
+    /**
+     * 目标路径
+     */
     target: string;
+    /**
+     * 是否成功
+     */
     success: boolean;
+    /**
+     * 错误信息（如果失败）
+     */
     error?: string;
 }
+/**
+ * FileSystem Repository Interface
+ *
+ * 文件系统操作接口
+ */
 export interface FileSystemRepository {
+    /**
+     * 检查路径是否存在
+     */
     exists(path: string): Promise<boolean>;
+    /**
+     * 检查路径是否为文件夹
+     */
     isDirectory(path: string): Promise<boolean>;
+    /**
+     * 检查路径是否为文件
+     */
     isFile(path: string): Promise<boolean>;
+    /**
+     * 列出文件夹内容
+     *
+     * @param path - 文件夹路径
+     * @returns 文件夹内容列表
+     */
     readDirectory(path: string): Promise<FolderScanResult[]>;
+    /**
+     * 扫描文件夹结构
+     *
+     * 自动识别 content, content.{lang}, static 文件夹
+     *
+     * @param path - 文件夹路径
+     * @returns 文件夹结构信息
+     */
     scanFolderStructure(path: string): Promise<FolderStructure>;
+    /**
+     * 创建符号链接
+     *
+     * @param source - 源路径（实际文件/文件夹）
+     * @param target - 目标路径（符号链接）
+     * @returns 操作结果
+     */
     createSymlink(source: string, target: string): Promise<SymlinkResult>;
+    /**
+     * 批量创建符号链接
+     *
+     * @param links - 链接列表 { source, target }[]
+     * @returns 操作结果列表
+     */
     createSymlinks(links: Array<{
         source: string;
         target: string;
     }>): Promise<SymlinkResult[]>;
+    /**
+     * 删除符号链接
+     *
+     * @param path - 链接路径
+     */
     removeSymlink(path: string): Promise<void>;
+    /**
+     * 检查路径是否为符号链接
+     */
     isSymlink(path: string): Promise<boolean>;
+    /**
+     * 读取符号链接的目标路径
+     */
     readSymlink(path: string): Promise<string>;
+    /**
+     * 创建文件夹
+     *
+     * @param path - 文件夹路径
+     * @param recursive - 是否递归创建父文件夹
+     */
     createDirectory(path: string, recursive?: boolean): Promise<void>;
+    /**
+     * 删除文件或文件夹
+     *
+     * @param path - 路径
+     * @param recursive - 如果是文件夹，是否递归删除
+     */
     remove(path: string, recursive?: boolean): Promise<void>;
+    /**
+     * 获取文件/文件夹状态信息
+     *
+     * @param path - 路径
+     * @returns 状态信息
+     */
     stat(path: string): Promise<{
         isFile(): boolean;
         isDirectory(): boolean;
@@ -47,18 +186,103 @@ export interface FileSystemRepository {
         size: number;
         mtime: Date;
     }>;
+    /**
+     * 拷贝文件
+     *
+     * @param source - 源文件路径
+     * @param target - 目标文件路径
+     */
     copyFile(source: string, target: string): Promise<void>;
+    /**
+     * 读取文件内容
+     *
+     * @param path - 文件路径
+     * @param encoding - 编码格式（默认 'utf-8'）
+     * @returns 文件内容
+     */
     readFile(path: string, encoding?: BufferEncoding): Promise<string>;
+    /**
+     * 写入文件内容
+     *
+     * @param path - 文件路径
+     * @param content - 文件内容
+     * @param encoding - 编码格式（默认 'utf-8'）
+     */
     writeFile(path: string, content: string, encoding?: BufferEncoding): Promise<void>;
+    /**
+     * 删除文件
+     *
+     * @param path - 文件路径
+     */
     unlink(path: string): Promise<void>;
+    /**
+     * 检查路径访问权限
+     *
+     * @param path - 路径
+     * @throws 如果路径不存在或无权限访问
+     */
     access(path: string): Promise<void>;
+    /**
+     * 解析路径（处理相对路径、符号链接等）
+     *
+     * @param path - 原始路径
+     * @returns 绝对路径
+     */
     resolvePath(path: string): Promise<string>;
+    /**
+     * 删除文件或目录
+     *
+     * @param targetPath - 要删除的路径
+     * @param recursive - 是否递归删除（用于目录）
+     */
     remove(targetPath: string, recursive?: boolean): Promise<void>;
+    /**
+     * 获取路径的文件名
+     */
     basename(path: string): string;
+    /**
+     * 获取路径的父文件夹
+     */
     dirname(path: string): string;
+    /**
+     * 连接路径
+     */
     join(...paths: string[]): string;
+    /**
+     * 解析为绝对路径（同步版本）
+     *
+     * 不涉及文件系统 I/O，纯路径计算
+     *
+     * @param paths - 路径片段
+     * @returns 绝对路径
+     *
+     * @example
+     * resolvePathSync('/foo/bar', '../baz') // '/foo/baz'
+     * resolvePathSync('foo/bar') // '/current/working/dir/foo/bar'
+     */
     resolvePathSync(...paths: string[]): string;
+    /**
+     * 计算相对路径
+     *
+     * @param from - 起始路径
+     * @param to - 目标路径
+     * @returns 从 from 到 to 的相对路径
+     *
+     * @example
+     * relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
+     * // '../../impl/bbb'
+     */
     relative(from: string, to: string): string;
+    /**
+     * 解析路径信息
+     *
+     * @param path - 路径
+     * @returns 路径的根目录、目录名、文件名、扩展名等信息
+     *
+     * @example
+     * parsePath('/home/user/dir/file.txt')
+     * // { root: '/', dir: '/home/user/dir', base: 'file.txt', ext: '.txt', name: 'file' }
+     */
     parsePath(path: string): {
         root: string;
         dir: string;
@@ -66,6 +290,23 @@ export interface FileSystemRepository {
         ext: string;
         name: string;
     };
+    /**
+     * 规范化路径
+     *
+     * 解析 '..' 和 '.'，去除多余的分隔符
+     *
+     * @param path - 路径
+     * @returns 规范化后的路径
+     *
+     * @example
+     * normalize('/foo/bar//baz/asdf/quux/..') // '/foo/bar/baz/asdf'
+     */
     normalize(path: string): string;
+    /**
+     * 判断路径是否为绝对路径
+     *
+     * @param path - 路径
+     * @returns 是否为绝对路径
+     */
     isAbsolute(path: string): boolean;
 }

package/dist/types/internal/domain/workspace/repository/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Workspace Domain Repository Interfaces
+ *
+ * 定义 Workspace Domain 需要的外部能力接口
+ * 由 Infrastructure 层提供具体实现
+ */
 export * from '../repository';
 export type { ProjectRegistry, ProjectEntry, BuildHistoryEntry } from '../type';
 export * from './file-system';

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

@@ -1,3 +1,9 @@
+/**
+ * Workspace Repository Interface
+ *
+ * 定义 Workspace 数据持久化的接口
+ * 具体实现由 infrastructure 层提供
+ */
 import type { ProjectRegistry, SnapshotMetadata } from './type';
 export * from './repository/file-system';
 export type WorkspaceMetadataData = {
@@ -25,28 +31,94 @@ export type ProjectMetadataData = {
     buildHistory?: any[];
     previews?: any;
 };
+/**
+ * Workspace Repository
+ */
 export interface WorkspaceRepository {
+    /**
+     * 检查目录是否为 workspace
+     */
     isWorkspace(path: string): Promise<boolean>;
+    /**
+     * 初始化 workspace 目录结构
+     */
     initWorkspaceStructure(path: string, modulesDir: string, projectsDir: string): Promise<void>;
+    /**
+     * 保存 workspace 元数据
+     */
     saveWorkspaceMetadata(path: string, metadata: WorkspaceMetadataData): Promise<void>;
+    /**
+     * 加载 workspace 元数据
+     */
     loadWorkspaceMetadata(path: string): Promise<WorkspaceMetadataData>;
+    /**
+     * 保存项目注册表
+     */
     saveProjectRegistry(path: string, registry: ProjectRegistry): Promise<void>;
+    /**
+     * 加载项目注册表
+     */
     loadProjectRegistry(path: string): Promise<ProjectRegistry>;
 }
+/**
+ * Project Repository
+ */
 export interface ProjectRepository {
+    /**
+     * 检查目录是否为 project
+     */
     isProject(path: string): Promise<boolean>;
+    /**
+     * 初始化 project 目录结构
+     */
     initProjectStructure(path: string, contentDir: string, staticDir: string, publishDir: string): Promise<void>;
+    /**
+     * 保存 project 元数据
+     */
     saveProjectMetadata(path: string, metadata: ProjectMetadataData): Promise<void>;
+    /**
+     * 加载 project 元数据
+     */
     loadProjectMetadata(path: string): Promise<ProjectMetadataData>;
+    /**
+     * 保存 project 配置
+     */
     saveProjectConfig(path: string, config: any): Promise<void>;
+    /**
+     * 创建示例内容
+     */
     createSampleContent(path: string, content: string): Promise<void>;
+    /**
+     * 删除 project 文件
+     */
     deleteProjectFiles(path: string): Promise<void>;
+    /**
+     * 删除 project 目录
+     */
     deleteProjectDirectory(path: string): Promise<void>;
 }
+/**
+ * Snapshot Repository
+ */
 export interface SnapshotRepository {
+    /**
+     * 创建快照（复制输出目录到快照存储）
+     */
     createSnapshot(projectPath: string, snapshotId: string, outputDir: string): Promise<SnapshotMetadata>;
+    /**
+     * 列出所有快照
+     */
     listSnapshots(projectPath: string): Promise<SnapshotMetadata[]>;
+    /**
+     * 获取快照元数据
+     */
     getSnapshot(projectPath: string, snapshotId: string): Promise<SnapshotMetadata>;
+    /**
+     * 恢复快照（从快照存储复制到输出目录）
+     */
     restoreSnapshot(projectPath: string, snapshotId: string, outputDir: string): Promise<void>;
+    /**
+     * 删除快照
+     */
     deleteSnapshot(projectPath: string, snapshotId: string): Promise<void>;
 }

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

@@ -1,3 +1,9 @@
+/**
+ * Workspace Domain Types
+ */
+/**
+ * Project registry entry
+ */
 export interface ProjectEntry {
     id: string;
     name: string;
@@ -9,10 +15,16 @@ export interface ProjectEntry {
     lastBuild?: number;
     status: 'active' | 'archived';
 }
+/**
+ * Project registry
+ */
 export interface ProjectRegistry {
     version: string;
     projects: ProjectEntry[];
 }
+/**
+ * Build history entry
+ */
 export interface BuildHistoryEntry {
     timestamp: number;
     type: 'build' | 'publish';
@@ -25,6 +37,9 @@ export interface BuildHistoryEntry {
         size?: number;
     };
 }
+/**
+ * Snapshot metadata
+ */
 export interface SnapshotMetadata {
     id: string;
     name: string;
@@ -34,6 +49,9 @@ export interface SnapshotMetadata {
     size: number;
     fileCount: number;
 }
+/**
+ * Previews configuration
+ */
 export interface PreviewsConfig {
     autoSnapshot?: boolean;
     retention?: number;

package/dist/types/internal/domain/workspace/value-object/folder-structure.d.ts

@@ -1,12 +1,27 @@
 import type { FolderStructure as IFolderStructure, ContentFolderInfo, StaticFolderInfo } from '../repository/file-system';
+/**
+ * FolderStructure Value Object
+ *
+ * 表示文件夹结构扫描结果
+ * 包含 content 文件夹（支持多语言）和 static 文件夹
+ */
 export declare class FolderStructure {
     private readonly rootPath;
     private readonly contentFolders;
     private readonly staticFolder;
     private readonly isStructured;
     private constructor();
+    /**
+     * 从扫描结果创建 FolderStructure
+     */
     static fromScanResult(result: IFolderStructure): FolderStructure;
+    /**
+     * 创建空的 FolderStructure（非结构化文件夹）
+     */
     static createEmpty(rootPath: string): FolderStructure;
+    /**
+     * 创建单个 content 文件夹的结构
+     */
     static createSingleContent(rootPath: string, contentPath: string, languageCode?: string): FolderStructure;
     getRootPath(): string;
     getContentFolders(): ContentFolderInfo[];
@@ -15,13 +30,39 @@ export declare class FolderStructure {
     hasContentFolders(): boolean;
     hasStaticFolder(): boolean;
     getContentFolderCount(): number;
+    /**
+     * 获取默认 content 文件夹（weight 为 0 的文件夹）
+     */
     getDefaultContentFolder(): ContentFolderInfo | null;
+    /**
+     * 获取多语言 content 文件夹（weight > 0 的文件夹）
+     */
     getLanguageContentFolders(): ContentFolderInfo[];
+    /**
+     * 按语言代码获取 content 文件夹
+     */
     getContentFolderByLanguage(languageCode: string): ContentFolderInfo | null;
+    /**
+     * 获取所有支持的语言代码
+     */
     getSupportedLanguages(): string[];
+    /**
+     * 验证结构是否有效
+     *
+     * 结构化文件夹必须至少有一个 content 文件夹
+     */
     isValid(): boolean;
+    /**
+     * 是否为多语言项目
+     */
     isMultilingual(): boolean;
+    /**
+     * 获取结构摘要（用于日志和显示）
+     */
     getSummary(): string;
     toJSON(): IFolderStructure;
+    /**
+     * 从 JSON 反序列化
+     */
     static fromJSON(json: IFolderStructure): FolderStructure;
 }

package/dist/types/internal/domain/workspace/value-object/project-metadata.d.ts

@@ -1,19 +1,53 @@
+/**
+ * 内容链接信息
+ */
 export interface ContentLink {
+    /**
+     * 源路径（实际文件夹）
+     */
     sourcePath: string;
+    /**
+     * 语言代码
+     */
     languageCode: string;
+    /**
+     * 权重（用于排序）
+     */
     weight: number;
 }
+/**
+ * 静态资源链接信息
+ */
 export interface StaticLink {
+    /**
+     * 源路径（实际文件夹）
+     */
     sourcePath: string;
 }
+/**
+ * 单文件链接信息
+ */
 export interface FileLink {
+    /**
+     * 源文件路径（实际文件）
+     */
     sourcePath: string;
+    /**
+     * 目标文件路径（项目中的链接/拷贝）
+     */
     targetPath: string;
+    /**
+     * 是否为符号链接（false表示是拷贝）
+     */
     isSymlink: boolean;
 }
+/**
+ * Project Metadata Value Object
+ */
 export declare class ProjectMetadata {
     readonly id: string;
     readonly name: string;
+    readonly type: string;
     readonly workspaceId: string;
     readonly createdAt: number;
     readonly updatedAt: number;
@@ -46,6 +80,7 @@ export declare class ProjectMetadata {
     static create(data: {
         id: string;
         name: string;
+        type?: string;
         workspaceId?: string;
         createdAt: number;
         updatedAt: number;
@@ -57,6 +92,7 @@ export declare class ProjectMetadata {
     }): ProjectMetadata;
     update(updates: Partial<{
         name: string;
+        type: string;
         buildHistory: any[];
         previews: any;
         contentLinks: ContentLink[];

package/dist/types/internal/domain/workspace/value-object/workspace-metadata.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Workspace Metadata Value Object
+ * Immutable representation of workspace configuration
+ */
 export declare class WorkspaceMetadata {
     readonly version: string;
     readonly id: string;
@@ -30,6 +34,9 @@ export declare class WorkspaceMetadata {
             language?: string;
         };
     }): WorkspaceMetadata;
+    /**
+     * Update with new values (creates new instance)
+     */
     update(updates: Partial<{
         name: string;
         paths: {

package/dist/types/internal/infrastructure/embedding/embedding-provider.interface.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Embedding Provider Interface (Infrastructure Layer)
+ *
+ * 继承自 Domain 层的 IEmbeddingProvider（generateEmbedding），
+ * 在此基础上增加 infrastructure 层的能力：embed、embedBatch、healthCheck。
+ *
+ * 所有具体 Embedding 实现类（LMStudioProvider、OllamaEmbeddingProvider 等）
+ * 实现此 infrastructure 接口后，同时自动满足 domain 层合约。
+ */
+import type { IEmbeddingProvider as DomainEmbeddingProvider } from '@internal/domain/wiki/repository/embedding-provider';
+export type { DomainEmbeddingProvider };
+export interface EmbedRequest {
+    text: string;
+    model?: string;
+    signal?: AbortSignal;
+}
+export interface EmbedResponse {
+    embedding: number[];
+}
+export interface IEmbeddingProvider extends DomainEmbeddingProvider {
+    /**
+     * 生成单条文本的向量嵌入（infrastructure 主要入口）
+     */
+    embed(request: EmbedRequest): Promise<number[]>;
+    /**
+     * 批量生成向量嵌入（可选，默认串行调用 embed）
+     */
+    embedBatch?(texts: string[]): Promise<number[][]>;
+    /**
+     * 健康检查（可选）
+     */
+    healthCheck?(): Promise<boolean>;
+}

package/dist/types/internal/infrastructure/embedding/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Embedding Infrastructure
+ */
+export * from './embedding-provider.interface';
+export * from './ollama-embedding-provider';

package/dist/types/internal/infrastructure/embedding/ollama-embedding-provider.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Ollama Embedding Provider
+ *
+ * 使用 Ollama 的 Embedding API
+ * 模型: nomic-embed-text (nomic-ai/nomic-embed-text-v2-moe-GGUF)
+ */
+import type { IEmbeddingProvider, EmbedRequest } from './embedding-provider.interface';
+export interface OllamaEmbeddingConfig {
+    baseUrl: string;
+    model: string;
+    timeout?: number;
+}
+export declare class OllamaEmbeddingProvider implements IEmbeddingProvider {
+    private config;
+    constructor(config: OllamaEmbeddingConfig);
+    /**
+     * Domain IEmbeddingProvider interface: generateEmbedding(text, model)
+     * Bridges the domain contract to the infrastructure embed() method.
+     */
+    generateEmbedding(text: string, model: string): Promise<number[]>;
+    embed(request: EmbedRequest): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    healthCheck(): Promise<boolean>;
+}