@imjp/writenex-astro 0.1.0 → 1.3.6

package/dist/filesystem/index.d.ts

@@ -1,7 +1,255 @@
-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 ImageConfig, V as VersionHistoryConfig, d as VersionResult, e as Version, f as VersionEntry, R as RestoreVersionOptions, g as RestoreResult, h as SaveVersionOptions, i as VersionManifest } from '../config-CliL0CoN.js';
 import { I as ImageDiscoveryOptions, a as ImageDiscoveryResult, D as DiscoveredImage } from '../image-FP7w5ZIs.js';
+import { C as ContentItem, a as ContentSummary } from '../content-TuL3GT66.js';
+import { C as ContentConflictError } from '../errors-C0iYiDTv.js';
+
+/**
+ * @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>;
 
 /**
  * @fileoverview Filesystem reader for content collections
@@ -171,281 +419,220 @@ declare function getFileStats(filePath: string): Promise<{
 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.
+ * @fileoverview Config-aware wrappers for version history operations
  *
- * ## 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
+ * 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/writer
+ * @module @writenex/astro/filesystem/version-config
+ * @see {@link saveVersion} - Core save function
+ * @see {@link getVersions} - Core list function
  */
 
 /**
- * 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
+ * Resolve version history configuration with defaults applied.
  *
- * @param text - Text to slugify
- * @returns URL-safe slug
+ * 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 generateSlug(text: string): string;
+declare function resolveVersionConfig(config?: VersionHistoryConfig): Required<VersionHistoryConfig>;
 /**
- * Generate a unique slug that doesn't conflict with existing files
+ * Check if version history is enabled in the configuration.
  *
- * @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
+ * @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 generateUniqueSlug(baseSlug: string, collectionPath: string, filePattern?: string): Promise<string>;
+declare function isVersionHistoryEnabled(config?: VersionHistoryConfig): boolean;
 /**
- * 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
+ * Save a version with automatic configuration resolution.
  *
- * 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
+ * This wrapper automatically applies configuration defaults and checks
+ * the enabled flag before delegating to the core saveVersion function.
  *
- * @param collectionPath - Absolute path to the collection directory
- * @param options - Content creation options
- * @returns WriteResult with success status and file info
+ * @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
- * // Flat structure
- * const result = await createContent('/project/src/content/blog', {
- *   frontmatter: { title: 'My New Post', pubDate: new Date() },
- *   body: '# Hello World',
- * });
+ * // 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.
  *
- * // 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',
- * });
+ * This wrapper automatically applies configuration defaults and checks
+ * the enabled flag before delegating to the core getVersions function.
  *
- * // 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',
- * });
+ * @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)
  *
- * // 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' },
- * });
+ * @example
+ * ```typescript
+ * const versions = await getVersionsWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   { storagePath: 'custom/versions' }
+ * );
  * ```
  */
-declare function createContent(collectionPath: string, options: CreateContentOptions): Promise<WriteResult>;
+declare function getVersionsWithConfig(projectRoot: string, collection: string, contentId: string, config?: VersionHistoryConfig): Promise<VersionEntry[]>;
 /**
- * Update an existing content file
+ * Get a specific version with automatic configuration resolution.
  *
- * 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.
+ * This wrapper automatically applies configuration defaults and checks
+ * the enabled flag before delegating to the core getVersion function.
  *
- * @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
+ * @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 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' },
- *   }
+ * const version = await getVersionWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   '2024-12-11T10-30-00-000Z'
  * );
  * ```
  */
-declare function updateContent(filePath: string, collectionPath: string, options: UpdateContentOptions): Promise<WriteResult>;
+declare function getVersionWithConfig(projectRoot: string, collection: string, contentId: string, versionId: string, config?: VersionHistoryConfig): Promise<Version | null>;
 /**
- * Delete a content file
+ * Delete a version with automatic configuration resolution.
  *
- * @param filePath - Absolute path to the content file
- * @returns WriteResult with success status
+ * 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 deleteContent('/project/src/content/blog/my-post.md');
+ * const result = await deleteVersionWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post',
+ *   '2024-12-11T10-30-00-000Z'
+ * );
  * ```
  */
-declare function deleteContent(filePath: string): Promise<WriteResult>;
-
+declare function deleteVersionWithConfig(projectRoot: string, collection: string, contentId: string, versionId: string, config?: VersionHistoryConfig): Promise<VersionResult>;
 /**
- * @fileoverview File watcher for detecting external changes
+ * Clear all versions with automatic configuration resolution.
  *
- * 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).
+ * This wrapper automatically applies configuration defaults before
+ * delegating to the core clearVersions function.
  *
- * @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
+ * @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
  *
- * Watches the src/content directory for changes and emits events
- * when files are added, modified, or deleted.
+ * @example
+ * ```typescript
+ * const result = await clearVersionsWithConfig(
+ *   '/project',
+ *   'blog',
+ *   'my-post'
+ * );
+ * ```
  */
-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;
-}
+declare function clearVersionsWithConfig(projectRoot: string, collection: string, contentId: string, config?: VersionHistoryConfig): Promise<VersionResult>;
 /**
- * Track file modification times for conflict detection
+ * 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 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;
-}
+declare function pruneVersionsWithConfig(projectRoot: string, collection: string, contentId: string, config?: VersionHistoryConfig): Promise<VersionResult>;
 /**
- * Create a content watcher instance
+ * 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 createContentWatcher(projectRoot: string, options?: WatcherOptions): ContentWatcher;
+declare function restoreVersionWithConfig(projectRoot: string, collection: string, contentId: string, versionId: string, contentFilePath: string, config?: VersionHistoryConfig, options?: RestoreVersionOptions): Promise<RestoreResult>;
 
 /**
  * @fileoverview Version history management for content files
@@ -702,591 +889,404 @@ declare function getVersions(projectRoot: string, collection: string, contentId:
 /**
  * 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.
+ * 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 delete
- * @param config - Partial version history configuration
- * @returns Result of the delete operation
+ * @param versionId - Version ID to retrieve
+ * @param config - Version history configuration
+ * @returns Full version data or null if not found
  *
  * @example
  * ```typescript
- * const result = await deleteVersionWithConfig(
+ * const version = await getVersion(
  *   '/project',
  *   'blog',
  *   'my-post',
- *   '2024-12-11T10-30-00-000Z'
+ *   '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 deleteVersionWithConfig(projectRoot: string, collection: string, contentId: string, versionId: string, config?: VersionHistoryConfig): Promise<VersionResult>;
+declare function getVersion(projectRoot: string, collection: string, contentId: string, versionId: string, config: Required<VersionHistoryConfig>): Promise<Version | null>;
 /**
- * Clear all versions with automatic configuration resolution.
+ * Delete a specific version.
  *
- * This wrapper automatically applies configuration defaults before
- * delegating to the core clearVersions function.
+ * 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 config - Partial version history configuration
- * @returns Result of the clear operation
+ * @param versionId - Version ID to delete
+ * @param config - Version history configuration
+ * @returns Result of the delete operation
  *
  * @example
  * ```typescript
- * const result = await clearVersionsWithConfig(
+ * const result = await deleteVersion(
  *   '/project',
  *   'blog',
- *   'my-post'
+ *   'my-post',
+ *   '2024-12-11T10-30-00-000Z',
+ *   { enabled: true, maxVersions: 20, storagePath: '.writenex/versions' }
  * );
+ *
+ * if (result.success) {
+ *   console.log('Version deleted');
+ * }
  * ```
  */
-declare function clearVersionsWithConfig(projectRoot: string, collection: string, contentId: string, config?: VersionHistoryConfig): Promise<VersionResult>;
+declare function deleteVersion(projectRoot: string, collection: string, contentId: string, versionId: string, config: Required<VersionHistoryConfig>): Promise<VersionResult>;
 /**
- * Prune old versions with automatic configuration resolution.
+ * Clear all versions for a content item.
  *
- * 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.
+ * 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 - Partial version history configuration
- * @returns Result of the prune operation
+ * @param config - Version history configuration
+ * @returns Result of the clear operation
  *
  * @example
  * ```typescript
- * // Uses custom maxVersions
- * const result = await pruneVersionsWithConfig(
+ * const result = await clearVersions(
  *   '/project',
  *   'blog',
  *   'my-post',
- *   { maxVersions: 10 }
+ *   { enabled: true, maxVersions: 20, storagePath: '.writenex/versions' }
  * );
+ *
+ * if (result.success) {
+ *   console.log('All versions cleared');
+ * }
  * ```
  */
-declare function pruneVersionsWithConfig(projectRoot: string, collection: string, contentId: string, config?: VersionHistoryConfig): Promise<VersionResult>;
+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 with automatic configuration resolution.
+ * Restore a version to current content.
  *
- * This wrapper automatically applies configuration defaults and checks
- * the enabled flag before delegating to the core restoreVersion function.
+ * 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 - Partial version history configuration
+ * @param config - Version history configuration
  * @param options - Restore options
  * @returns Result of the restore operation
  *
  * @example
  * ```typescript
- * const result = await restoreVersionWithConfig(
+ * const result = await restoreVersion(
  *   '/project',
  *   'blog',
  *   'my-post',
  *   '2024-12-11T10-30-00-000Z',
- *   '/project/src/content/blog/my-post.md'
+ *   '/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 restoreVersionWithConfig(projectRoot: string, collection: string, contentId: string, versionId: string, contentFilePath: string, config?: VersionHistoryConfig, options?: RestoreVersionOptions): Promise<RestoreResult>;
+declare function restoreVersion(projectRoot: string, collection: string, contentId: string, versionId: string, contentFilePath: string, config: Required<VersionHistoryConfig>, options?: RestoreVersionOptions): Promise<RestoreResult>;
 
 /**
- * @fileoverview Image handling for content collections
+ * @fileoverview File watcher for detecting external changes
  *
- * This module provides functions for uploading and managing images
- * in content collections with support for different storage strategies.
+ * 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).
  *
- * ## Strategies:
- * - colocated: Images stored alongside content files
- * - public: Images stored in public directory
- * - custom: User-defined storage paths
+ * @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
  *
- * @module @writenex/astro/filesystem/images
+ * 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;
 
 /**
- * Default image configuration
+ * @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
  */
-declare const DEFAULT_IMAGE_CONFIG: ImageConfig;
+
 /**
- * Result of image upload operation
+ * Options for creating content
  */
-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;
+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 image upload
+ * Options for updating content
  */
-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;
+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;
 }
 /**
- * Validate image file
- *
- * @param filename - Original filename
- * @returns True if valid image file
+ * Result of a write operation
  */
-declare function isValidImageFile(filename: string): boolean;
+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;
+}
 /**
- * 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",
- * });
+ * Generate a URL-safe slug from a string
  *
- * if (result.success) {
- *   console.log(result.path); // "./my-post/hero-abc123.jpg"
- * }
- * ```
+ * @param text - Text to slugify
+ * @returns URL-safe slug
  */
-declare function uploadImage(options: ImageUploadOptions): Promise<ImageUploadResult>;
+declare function generateSlug(text: string): string;
 /**
- * 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.
+ * Generate a unique slug that doesn't conflict with existing files
  *
- * @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
+ * @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
  */
-interface ContentStructureResult {
-    /** Detected structure type */
-    structure: ContentStructure;
-    /** Path to the image folder (null if doesn't exist) */
-    imageFolderPath: string | null;
-}
+declare function generateUniqueSlug(baseSlug: string, collectionPath: string, filePattern?: string): Promise<string>;
 /**
- * Detect content structure and get the image folder path
+ * Create a new content file in a collection
  *
- * 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
+ * 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 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
+ * @param options - Content creation options
+ * @returns WriteResult with success status and file info
  *
  * @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)
+ * // 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 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.
+ * const result = await createContent('/project/src/content/blog', {
+ *   frontmatter: { title: 'My New Post', pubDate: new Date() },
+ *   body: '# Hello World',
+ *   filePattern: '{slug}/index.md',
+ * });
  *
- * @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
+ * // 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',
+ * });
  *
- * @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' }
- * );
+ * // 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 scanDirectoryForImages(dirPath: string, basePath: string, options: ScanOptions): Promise<DiscoveredImage[]>;
+declare function createContent(collectionPath: string, options: CreateContentOptions): Promise<WriteResult>;
 /**
- * Calculate relative path from content file to image file
+ * Update an existing content 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.
+ * 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 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)
+ * @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
- * // Flat file structure
- * const relPath = calculateRelativePath(
+ * const result = await updateContent(
  *   '/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'
+ *   '/project/src/content/blog',
+ *   {
+ *     frontmatter: { title: 'Updated Title' },
+ *     body: '# Updated Content',
+ *     projectRoot: '/project',
+ *     collection: 'blog',
+ *     versionHistoryConfig: { enabled: true, maxVersions: 20, storagePath: '.writenex/versions' },
+ *   }
  * );
- * // Returns: './assets/photos/hero.jpg'
  * ```
  */
-declare function calculateRelativePath(contentFilePath: string, imagePath: string): string;
+declare function updateContent(filePath: string, collectionPath: string, options: UpdateContentOptions): Promise<WriteResult>;
 /**
- * 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
+ * Delete a content file
  *
- * @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
+ * @param filePath - Absolute path to the content file
+ * @returns WriteResult with success status
  *
  * @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}`);
- *   }
- * }
+ * const result = await deleteContent('/project/src/content/blog/my-post.md');
  * ```
  */
-declare function discoverContentImages(collectionPath: string, contentId: string, options?: ImageDiscoveryOptions): Promise<ImageDiscoveryResult>;
+declare function deleteContent(filePath: string): Promise<WriteResult>;
 
 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 };