@mdfriday/foundry 26.4.19 → 26.5.1

package/dist/types/internal/domain/publish/repository/manifest-repository.d.ts

@@ -1,7 +1,34 @@
 import { PublishManifest } from '../value-object/publish-manifest';
+/**
+ * Manifest Repository Interface
+ *
+ * 管理发布清单的持久化
+ */
 export interface ManifestRepository {
+    /**
+     * Load manifest for a project and publish method
+     * Returns null if manifest doesn't exist
+     *
+     * @param projectPath
+     * @param publishMethod
+     * @param suffix - Optional suffix for manifest file (e.g., 'free', 'custom' for mdfriday)
+     */
     loadManifest(projectPath: string, publishMethod: 'ftp' | 'netlify' | 'mdfriday', suffix?: string): Promise<PublishManifest | null>;
+    /**
+     * Save manifest after successful publish
+     *
+     * @param projectPath
+     * @param manifest
+     * @param suffix - Optional suffix for manifest file (e.g., 'free', 'custom' for mdfriday)
+     */
     saveManifest(projectPath: string, manifest: PublishManifest, suffix?: string): Promise<void>;
+    /**
+     * Generate manifest from directory
+     * Scans all files in publicDir and creates manifest
+     */
     generateManifest(projectId: string, publicDir: string, publishMethod: 'ftp' | 'netlify' | 'mdfriday', remoteConfig?: any): Promise<PublishManifest>;
+    /**
+     * Delete manifest
+     */
     deleteManifest(projectPath: string, publishMethod: 'ftp' | 'netlify' | 'mdfriday', suffix?: string): Promise<boolean>;
 }

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

@@ -1,4 +1,15 @@
+/**
+ * Publish Domain Types
+ *
+ * 发布领域的核心类型定义
+ */
+/**
+ * Publish Type
+ */
 export type PublishType = 'ftp' | 'netlify' | 'mdfriday';
+/**
+ * Progress Info
+ */
 export interface PublishProgressInfo {
     phase: 'scanning' | 'uploading' | 'deploying' | 'complete';
     percentage: number;
@@ -9,7 +20,13 @@ export interface PublishProgressInfo {
     bytesTransferred?: number;
     bytesTotal?: number;
 }
+/**
+ * Progress Callback
+ */
 export type PublishProgressCallback = (progress: PublishProgressInfo) => void;
+/**
+ * Publish Result
+ */
 export interface PublishResult {
     success: boolean;
     url?: string;
@@ -18,9 +35,15 @@ export interface PublishResult {
     duration: number;
     error?: string;
 }
+/**
+ * Base Publish Config
+ */
 export interface BasePublishConfig {
     type: PublishType;
 }
+/**
+ * FTP Publish Config
+ */
 export interface FtpPublishConfig extends BasePublishConfig {
     type: 'ftp';
     host: string;
@@ -30,11 +53,17 @@ export interface FtpPublishConfig extends BasePublishConfig {
     remotePath: string;
     secure: boolean;
 }
+/**
+ * Netlify Publish Config
+ */
 export interface NetlifyPublishConfig extends BasePublishConfig {
     type: 'netlify';
     accessToken: string;
     siteId: string;
 }
+/**
+ * MDFriday Publish Config
+ */
 export interface MDFridayPublishConfig extends BasePublishConfig {
     type: 'mdfriday';
     apiUrl?: string;
@@ -44,17 +73,37 @@ export interface MDFridayPublishConfig extends BasePublishConfig {
     accessToken?: string;
     licenseKey?: string;
 }
+/**
+ * Any Publish Config
+ */
 export type AnyPublishConfig = FtpPublishConfig | NetlifyPublishConfig | MDFridayPublishConfig;
+/**
+ * Publisher Interface (Strategy)
+ *
+ * 定义发布策略的接口
+ */
 export interface Publisher {
+    /**
+     * Execute publish
+     */
     publish(sourceDir: string, options?: {
         incremental?: boolean;
         force?: boolean;
         onProgress?: PublishProgressCallback;
     }): Promise<PublishResult>;
+    /**
+     * Test connection (optional)
+     */
     testConnection?(): Promise<{
         success: boolean;
         error?: string;
     }>;
+    /**
+     * Get config
+     */
     getConfig(): AnyPublishConfig;
+    /**
+     * Get type
+     */
     getType(): PublishType;
 }

package/dist/types/internal/domain/publish/value-object/ftp-publisher.d.ts

@@ -1,22 +1,52 @@
 import { Publisher, PublishType, FtpPublishConfig, PublishResult, PublishProgressCallback } from '../type';
 import { ManifestRepository } from '../repository/manifest-repository';
+/**
+ * FTP Publisher Strategy (Value Object)
+ *
+ * FTP 发布策略实现 - 参考 Obsidian Friday 的成熟实现
+ */
 export declare class FtpPublisher implements Publisher {
     private readonly config;
     private readonly manifestRepo;
     private readonly projectId;
     private readonly projectPath;
     constructor(config: FtpPublishConfig, manifestRepo: ManifestRepository, projectId: string, projectPath: string);
+    /**
+     * Execute FTP publish
+     */
     publish(sourceDir: string, options?: {
         incremental?: boolean;
         onProgress?: PublishProgressCallback;
     }): Promise<PublishResult>;
+    /**
+     * Test FTP connection
+     */
     testConnection(): Promise<{
         success: boolean;
         error?: string;
     }>;
+    /**
+     * Get config
+     */
     getConfig(): FtpPublishConfig;
+    /**
+     * Get type
+     */
     getType(): PublishType;
+    /**
+     * Connect with automatic fallback
+     * Try plain FTP first (faster), then FTPS if that fails
+     * 参考 Friday 的 connectWithFallback 实现
+     */
     private connectWithFallback;
+    /**
+     * Upload a single file with retry mechanism
+     * This handles the case where a previous upload left a 0-byte file on the server
+     * 参考 Friday 的 uploadFileWithRetry 实现
+     */
     private uploadFileWithRetry;
+    /**
+     * Get file lists (changed and deleted)
+     */
     private getFileLists;
 }

package/dist/types/internal/domain/publish/value-object/mdfriday-publisher.d.ts

@@ -1,6 +1,12 @@
 import { Publisher, PublishType, MDFridayPublishConfig, PublishResult, PublishProgressCallback } from '../type';
 import { ManifestRepository } from '../repository/manifest-repository';
 import { HttpClient } from '../repository/http-client';
+/**
+ * MDFriday Publisher Strategy (Value Object)
+ *
+ * Publishes to MDFriday platform (share/sub/custom/enterprise)
+ * Follows DDD principles like FTP and Netlify publishers
+ */
 export declare class MDFridayPublisher implements Publisher {
     private readonly config;
     private readonly manifestRepo;
@@ -8,23 +14,74 @@ export declare class MDFridayPublisher implements Publisher {
     private readonly projectId;
     private readonly projectPath;
     constructor(config: MDFridayPublishConfig, manifestRepo: ManifestRepository, httpClient: HttpClient, projectId: string, projectPath: string);
+    /**
+     * Execute MDFriday publish
+     */
     publish(sourceDir: string, options?: {
         incremental?: boolean;
         onProgress?: PublishProgressCallback;
     }): Promise<PublishResult>;
+    /**
+     * Test MDFriday connection
+     */
     testConnection(): Promise<{
         success: boolean;
         error?: string;
     }>;
+    /**
+     * Get config
+     */
     getConfig(): MDFridayPublishConfig;
+    /**
+     * Get type
+     */
     getType(): PublishType;
+    /**
+     * Get file lists for incremental or full publish
+     * Similar to FtpPublisher.getFileLists()
+     *
+     * @returns changedFiles - Files that are new or modified
+     * @returns allFiles - All current files in sourceDir
+     */
     private getFileLists;
+    /**
+     * Create incremental ZIP containing only specified files
+     * Maintains directory structure
+     */
     private createIncrementalZip;
+    /**
+     * Create ZIP file from directory
+     * Similar to old Netlify implementation
+     */
     private createZipFromDirectory;
+    /**
+     * Upload ZIP to MDFriday
+     *
+     * POST /api/mdf/preview?type=MDFPreview
+     * FormData with: type, path, id, name, size, asset
+     */
     private uploadToMDFriday;
+    /**
+     * Deploy preview
+     *
+     * POST /api/mdf/preview/deploy?type=MDFPreview&id={id}
+     * FormData with: type, id, host_name, license_key
+     */
     private deployPreview;
+    /**
+     * Build multipart form data for upload
+     */
     private buildFormData;
+    /**
+     * Get API URL
+     */
     private getApiUrl;
+    /**
+     * Simulate upload progress
+     */
     private simulateUploadProgress;
+    /**
+     * Format bytes to human-readable string
+     */
     private formatBytes;
 }

package/dist/types/internal/domain/publish/value-object/netlify-publisher.d.ts

@@ -1,6 +1,15 @@
 import { Publisher, PublishType, NetlifyPublishConfig, PublishResult, PublishProgressCallback } from '../type';
 import { ManifestRepository } from '../repository/manifest-repository';
 import { HttpClient } from '../repository/http-client';
+/**
+ * Netlify Publisher Strategy (Value Object)
+ *
+ * Uses Netlify's recommended Digest Deploy API with file-level uploads
+ * Follows DDD principles:
+ * - Domain logic in this class
+ * - Infrastructure services injected (ManifestRepository, HttpClient)
+ * - Similar architecture to FTP Publisher
+ */
 export declare class NetlifyPublisher implements Publisher {
     private readonly config;
     private readonly manifestRepo;
@@ -8,21 +17,67 @@ export declare class NetlifyPublisher implements Publisher {
     private readonly projectId;
     private readonly projectPath;
     constructor(config: NetlifyPublishConfig, manifestRepo: ManifestRepository, httpClient: HttpClient, projectId: string, projectPath: string);
+    /**
+     * Execute Netlify publish using Digest Deploy API
+     */
     publish(sourceDir: string, options?: {
         incremental?: boolean;
         onProgress?: PublishProgressCallback;
     }): Promise<PublishResult>;
+    /**
+     * Test Netlify connection
+     */
     testConnection(): Promise<{
         success: boolean;
         error?: string;
     }>;
+    /**
+     * Get config
+     */
     getConfig(): NetlifyPublishConfig;
+    /**
+     * Get type
+     */
     getType(): PublishType;
+    /**
+     * Get file lists (changed and unchanged)
+     * Similar to FTP implementation
+     */
     private getFileLists;
+    /**
+     * Create deploy with file digests
+     *
+     * POST /sites/:site_id/deploys
+     * Body: { files: { "path": "sha1_hash", ... } }
+     *
+     * IMPORTANT: Netlify returns { required: ["sha1_hash1", "sha1_hash2"] }
+     * The required array contains SHA1 hashes, NOT file paths!
+     * We need to create a reverse mapping: hash → filepath
+     */
     private createDeployWithDigests;
+    /**
+     * Upload required files
+     *
+     * PUT /deploys/:deploy_id/files/:path
+     * Content-Type: application/octet-stream
+     * Body: file_binary_content
+     */
     private uploadRequiredFiles;
+    /**
+     * Upload a single file with retry mechanism
+     * Similar to FTP implementation
+     */
     private uploadFileWithRetry;
+    /**
+     * Wait for deployment to be ready
+     */
     private waitForDeployment;
+    /**
+     * Get the site URL
+     */
     private getSiteUrl;
+    /**
+     * Format bytes to human-readable string
+     */
     private formatBytes;
 }

package/dist/types/internal/domain/publish/value-object/publish-config.d.ts

@@ -1,3 +1,6 @@
+/**
+ * FTP Configuration Value Object
+ */
 export interface FTPConfig {
     host: string;
     port: number;
@@ -6,16 +9,27 @@ export interface FTPConfig {
     remotePath: string;
     secure: boolean;
 }
+/**
+ * Netlify Configuration Value Object
+ */
 export interface NetlifyConfig {
     accessToken: string;
     siteId: string;
 }
+/**
+ * MDFriday Configuration Value Object
+ */
 export interface MDFridayConfig {
     enabled: boolean;
     type: 'share' | 'sub' | 'custom' | 'enterprise';
     autoPublish: boolean;
     licenseKey?: string;
 }
+/**
+ * Workspace Publish Configuration Value Object
+ *
+ * 从 workspace global config 中提取发布配置
+ */
 export declare class WorkspacePublishConfig {
     readonly ftp?: FTPConfig;
     readonly netlify?: NetlifyConfig;
@@ -25,12 +39,36 @@ export declare class WorkspacePublishConfig {
         netlify?: NetlifyConfig;
         mdfriday?: MDFridayConfig;
     });
+    /**
+     * Check if FTP is configured
+     */
     hasFTP(): boolean;
+    /**
+     * Check if Netlify is configured
+     */
     hasNetlify(): boolean;
+    /**
+     * Check if MDFriday is configured
+     */
     hasMDFriday(): boolean;
+    /**
+     * Get FTP config
+     */
     getFTPConfig(): FTPConfig | null;
+    /**
+     * Get Netlify config
+     */
     getNetlifyConfig(): NetlifyConfig | null;
+    /**
+     * Get MDFriday config
+     */
     getMDFridayConfig(): MDFridayConfig | null;
+    /**
+     * Create from global workspace config
+     */
     static fromGlobalConfig(globalConfig: any): WorkspacePublishConfig;
+    /**
+     * Merge with command-line config override
+     */
     merge(override: Partial<FTPConfig | NetlifyConfig | MDFridayConfig>, method: 'ftp' | 'netlify' | 'mdfriday'): WorkspacePublishConfig;
 }

package/dist/types/internal/domain/publish/value-object/publish-manifest.d.ts

@@ -1,9 +1,18 @@
+/**
+ * Manifest File Entry
+ * 表示已发布文件的元数据
+ */
 export interface ManifestFileEntry {
     hash: string;
     size: number;
     mtime: number;
     relativePath: string;
 }
+/**
+ * Publish Manifest Value Object
+ *
+ * 发布清单，记录已发布的文件信息，用于增量发布
+ */
 export declare class PublishManifest {
     private readonly projectId;
     private readonly publishMethod;
@@ -17,18 +26,59 @@ export declare class PublishManifest {
         files: Map<string, ManifestFileEntry> | Record<string, ManifestFileEntry>;
         remoteConfig?: any;
     });
+    /**
+     * Get project ID
+     */
     getProjectId(): string;
+    /**
+     * Get publish method
+     */
     getPublishMethod(): string;
+    /**
+     * Get last publish time
+     */
     getLastPublishTime(): number;
+    /**
+     * Get remote config
+     */
     getRemoteConfig(): any;
+    /**
+     * Get all file paths
+     */
     getAllFiles(): string[];
+    /**
+     * Get file entry
+     */
     getFile(relativePath: string): ManifestFileEntry | undefined;
+    /**
+     * Check if file exists
+     */
     hasFile(relativePath: string): boolean;
+    /**
+     * Get total file count
+     */
     getFileCount(): number;
+    /**
+     * Get changed files compared to new manifest
+     * Returns files that are new or have different hash
+     */
     getChangedFiles(newManifest: PublishManifest): string[];
+    /**
+     * Get deleted files compared to new manifest
+     * Returns files that exist in old manifest but not in new
+     */
     getDeletedFiles(newManifest: PublishManifest): string[];
+    /**
+     * Serialize to JSON
+     */
     toJSON(): any;
+    /**
+     * Deserialize from JSON
+     */
     static fromJSON(json: any): PublishManifest;
+    /**
+     * Create new manifest
+     */
     static create(data: {
         projectId: string;
         publishMethod: 'ftp' | 'netlify' | 'mdfriday';

package/dist/types/internal/domain/resources/entity/http.d.ts

@@ -1,6 +1,17 @@
+/**
+ * HttpClient for fetching remote content via HTTP/HTTPS
+ * Uses Node.js http/https modules to avoid CORS issues in Obsidian plugin environment
+ * Focuses solely on HTTP requests and returns string content
+ */
 export declare class HttpClient {
     private defaultTimeout;
     private defaultHeaders;
+    /**
+     * Fetch content from a remote URI using Node.js http/https modules
+     * @param uri - The URI to fetch content from
+     * @param options - Optional request configuration
+     * @returns Promise<string | null> - The fetched content as string or null if failed
+     */
     fromRemote(uri: string, options?: {
         headers?: Record<string, string>;
         timeout?: number;

package/dist/types/internal/domain/resources/entity/integrity.d.ts

@@ -1,4 +1,8 @@
 import { Resource } from '../type';
+/**
+ * IntegrityClient provides fingerprinting and integrity generation for resources
+ * This implements the Fingerprint operation
+ */
 export declare class IntegrityClient {
     fingerprint(resource: Resource, algo?: string): Promise<Resource>;
     generateIntegrity(content: string): string;

package/dist/types/internal/domain/resources/entity/minifier.d.ts

@@ -1,4 +1,8 @@
 import { Resource, MinifierClient as IMinifierClient } from '../type';
+/**
+ * MinifierClient for minification of Resource objects. Supported minifiers are:
+ * css, html, js, json, svg and xml.
+ */
 export declare class MinifierClient implements IMinifierClient {
     private minifiers;
     minifyOutput: boolean;

package/dist/types/internal/domain/resources/entity/publisher.d.ts

@@ -1,12 +1,36 @@
 import { URLConfig } from '../type';
 import { Fs, File } from '../../fs/type';
+/**
+ * Publisher for Resources domain
+ * TypeScript equivalent of golang/internal/domain/resources/entity/publisher.go
+ */
 export declare class Publisher {
     private pubFs;
     private urlSvc;
     constructor(pubFs: Fs, urlSvc: URLConfig);
+    /**
+     * PublishContentToTarget publishes string content to target path
+     * TypeScript equivalent of PublishContentToTarget method from Go
+     */
+    /**
+     * OpenPublishFileForWriting opens a file for writing in the publish directory
+     * TypeScript equivalent of OpenPublishFileForWriting method from Go
+     */
     openPublishFileForWriting(filename: string): Promise<FileWritable>;
+    /**
+     * Helper method to open files for writing using a MultiWriter approach
+     * TypeScript equivalent of helpers.OpenFilesForWriting function from Go
+     */
     private openFilesForWriting;
+    /**
+     * OpenFileForWriting opens or creates the given file. If the target directory
+     * does not exist, it gets created.
+     * TypeScript equivalent of OpenFileForWriting function from Go
+     */
     private openFileForWriting;
+    /**
+     * Helper to check if error is a file not found error
+     */
     private isFileNotFoundError;
 }
 import { Writable } from 'stream';

package/dist/types/internal/domain/resources/entity/resource.d.ts

@@ -30,6 +30,10 @@ export declare class ResourceImpl implements IResource, ResourceCopier {
     relPermalink(): string;
     permalink(): string;
     private publish;
+    /**
+     * Helper method to copy stream content to file
+     * TypeScript equivalent of golang's io.Copy functionality
+     */
     private copyStreamToFile;
     targetPath(): string;
     data(): any;

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

@@ -1,4 +1,11 @@
 import { Resources as IResources, Resource, OpenReadSeekCloser, Workspace, MinifierClient as IMinifierClient, IntegrityClient as IIntegrityClient, TemplateClient as ITemplateClient, TemplateSvc } from '../type';
+/**
+ * Resources aggregation root - the main entry point for all resource operations
+ * Implements the four main operations: GetResource, ExecuteAsTemplate, Minify, Fingerprint
+ *
+ * This is the main aggregation root for the Resources domain following DDD principles.
+ * All resource operations should go through this class.
+ */
 export declare class Resources implements IResources {
     private cache;
     private workspace;
@@ -12,18 +19,51 @@ export declare class Resources implements IResources {
     private httpClient;
     constructor(workspace: Workspace);
     setTemplateSvc(templateSvc: TemplateSvc): void;
+    /**
+     * GetResource - First primary operation: get a resource by pathname
+     * Supports caching for performance optimization
+     */
     getResource(pathname: string): Promise<Resource | null>;
+    /**
+     * GetResourceWithOpener - Alternative way to get resource with custom opener
+     */
     getResourceWithOpener(pathname: string, opener: OpenReadSeekCloser): Promise<Resource | null>;
+    /**
+     * ExecuteAsTemplate - Second primary operation: execute resource as template
+     * Supports template execution with data binding
+     */
     executeAsTemplate(resource: Resource, targetPath: string, data: any): Promise<Resource>;
+    /**
+     * Minify - Third primary operation: minify a resource
+     * Supports CSS, JS, HTML, JSON, SVG, and XML minification
+     */
     minify(resource: Resource): Promise<Resource>;
+    /**
+     * Fingerprint - Fourth primary operation: add fingerprint to resource
+     * Supports integrity generation and filename fingerprinting
+     */
     fingerprint(resource: Resource): Promise<Resource>;
+    /**
+     * FromRemote - Fifth primary operation: get resource from remote URI
+     * Supports fetching resources from HTTP/HTTPS URLs with caching
+     */
     getRemote(uri: string): Promise<Resource | null>;
     cacheKey(key: string): string;
+    /**
+     * Client accessors for external access
+     */
     getMinifierClient(): IMinifierClient;
     getIntegrityClient(): IIntegrityClient;
     setTemplateClient(client: ITemplateClient): void;
+    /**
+     * Private helper methods
+     */
     private buildResource;
     private getMediaTypeFromExtension;
     private createReadSeekCloser;
+    /**
+     * Create ReadSeekCloser from string content
+     * This follows golang's NewReadSeekerNoOpCloserFromString pattern
+     */
     private newReadSeekerNoOpCloserFromString;
 }

package/dist/types/internal/domain/resources/entity/template.d.ts

@@ -1,4 +1,8 @@
 import { Resource, TemplateClient as ITemplateClient, TemplateSvc } from '../type';
+/**
+ * TemplateClient provides template execution functionality for resources
+ * This implements the ExecuteAsTemplate operation following golang version
+ */
 export declare class TemplateClient implements ITemplateClient {
     private templateExecutor;
     constructor(templateExecutor: TemplateSvc);

package/dist/types/internal/domain/resources/factory/resource.d.ts

@@ -1,3 +1,7 @@
 import { Resources } from '../entity/resources';
 import { Workspace } from '../type';
+/**
+ * Factory function to create Resources aggregation root
+ * This provides the main entry point for the resources domain
+ */
 export declare function createResources(workspace: Workspace): Resources;