@imjp/writenex-astro 0.1.0

package/dist/filesystem/index.d.ts

@@ -0,0 +1,1292 @@
+import { C as ContentItem, a as ContentSummary } from '../content-BWR52vD-.js';
+import { V as VersionHistoryConfig, d as SaveVersionOptions, e as VersionResult, f as VersionEntry, g as Version, R as RestoreVersionOptions, h as RestoreResult, i as VersionManifest, I as ImageConfig } from '../config-BmEdBDo_.js';
+import { C as ContentConflictError } from '../errors-C0iYiDTv.js';
+import { I as ImageDiscoveryOptions, a as ImageDiscoveryResult, D as DiscoveredImage } from '../image-FP7w5ZIs.js';
+
+/**
+ * @fileoverview Filesystem reader for content collections
+ *
+ * This module provides functions for reading content files from the filesystem,
+ * parsing frontmatter, and extracting content metadata.
+ *
+ * ## Features:
+ * - Read individual content files with frontmatter parsing
+ * - List all content files in a collection
+ * - Generate content summaries for listing
+ * - Support for .md and .mdx files
+ *
+ * @module @writenex/astro/filesystem/reader
+ */
+
+/**
+ * Options for reading content
+ */
+interface ReadContentOptions {
+    /** Include draft content in listings */
+    includeDrafts?: boolean;
+    /** Sort field for listings */
+    sortBy?: string;
+    /** Sort order */
+    sortOrder?: "asc" | "desc";
+}
+/**
+ * Result of reading a content file
+ */
+interface ReadFileResult {
+    /** Whether the read was successful */
+    success: boolean;
+    /** The content item (if successful) */
+    content?: ContentItem;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Check if a file is a content file based on extension
+ *
+ * @param filename - The filename to check
+ * @returns True if the file is a content file
+ */
+declare function isContentFile(filename: string): boolean;
+/**
+ * Extract slug from a content file path
+ *
+ * Handles various file patterns:
+ * - `my-post.md` -> `my-post`
+ * - `2024-01-15-my-post.md` -> `2024-01-15-my-post`
+ * - `my-post/index.md` -> `my-post`
+ *
+ * @param filePath - Path to the content file
+ * @param collectionPath - Path to the collection directory
+ * @returns The extracted slug
+ */
+declare function extractSlug(filePath: string, collectionPath: string): string;
+/**
+ * Generate an excerpt from markdown content
+ *
+ * @param body - The markdown body content
+ * @param maxLength - Maximum excerpt length
+ * @returns The generated excerpt
+ */
+declare function generateExcerpt(body: string, maxLength?: number): string;
+/**
+ * Read and parse a single content file
+ *
+ * @param filePath - Absolute path to the content file
+ * @param collectionPath - Path to the collection directory
+ * @returns ReadFileResult with the parsed content or error
+ *
+ * @example
+ * ```typescript
+ * const result = await readContentFile(
+ *   '/project/src/content/blog/my-post.md',
+ *   '/project/src/content/blog'
+ * );
+ *
+ * if (result.success) {
+ *   console.log(result.content.frontmatter.title);
+ * }
+ * ```
+ */
+declare function readContentFile(filePath: string, collectionPath: string): Promise<ReadFileResult>;
+/**
+ * Read all content files in a collection
+ *
+ * @param collectionPath - Absolute path to the collection directory
+ * @param options - Read options
+ * @returns Array of content items
+ *
+ * @example
+ * ```typescript
+ * const items = await readCollection('/project/src/content/blog', {
+ *   includeDrafts: false,
+ *   sortBy: 'pubDate',
+ *   sortOrder: 'desc',
+ * });
+ * ```
+ */
+declare function readCollection(collectionPath: string, options?: ReadContentOptions): Promise<ContentItem[]>;
+/**
+ * Convert a content item to a summary for listing
+ *
+ * @param item - The full content item
+ * @returns Content summary with essential fields
+ */
+declare function toContentSummary(item: ContentItem): ContentSummary;
+/**
+ * Get content summaries for a collection
+ *
+ * @param collectionPath - Absolute path to the collection directory
+ * @param options - Read options
+ * @returns Array of content summaries
+ */
+declare function getCollectionSummaries(collectionPath: string, options?: ReadContentOptions): Promise<ContentSummary[]>;
+/**
+ * Get the count of content files in a collection
+ *
+ * @param collectionPath - Absolute path to the collection directory
+ * @returns Number of content files
+ */
+declare function getCollectionCount(collectionPath: string): Promise<number>;
+/**
+ * Check if a collection directory exists and contains content
+ *
+ * @param collectionPath - Absolute path to the collection directory
+ * @returns Object with exists and hasContent flags
+ */
+declare function checkCollection(collectionPath: string): Promise<{
+    exists: boolean;
+    hasContent: boolean;
+    count: number;
+}>;
+/**
+ * Get file stats for a content file
+ *
+ * @param filePath - Path to the content file
+ * @returns File stats or null if file doesn't exist
+ */
+declare function getFileStats(filePath: string): Promise<{
+    size: number;
+    mtime: Date;
+    ctime: Date;
+} | null>;
+/**
+ * Get the file path for a content item by ID
+ *
+ * Searches for the content file in the collection directory,
+ * handling different content structures:
+ * - Folder-based: `slug/index.md` or `slug/index.mdx`
+ * - Flat file: `slug.md` or `slug.mdx`
+ *
+ * @param collectionPath - Path to the collection directory
+ * @param contentId - Content ID (slug)
+ * @returns File path if found, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const filePath = getContentFilePath('/project/src/content/blog', 'my-post');
+ * // Returns: '/project/src/content/blog/my-post.md' or
+ * //          '/project/src/content/blog/my-post/index.md'
+ * ```
+ */
+declare function getContentFilePath(collectionPath: string, contentId: string): string | null;
+
+/**
+ * @fileoverview Filesystem writer for content operations
+ *
+ * This module provides functions for creating, updating, and deleting
+ * content files in Astro content collections.
+ *
+ * ## Features:
+ * - Create new content files with frontmatter
+ * - Update existing content files
+ * - Delete content files
+ * - Generate unique slugs to avoid collisions
+ * - Support for different file patterns (flat, folder-based, date-prefixed)
+ * - Automatic version history creation before updates
+ *
+ * @module @writenex/astro/filesystem/writer
+ */
+
+/**
+ * Options for creating content
+ */
+interface CreateContentOptions {
+    /** Frontmatter data */
+    frontmatter: Record<string, unknown>;
+    /** Markdown body content */
+    body: string;
+    /** Custom slug (optional, generated from title if not provided) */
+    slug?: string;
+    /** File pattern for the collection (e.g., "{slug}/index.md", "{date}-{slug}.md") */
+    filePattern?: string;
+    /** Custom token values to override automatic resolution */
+    customTokens?: Record<string, string>;
+}
+/**
+ * Options for updating content
+ */
+interface UpdateContentOptions {
+    /** Updated frontmatter data */
+    frontmatter?: Record<string, unknown>;
+    /** Updated markdown body content */
+    body?: string;
+    /** Project root for version history (required for version creation) */
+    projectRoot?: string;
+    /** Collection name for version history */
+    collection?: string;
+    /** Version history configuration */
+    versionHistoryConfig?: Required<VersionHistoryConfig>;
+    /**
+     * Expected modification time for conflict detection.
+     * If provided and the file's mtime differs, the update will fail with a conflict error.
+     */
+    expectedMtime?: number;
+}
+/**
+ * Result of a write operation
+ */
+interface WriteResult {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** The content ID (slug) */
+    id?: string;
+    /** The file path */
+    path?: string;
+    /** Error message if failed */
+    error?: string;
+    /** New modification time after write (for conflict detection) */
+    mtime?: number;
+    /** Conflict error if update failed due to external modification */
+    conflict?: ContentConflictError;
+}
+/**
+ * Generate a URL-safe slug from a string
+ *
+ * @param text - Text to slugify
+ * @returns URL-safe slug
+ */
+declare function generateSlug(text: string): string;
+/**
+ * Generate a unique slug that doesn't conflict with existing files
+ *
+ * @param baseSlug - The base slug to start with
+ * @param collectionPath - Path to the collection directory
+ * @param filePattern - File pattern (default: "{slug}.md")
+ * @returns A unique slug
+ */
+declare function generateUniqueSlug(baseSlug: string, collectionPath: string, filePattern?: string): Promise<string>;
+/**
+ * Create a new content file in a collection
+ *
+ * Supports various file patterns with automatic token resolution:
+ * - `{slug}.md` - Simple flat structure (default)
+ * - `{slug}/index.md` - Folder-based content
+ * - `{date}-{slug}.md` - Date-prefixed naming
+ * - `{year}/{slug}.md` - Year folder structure
+ * - `{year}/{month}/{slug}.md` - Year/month folder structure
+ * - `{year}/{month}/{day}/{slug}.md` - Full date folder structure
+ * - `{lang}/{slug}.md` - Language-prefixed (i18n)
+ * - `{category}/{slug}.md` - Category folder structure
+ * - `{author}/{slug}.md` - Author folder structure
+ * - Any custom pattern with tokens from frontmatter
+ *
+ * Token resolution priority:
+ * 1. Custom tokens (explicitly provided via customTokens)
+ * 2. Known token resolvers (date, year, month, lang, category, etc.)
+ * 3. Frontmatter values (for custom tokens)
+ * 4. Default values
+ *
+ * @param collectionPath - Absolute path to the collection directory
+ * @param options - Content creation options
+ * @returns WriteResult with success status and file info
+ *
+ * @example
+ * ```typescript
+ * // Flat structure
+ * const result = await createContent('/project/src/content/blog', {
+ *   frontmatter: { title: 'My New Post', pubDate: new Date() },
+ *   body: '# Hello World',
+ * });
+ *
+ * // Folder-based structure
+ * const result = await createContent('/project/src/content/blog', {
+ *   frontmatter: { title: 'My New Post', pubDate: new Date() },
+ *   body: '# Hello World',
+ *   filePattern: '{slug}/index.md',
+ * });
+ *
+ * // i18n structure with custom token
+ * const result = await createContent('/project/src/content/blog', {
+ *   frontmatter: { title: 'My New Post', lang: 'id' },
+ *   body: '# Hello World',
+ *   filePattern: '{lang}/{slug}.md',
+ * });
+ *
+ * // Custom pattern with explicit token
+ * const result = await createContent('/project/src/content/blog', {
+ *   frontmatter: { title: 'My New Post' },
+ *   body: '# Hello World',
+ *   filePattern: '{category}/{slug}.md',
+ *   customTokens: { category: 'tutorials' },
+ * });
+ * ```
+ */
+declare function createContent(collectionPath: string, options: CreateContentOptions): Promise<WriteResult>;
+/**
+ * Update an existing content file
+ *
+ * Creates a version snapshot of the current content before updating
+ * when version history is configured. Skips both version creation and
+ * file write if the new content is identical to the current file content.
+ * Version creation errors are logged but do not fail the save operation.
+ *
+ * @param filePath - Absolute path to the content file
+ * @param collectionPath - Path to the collection directory
+ * @param options - Update options including version history config
+ * @returns WriteResult with success status
+ *
+ * @example
+ * ```typescript
+ * const result = await updateContent(
+ *   '/project/src/content/blog/my-post.md',
+ *   '/project/src/content/blog',
+ *   {
+ *     frontmatter: { title: 'Updated Title' },
+ *     body: '# Updated Content',
+ *     projectRoot: '/project',
+ *     collection: 'blog',
+ *     versionHistoryConfig: { enabled: true, maxVersions: 20, storagePath: '.writenex/versions' },
+ *   }
+ * );
+ * ```
+ */
+declare function updateContent(filePath: string, collectionPath: string, options: UpdateContentOptions): Promise<WriteResult>;
+/**
+ * Delete a content file
+ *
+ * @param filePath - Absolute path to the content file
+ * @returns WriteResult with success status
+ *
+ * @example
+ * ```typescript
+ * const result = await deleteContent('/project/src/content/blog/my-post.md');
+ * ```
+ */
+declare function deleteContent(filePath: string): Promise<WriteResult>;
+
+/**
+ * @fileoverview File watcher for detecting external changes
+ *
+ * This module provides file watching capabilities to detect when
+ * content files are modified outside of the Writenex editor
+ * (e.g., in VS Code or another editor).
+ *
+ * @module @writenex/astro/filesystem/watcher
+ */
+/**
+ * File change event types
+ */
+type FileChangeType = "add" | "change" | "unlink";
+/**
+ * File change event
+ */
+interface FileChangeEvent {
+    type: FileChangeType;
+    path: string;
+    collection: string;
+}
+/**
+ * Watcher options
+ */
+interface WatcherOptions {
+    /** Callback when a file changes */
+    onChange?: (event: FileChangeEvent) => void;
+    /** Debounce delay in milliseconds */
+    debounceMs?: number;
+    /** Patterns to ignore */
+    ignored?: string[];
+}
+/**
+ * Content file watcher
+ *
+ * Watches the src/content directory for changes and emits events
+ * when files are added, modified, or deleted.
+ */
+declare class ContentWatcher {
+    private watcher;
+    private projectRoot;
+    private contentDir;
+    private options;
+    private debounceTimers;
+    constructor(projectRoot: string, contentDir?: string, options?: WatcherOptions);
+    /**
+     * Start watching for file changes
+     */
+    start(): void;
+    /**
+     * Stop watching for file changes
+     */
+    stop(): Promise<void>;
+    /**
+     * Handle a file change event
+     */
+    private handleChange;
+    /**
+     * Emit a file change event
+     */
+    private emitChange;
+    /**
+     * Check if the watcher is running
+     */
+    isWatching(): boolean;
+}
+/**
+ * Track file modification times for conflict detection
+ */
+declare class FileModificationTracker {
+    private mtimes;
+    /**
+     * Record the current modification time of a file
+     */
+    track(filePath: string): Promise<void>;
+    /**
+     * Check if a file has been modified externally
+     */
+    hasExternalChanges(filePath: string): Promise<boolean>;
+    /**
+     * Clear tracking for a file
+     */
+    untrack(filePath: string): void;
+    /**
+     * Clear all tracking
+     */
+    clear(): void;
+}
+/**
+ * Create a content watcher instance
+ */
+declare function createContentWatcher(projectRoot: string, options?: WatcherOptions): ContentWatcher;
+
+/**
+ * @fileoverview Version history management for content files
+ *
+ * This module provides functions for creating, reading, and managing
+ * version history (shadow copies) of content files. Versions are stored
+ * as markdown files in a hidden directory structure with a JSON manifest
+ * tracking metadata.
+ *
+ * ## Storage Structure:
+ * ```
+ * .writenex/versions/
+ * ├── .gitignore              # Contains "*" to exclude from Git
+ * └── {collection}/
+ *     └── {contentId}/
+ *         ├── manifest.json   # Version metadata
+ *         └── {timestamp}.md  # Version files
+ * ```
+ *
+ * @module @writenex/astro/filesystem/versions
+ * @see {@link VersionEntry} - Version metadata type
+ * @see {@link VersionManifest} - Manifest structure type
+ */
+
+/**
+ * Generate a unique version ID based on current timestamp with random suffix.
+ *
+ * The ID is an ISO-8601 timestamp with colons replaced by hyphens,
+ * plus a 4-character random suffix to ensure uniqueness even when
+ * multiple versions are created within the same millisecond.
+ *
+ * Format: YYYY-MM-DDTHH-MM-SS.mmmZ-xxxx
+ * Where xxxx is a random alphanumeric suffix.
+ *
+ * @returns Version ID string (e.g., "2024-12-11T10-30-00.000Z-a1b2")
+ *
+ * @example
+ * ```typescript
+ * const id = generateVersionId();
+ * // Returns: "2024-12-11T10-30-00.000Z-a1b2"
+ * ```
+ */
+declare function generateVersionId(): string;
+/**
+ * Parse a version ID back to a Date object.
+ *
+ * Handles both old format (without suffix) and new format (with random suffix).
+ *
+ * @param versionId - Version ID string
+ * @returns Date object or null if invalid
+ */
+declare function parseVersionId(versionId: string): Date | null;
+/**
+ * Get the storage path for version files of a content item.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param config - Version history configuration
+ * @returns Absolute path to version storage directory
+ *
+ * @example
+ * ```typescript
+ * const path = getVersionStoragePath(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   { storagePath: '.writenex/versions' }
+ * );
+ * // Returns: "/project/.writenex/versions/blog/my-post"
+ * ```
+ */
+declare function getVersionStoragePath(projectRoot: string, collection: string, contentId: string, config: Required<VersionHistoryConfig>): string;
+/**
+ * Get the path to a specific version file.
+ *
+ * @param storagePath - Version storage directory path
+ * @param versionId - Version ID
+ * @returns Absolute path to version file
+ */
+declare function getVersionFilePath(storagePath: string, versionId: string): string;
+/**
+ * Get the path to the manifest file for a content item.
+ *
+ * @param storagePath - Version storage directory path
+ * @returns Absolute path to manifest file
+ */
+declare function getManifestPath(storagePath: string): string;
+/**
+ * Generate a preview string from content.
+ *
+ * Extracts the first 100 characters of the content body,
+ * stripping frontmatter if present.
+ *
+ * @param content - Full markdown content
+ * @returns Preview string (max 100 characters)
+ *
+ * @example
+ * ```typescript
+ * const preview = generatePreview("---\ntitle: Test\n---\n\n# Hello World\n\nThis is content.");
+ * // Returns: "# Hello World\n\nThis is content."
+ * ```
+ */
+declare function generatePreview(content: string): string;
+/**
+ * Ensure the .gitignore file exists in the version storage root.
+ *
+ * Creates a .gitignore file with "*" pattern to exclude all version
+ * files from Git tracking.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param config - Version history configuration
+ *
+ * @example
+ * ```typescript
+ * await ensureGitignore('/project', { storagePath: '.writenex/versions' });
+ * // Creates: /project/.writenex/versions/.gitignore with content "*"
+ * ```
+ */
+declare function ensureGitignore(projectRoot: string, config: Required<VersionHistoryConfig>): Promise<void>;
+/**
+ * Ensure the version storage directory exists for a content item.
+ *
+ * @param storagePath - Version storage directory path
+ */
+declare function ensureStorageDirectory(storagePath: string): Promise<void>;
+/**
+ * Read the version manifest for a content item.
+ *
+ * @param storagePath - Version storage directory path
+ * @returns Version manifest or null if not found/corrupted
+ *
+ * @example
+ * ```typescript
+ * const manifest = await readManifest('/project/.writenex/versions/blog/my-post');
+ * if (manifest) {
+ *   console.log(`Found ${manifest.versions.length} versions`);
+ * }
+ * ```
+ */
+declare function readManifest(storagePath: string): Promise<VersionManifest | null>;
+/**
+ * Write the version manifest for a content item.
+ *
+ * @param storagePath - Version storage directory path
+ * @param manifest - Version manifest to write
+ *
+ * @example
+ * ```typescript
+ * await writeManifest('/project/.writenex/versions/blog/my-post', {
+ *   contentId: 'my-post',
+ *   collection: 'blog',
+ *   versions: [],
+ *   updatedAt: new Date().toISOString(),
+ * });
+ * ```
+ */
+declare function writeManifest(storagePath: string, manifest: VersionManifest): Promise<void>;
+/**
+ * Create an empty manifest for a content item.
+ *
+ * @param collection - Collection name
+ * @param contentId - Content item ID
+ * @returns New empty manifest
+ */
+declare function createEmptyManifest(collection: string, contentId: string): VersionManifest;
+/**
+ * Recover manifest by scanning version files in the storage directory.
+ *
+ * This function rebuilds the manifest from existing version files
+ * when the manifest is corrupted or missing.
+ *
+ * @param storagePath - Version storage directory path
+ * @param collection - Collection name
+ * @param contentId - Content item ID
+ * @returns Recovered manifest
+ *
+ * @example
+ * ```typescript
+ * const manifest = await recoverManifest(
+ *   '/project/.writenex/versions/blog/my-post',
+ *   'blog',
+ *   'my-post'
+ * );
+ * ```
+ */
+declare function recoverManifest(storagePath: string, collection: string, contentId: string): Promise<VersionManifest>;
+/**
+ * Get or recover manifest for a content item.
+ *
+ * Attempts to read existing manifest, falls back to recovery if corrupted.
+ *
+ * @param storagePath - Version storage directory path
+ * @param collection - Collection name
+ * @param contentId - Content item ID
+ * @returns Version manifest
+ */
+declare function getOrRecoverManifest(storagePath: string, collection: string, contentId: string): Promise<VersionManifest>;
+/**
+ * Save a version snapshot of content.
+ *
+ * Creates a new version file with the provided content and updates
+ * the manifest. Automatically prunes old versions if the limit is exceeded.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param content - Full markdown content to save
+ * @param config - Version history configuration
+ * @param options - Save options
+ * @returns Result of the save operation
+ *
+ * @example
+ * ```typescript
+ * const result = await saveVersion(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   '---\ntitle: My Post\n---\n\nContent here...',
+ *   { enabled: true, maxVersions: 20, storagePath: '.writenex/versions' }
+ * );
+ *
+ * if (result.success) {
+ *   console.log(`Created version: ${result.version?.id}`);
+ * }
+ * ```
+ */
+declare function saveVersion(projectRoot: string, collection: string, contentId: string, content: string, config: Required<VersionHistoryConfig>, options?: SaveVersionOptions): Promise<VersionResult>;
+/**
+ * Get all versions for a content item.
+ *
+ * Returns versions sorted by timestamp in descending order (newest first).
+ * Handles missing or corrupted manifests gracefully.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param config - Version history configuration
+ * @returns Array of version entries
+ *
+ * @example
+ * ```typescript
+ * const versions = await getVersions(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   { enabled: true, maxVersions: 20, storagePath: '.writenex/versions' }
+ * );
+ *
+ * console.log(`Found ${versions.length} versions`);
+ * ```
+ */
+declare function getVersions(projectRoot: string, collection: string, contentId: string, config: Required<VersionHistoryConfig>): Promise<VersionEntry[]>;
+/**
+ * Get a specific version with full content.
+ *
+ * Reads the version file and parses it to return structured data
+ * with frontmatter and body separated.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param versionId - Version ID to retrieve
+ * @param config - Version history configuration
+ * @returns Full version data or null if not found
+ *
+ * @example
+ * ```typescript
+ * const version = await getVersion(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   '2024-12-11T10-30-00-000Z',
+ *   { enabled: true, maxVersions: 20, storagePath: '.writenex/versions' }
+ * );
+ *
+ * if (version) {
+ *   console.log(`Title: ${version.frontmatter.title}`);
+ *   console.log(`Body: ${version.body}`);
+ * }
+ * ```
+ */
+declare function getVersion(projectRoot: string, collection: string, contentId: string, versionId: string, config: Required<VersionHistoryConfig>): Promise<Version | null>;
+/**
+ * Delete a specific version.
+ *
+ * Removes the version file from the filesystem and updates the manifest.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param versionId - Version ID to delete
+ * @param config - Version history configuration
+ * @returns Result of the delete operation
+ *
+ * @example
+ * ```typescript
+ * const result = await deleteVersion(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   '2024-12-11T10-30-00-000Z',
+ *   { enabled: true, maxVersions: 20, storagePath: '.writenex/versions' }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Version deleted');
+ * }
+ * ```
+ */
+declare function deleteVersion(projectRoot: string, collection: string, contentId: string, versionId: string, config: Required<VersionHistoryConfig>): Promise<VersionResult>;
+/**
+ * Clear all versions for a content item.
+ *
+ * Deletes all version files and resets the manifest to empty state.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param config - Version history configuration
+ * @returns Result of the clear operation
+ *
+ * @example
+ * ```typescript
+ * const result = await clearVersions(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   { enabled: true, maxVersions: 20, storagePath: '.writenex/versions' }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('All versions cleared');
+ * }
+ * ```
+ */
+declare function clearVersions(projectRoot: string, collection: string, contentId: string, config: Required<VersionHistoryConfig>): Promise<VersionResult>;
+declare function pruneVersions(projectRoot: string, collection: string, contentId: string, config: Required<VersionHistoryConfig>): Promise<VersionResult>;
+/**
+ * Restore a version to current content.
+ *
+ * This function:
+ * 1. Creates a safety snapshot of the current content before restoring
+ * 2. Reads the version content to restore
+ * 3. Overwrites the current content file with the version content
+ *
+ * Note: Cache invalidation should be handled by the caller (API route)
+ * since the cache is managed at the server level.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param versionId - Version ID to restore
+ * @param contentFilePath - Absolute path to the current content file
+ * @param config - Version history configuration
+ * @param options - Restore options
+ * @returns Result of the restore operation
+ *
+ * @example
+ * ```typescript
+ * const result = await restoreVersion(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   '2024-12-11T10-30-00-000Z',
+ *   '/project/src/content/blog/my-post.md',
+ *   { enabled: true, maxVersions: 20, storagePath: '.writenex/versions' }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Restored content:', result.content);
+ *   if (result.safetySnapshot) {
+ *     console.log('Safety snapshot created:', result.safetySnapshot.id);
+ *   }
+ * }
+ * ```
+ */
+declare function restoreVersion(projectRoot: string, collection: string, contentId: string, versionId: string, contentFilePath: string, config: Required<VersionHistoryConfig>, options?: RestoreVersionOptions): Promise<RestoreResult>;
+
+/**
+ * @fileoverview Config-aware wrappers for version history operations
+ *
+ * This module provides wrapper functions that automatically apply configuration
+ * defaults and check the enabled flag before performing version operations.
+ * These wrappers simplify usage by accepting partial configuration and handling
+ * all the configuration resolution internally.
+ *
+ * @module @writenex/astro/filesystem/version-config
+ * @see {@link saveVersion} - Core save function
+ * @see {@link getVersions} - Core list function
+ */
+
+/**
+ * Resolve version history configuration with defaults applied.
+ *
+ * Takes a partial configuration and merges it with defaults to produce
+ * a complete configuration object.
+ *
+ * @param config - Partial version history configuration
+ * @returns Complete configuration with all defaults applied
+ *
+ * @example
+ * ```typescript
+ * const resolved = resolveVersionConfig({ maxVersions: 50 });
+ * // Returns: { enabled: true, maxVersions: 50, storagePath: '.writenex/versions' }
+ * ```
+ */
+declare function resolveVersionConfig(config?: VersionHistoryConfig): Required<VersionHistoryConfig>;
+/**
+ * Check if version history is enabled in the configuration.
+ *
+ * @param config - Version history configuration (partial or full)
+ * @returns True if version history is enabled
+ *
+ * @example
+ * ```typescript
+ * if (isVersionHistoryEnabled({ enabled: false })) {
+ *   // This won't execute
+ * }
+ * ```
+ */
+declare function isVersionHistoryEnabled(config?: VersionHistoryConfig): boolean;
+/**
+ * Save a version with automatic configuration resolution.
+ *
+ * This wrapper automatically applies configuration defaults and checks
+ * the enabled flag before delegating to the core saveVersion function.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param content - Full markdown content to save
+ * @param config - Partial version history configuration
+ * @param options - Save options
+ * @returns Result of the save operation
+ *
+ * @example
+ * ```typescript
+ * // With partial config - defaults are applied automatically
+ * const result = await saveVersionWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   '---\ntitle: My Post\n---\n\nContent...',
+ *   { maxVersions: 50 }  // enabled and storagePath use defaults
+ * );
+ * ```
+ */
+declare function saveVersionWithConfig(projectRoot: string, collection: string, contentId: string, content: string, config?: VersionHistoryConfig, options?: SaveVersionOptions): Promise<VersionResult>;
+/**
+ * Get all versions with automatic configuration resolution.
+ *
+ * This wrapper automatically applies configuration defaults and checks
+ * the enabled flag before delegating to the core getVersions function.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param config - Partial version history configuration
+ * @returns Array of version entries (empty if disabled)
+ *
+ * @example
+ * ```typescript
+ * const versions = await getVersionsWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   { storagePath: 'custom/versions' }
+ * );
+ * ```
+ */
+declare function getVersionsWithConfig(projectRoot: string, collection: string, contentId: string, config?: VersionHistoryConfig): Promise<VersionEntry[]>;
+/**
+ * Get a specific version with automatic configuration resolution.
+ *
+ * This wrapper automatically applies configuration defaults and checks
+ * the enabled flag before delegating to the core getVersion function.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param versionId - Version ID to retrieve
+ * @param config - Partial version history configuration
+ * @returns Full version data or null if not found/disabled
+ *
+ * @example
+ * ```typescript
+ * const version = await getVersionWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   '2024-12-11T10-30-00-000Z'
+ * );
+ * ```
+ */
+declare function getVersionWithConfig(projectRoot: string, collection: string, contentId: string, versionId: string, config?: VersionHistoryConfig): Promise<Version | null>;
+/**
+ * Delete a version with automatic configuration resolution.
+ *
+ * This wrapper automatically applies configuration defaults before
+ * delegating to the core deleteVersion function.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param versionId - Version ID to delete
+ * @param config - Partial version history configuration
+ * @returns Result of the delete operation
+ *
+ * @example
+ * ```typescript
+ * const result = await deleteVersionWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   '2024-12-11T10-30-00-000Z'
+ * );
+ * ```
+ */
+declare function deleteVersionWithConfig(projectRoot: string, collection: string, contentId: string, versionId: string, config?: VersionHistoryConfig): Promise<VersionResult>;
+/**
+ * Clear all versions with automatic configuration resolution.
+ *
+ * This wrapper automatically applies configuration defaults before
+ * delegating to the core clearVersions function.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param config - Partial version history configuration
+ * @returns Result of the clear operation
+ *
+ * @example
+ * ```typescript
+ * const result = await clearVersionsWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post'
+ * );
+ * ```
+ */
+declare function clearVersionsWithConfig(projectRoot: string, collection: string, contentId: string, config?: VersionHistoryConfig): Promise<VersionResult>;
+/**
+ * Prune old versions with automatic configuration resolution.
+ *
+ * This wrapper automatically applies configuration defaults before
+ * delegating to the core pruneVersions function. Uses the configured
+ * maxVersions value for determining how many versions to keep.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param config - Partial version history configuration
+ * @returns Result of the prune operation
+ *
+ * @example
+ * ```typescript
+ * // Uses custom maxVersions
+ * const result = await pruneVersionsWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   { maxVersions: 10 }
+ * );
+ * ```
+ */
+declare function pruneVersionsWithConfig(projectRoot: string, collection: string, contentId: string, config?: VersionHistoryConfig): Promise<VersionResult>;
+/**
+ * Restore a version with automatic configuration resolution.
+ *
+ * This wrapper automatically applies configuration defaults and checks
+ * the enabled flag before delegating to the core restoreVersion function.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param collection - Collection name
+ * @param contentId - Content item ID (slug)
+ * @param versionId - Version ID to restore
+ * @param contentFilePath - Absolute path to the current content file
+ * @param config - Partial version history configuration
+ * @param options - Restore options
+ * @returns Result of the restore operation
+ *
+ * @example
+ * ```typescript
+ * const result = await restoreVersionWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   '2024-12-11T10-30-00-000Z',
+ *   '/project/src/content/blog/my-post.md'
+ * );
+ * ```
+ */
+declare function restoreVersionWithConfig(projectRoot: string, collection: string, contentId: string, versionId: string, contentFilePath: string, config?: VersionHistoryConfig, options?: RestoreVersionOptions): Promise<RestoreResult>;
+
+/**
+ * @fileoverview Image handling for content collections
+ *
+ * This module provides functions for uploading and managing images
+ * in content collections with support for different storage strategies.
+ *
+ * ## Strategies:
+ * - colocated: Images stored alongside content files
+ * - public: Images stored in public directory
+ * - custom: User-defined storage paths
+ *
+ * @module @writenex/astro/filesystem/images
+ */
+
+/**
+ * Default image configuration
+ */
+declare const DEFAULT_IMAGE_CONFIG: ImageConfig;
+/**
+ * Result of image upload operation
+ */
+interface ImageUploadResult {
+    success: boolean;
+    /** Markdown-compatible path for the image */
+    path?: string;
+    /** Public URL for the image */
+    url?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Options for image upload
+ */
+interface ImageUploadOptions {
+    /** Original filename */
+    filename: string;
+    /** Image binary data */
+    data: Buffer;
+    /** Collection name */
+    collection: string;
+    /** Content ID (slug) */
+    contentId: string;
+    /** Project root path */
+    projectRoot: string;
+    /** Image configuration */
+    config?: ImageConfig;
+}
+/**
+ * Validate image file
+ *
+ * @param filename - Original filename
+ * @returns True if valid image file
+ */
+declare function isValidImageFile(filename: string): boolean;
+/**
+ * Upload an image file
+ *
+ * @param options - Upload options
+ * @returns Upload result with paths
+ *
+ * @example
+ * ```typescript
+ * const result = await uploadImage({
+ *   filename: "hero.jpg",
+ *   data: imageBuffer,
+ *   collection: "blog",
+ *   contentId: "my-post",
+ *   projectRoot: "/path/to/project",
+ * });
+ *
+ * if (result.success) {
+ *   console.log(result.path); // "./my-post/hero-abc123.jpg"
+ * }
+ * ```
+ */
+declare function uploadImage(options: ImageUploadOptions): Promise<ImageUploadResult>;
+/**
+ * Parse multipart form data for image upload
+ *
+ * Simple parser for multipart/form-data with single file upload.
+ * For production, consider using a proper multipart parser library.
+ *
+ * @param body - Raw request body
+ * @param contentType - Content-Type header
+ * @returns Parsed file data and fields
+ */
+declare function parseMultipartFormData(body: Buffer, contentType: string): {
+    file?: {
+        filename: string;
+        data: Buffer;
+        contentType: string;
+    };
+    fields: Record<string, string>;
+};
+/**
+ * Content structure type detected from file path
+ */
+type ContentStructure = "flat" | "folder-based" | "date-prefixed";
+/**
+ * Result of content structure detection
+ */
+interface ContentStructureResult {
+    /** Detected structure type */
+    structure: ContentStructure;
+    /** Path to the image folder (null if doesn't exist) */
+    imageFolderPath: string | null;
+}
+/**
+ * Detect content structure and get the image folder path
+ *
+ * Handles three content structures:
+ * - Flat file: `my-post.md` -> looks for `my-post/` sibling folder
+ * - Folder-based: `slug/index.md` -> uses `slug/` parent folder
+ * - Date-prefixed: `2024-01-15-my-post.md` -> looks for `2024-01-15-my-post/` sibling folder
+ *
+ * @param collectionPath - Absolute path to the collection directory
+ * @param contentId - Content ID (slug)
+ * @param contentFilePath - Absolute path to the content file
+ * @returns Path to the image folder, or null if no image folder exists
+ *
+ * @example
+ * ```typescript
+ * // Flat file structure
+ * const folder = getContentImageFolder(
+ *   '/project/src/content/blog',
+ *   'my-post',
+ *   '/project/src/content/blog/my-post.md'
+ * );
+ * // Returns: '/project/src/content/blog/my-post' (if exists)
+ *
+ * // Folder-based structure
+ * const folder = getContentImageFolder(
+ *   '/project/src/content/blog',
+ *   'my-post',
+ *   '/project/src/content/blog/my-post/index.md'
+ * );
+ * // Returns: '/project/src/content/blog/my-post'
+ * ```
+ */
+declare function getContentImageFolder(collectionPath: string, contentId: string, contentFilePath: string): string | null;
+/**
+ * Detect the content structure type from a content file path
+ *
+ * @param contentFilePath - Absolute path to the content file
+ * @returns The detected content structure type
+ */
+declare function detectContentStructure(contentFilePath: string): ContentStructure;
+/**
+ * Options for recursive directory scanning
+ */
+interface ScanOptions {
+    /** Maximum recursion depth */
+    maxDepth: number;
+    /** Current recursion depth */
+    currentDepth: number;
+    /** Base path for calculating relative paths */
+    basePath: string;
+}
+/**
+ * Scan a directory recursively for image files
+ *
+ * Recursively scans the given directory for image files with supported extensions.
+ * Skips hidden folders (starting with .) and special folders (starting with _).
+ * Limits recursion to the specified maxDepth.
+ *
+ * @param dirPath - Absolute path to the directory to scan
+ * @param basePath - Base path for calculating relative paths
+ * @param options - Scan options including maxDepth and currentDepth
+ * @returns Array of discovered images
+ *
+ * @example
+ * ```typescript
+ * const images = await scanDirectoryForImages(
+ *   '/project/src/content/blog/my-post',
+ *   '/project/src/content/blog/my-post',
+ *   { maxDepth: 5, currentDepth: 0, basePath: '/project/src/content/blog/my-post' }
+ * );
+ * ```
+ */
+declare function scanDirectoryForImages(dirPath: string, basePath: string, options: ScanOptions): Promise<DiscoveredImage[]>;
+/**
+ * Calculate relative path from content file to image file
+ *
+ * Calculates the path that can be used in markdown to reference an image
+ * relative to the content file's location. The path always starts with ./
+ * to ensure it's treated as a relative reference.
+ *
+ * @param contentFilePath - Absolute path to the content file (e.g., /project/src/content/blog/my-post.md)
+ * @param imagePath - Absolute path to the image file (e.g., /project/src/content/blog/my-post/images/hero.jpg)
+ * @returns Relative path starting with ./ (e.g., ./my-post/images/hero.jpg)
+ *
+ * @example
+ * ```typescript
+ * // Flat file structure
+ * const relPath = calculateRelativePath(
+ *   '/project/src/content/blog/my-post.md',
+ *   '/project/src/content/blog/my-post/hero.jpg'
+ * );
+ * // Returns: './my-post/hero.jpg'
+ *
+ * // Folder-based structure
+ * const relPath = calculateRelativePath(
+ *   '/project/src/content/blog/my-post/index.md',
+ *   '/project/src/content/blog/my-post/images/hero.jpg'
+ * );
+ * // Returns: './images/hero.jpg'
+ *
+ * // Nested subfolder
+ * const relPath = calculateRelativePath(
+ *   '/project/src/content/blog/my-post/index.md',
+ *   '/project/src/content/blog/my-post/assets/photos/hero.jpg'
+ * );
+ * // Returns: './assets/photos/hero.jpg'
+ * ```
+ */
+declare function calculateRelativePath(contentFilePath: string, imagePath: string): string;
+/**
+ * Discover all images associated with a content item
+ *
+ * This is the main entry point for image discovery. It:
+ * 1. Locates the content file using getContentFilePath
+ * 2. Determines the image folder using getContentImageFolder
+ * 3. Scans the folder recursively using scanDirectoryForImages
+ * 4. Calculates relative paths for all discovered images
+ *
+ * @param collectionPath - Absolute path to the collection directory
+ * @param contentId - Content ID (slug)
+ * @param options - Optional discovery options
+ * @returns ImageDiscoveryResult with discovered images or error
+ *
+ * @example
+ * ```typescript
+ * const result = await discoverContentImages(
+ *   '/project/src/content/blog',
+ *   'my-post',
+ *   { maxDepth: 3 }
+ * );
+ *
+ * if (result.success) {
+ *   console.log(`Found ${result.images.length} images`);
+ *   for (const img of result.images) {
+ *     console.log(`- ${img.relativePath}`);
+ *   }
+ * }
+ * ```
+ */
+declare function discoverContentImages(collectionPath: string, contentId: string, options?: ImageDiscoveryOptions): Promise<ImageDiscoveryResult>;
+
+export { type ContentStructure, type ContentStructureResult, ContentWatcher, type CreateContentOptions, DEFAULT_IMAGE_CONFIG, type FileChangeEvent, type FileChangeType, FileModificationTracker, type ImageUploadOptions, type ImageUploadResult, type ReadContentOptions, type ReadFileResult, type UpdateContentOptions, type WatcherOptions, type WriteResult, calculateRelativePath, checkCollection, clearVersions, clearVersionsWithConfig, createContent, createContentWatcher, createEmptyManifest, deleteContent, deleteVersion, deleteVersionWithConfig, detectContentStructure, discoverContentImages, ensureGitignore, ensureStorageDirectory, extractSlug, generateExcerpt, generatePreview, generateSlug, generateUniqueSlug, generateVersionId, getCollectionCount, getCollectionSummaries, getContentFilePath, getContentImageFolder, getFileStats, getManifestPath, getOrRecoverManifest, getVersion, getVersionFilePath, getVersionStoragePath, getVersionWithConfig, getVersions, getVersionsWithConfig, isContentFile, isValidImageFile, isVersionHistoryEnabled, parseMultipartFormData, parseVersionId, pruneVersions, pruneVersionsWithConfig, readCollection, readContentFile, readManifest, recoverManifest, resolveVersionConfig, restoreVersion, restoreVersionWithConfig, saveVersion, saveVersionWithConfig, scanDirectoryForImages, toContentSummary, updateContent, uploadImage, writeManifest };