@imjp/writenex-astro 0.1.0

package/dist/loader-CrdnaAWR.d.ts

@@ -0,0 +1,327 @@
+import { z } from 'zod';
+import { a as WritenexConfig } from './config-BmEdBDo_.js';
+
+/**
+ * @fileoverview Configuration schema and validation for @writenex/astro
+ *
+ * This module provides Zod schemas for validating Writenex configuration
+ * and a helper function for defining type-safe configurations.
+ *
+ * @module @writenex/astro/config/schema
+ */
+
+/**
+ * Main Writenex configuration schema
+ */
+declare const writenexConfigSchema: z.ZodObject<{
+    collections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        filePattern: z.ZodOptional<z.ZodString>;
+        previewUrl: z.ZodOptional<z.ZodString>;
+        schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<["string", "number", "boolean", "date", "array", "image", "object"]>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            default: z.ZodOptional<z.ZodUnknown>;
+            items: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: "string" | "number" | "boolean" | "object" | "date" | "array" | "image";
+            required?: boolean | undefined;
+            default?: unknown;
+            items?: string | undefined;
+            description?: string | undefined;
+        }, {
+            type: "string" | "number" | "boolean" | "object" | "date" | "array" | "image";
+            required?: boolean | undefined;
+            default?: unknown;
+            items?: string | undefined;
+            description?: string | undefined;
+        }>>>;
+        images: z.ZodOptional<z.ZodObject<{
+            strategy: z.ZodEnum<["colocated", "public", "custom"]>;
+            publicPath: z.ZodOptional<z.ZodString>;
+            storagePath: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            strategy: "colocated" | "public" | "custom";
+            publicPath?: string | undefined;
+            storagePath?: string | undefined;
+        }, {
+            strategy: "colocated" | "public" | "custom";
+            publicPath?: string | undefined;
+            storagePath?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        path: string;
+        images?: {
+            strategy: "colocated" | "public" | "custom";
+            publicPath?: string | undefined;
+            storagePath?: string | undefined;
+        } | undefined;
+        filePattern?: string | undefined;
+        previewUrl?: string | undefined;
+        schema?: Record<string, {
+            type: "string" | "number" | "boolean" | "object" | "date" | "array" | "image";
+            required?: boolean | undefined;
+            default?: unknown;
+            items?: string | undefined;
+            description?: string | undefined;
+        }> | undefined;
+    }, {
+        name: string;
+        path: string;
+        images?: {
+            strategy: "colocated" | "public" | "custom";
+            publicPath?: string | undefined;
+            storagePath?: string | undefined;
+        } | undefined;
+        filePattern?: string | undefined;
+        previewUrl?: string | undefined;
+        schema?: Record<string, {
+            type: "string" | "number" | "boolean" | "object" | "date" | "array" | "image";
+            required?: boolean | undefined;
+            default?: unknown;
+            items?: string | undefined;
+            description?: string | undefined;
+        }> | undefined;
+    }>, "many">>;
+    images: z.ZodOptional<z.ZodObject<{
+        strategy: z.ZodEnum<["colocated", "public", "custom"]>;
+        publicPath: z.ZodOptional<z.ZodString>;
+        storagePath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "colocated" | "public" | "custom";
+        publicPath?: string | undefined;
+        storagePath?: string | undefined;
+    }, {
+        strategy: "colocated" | "public" | "custom";
+        publicPath?: string | undefined;
+        storagePath?: string | undefined;
+    }>>;
+    editor: z.ZodOptional<z.ZodObject<{
+        autosave: z.ZodOptional<z.ZodBoolean>;
+        autosaveInterval: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        autosave?: boolean | undefined;
+        autosaveInterval?: number | undefined;
+    }, {
+        autosave?: boolean | undefined;
+        autosaveInterval?: number | undefined;
+    }>>;
+    discovery: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        ignore?: string[] | undefined;
+    }, {
+        enabled: boolean;
+        ignore?: string[] | undefined;
+    }>>;
+    versionHistory: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        maxVersions: z.ZodOptional<z.ZodNumber>;
+        storagePath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        storagePath?: string | undefined;
+        enabled?: boolean | undefined;
+        maxVersions?: number | undefined;
+    }, {
+        storagePath?: string | undefined;
+        enabled?: boolean | undefined;
+        maxVersions?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    collections?: {
+        name: string;
+        path: string;
+        images?: {
+            strategy: "colocated" | "public" | "custom";
+            publicPath?: string | undefined;
+            storagePath?: string | undefined;
+        } | undefined;
+        filePattern?: string | undefined;
+        previewUrl?: string | undefined;
+        schema?: Record<string, {
+            type: "string" | "number" | "boolean" | "object" | "date" | "array" | "image";
+            required?: boolean | undefined;
+            default?: unknown;
+            items?: string | undefined;
+            description?: string | undefined;
+        }> | undefined;
+    }[] | undefined;
+    images?: {
+        strategy: "colocated" | "public" | "custom";
+        publicPath?: string | undefined;
+        storagePath?: string | undefined;
+    } | undefined;
+    editor?: {
+        autosave?: boolean | undefined;
+        autosaveInterval?: number | undefined;
+    } | undefined;
+    discovery?: {
+        enabled: boolean;
+        ignore?: string[] | undefined;
+    } | undefined;
+    versionHistory?: {
+        storagePath?: string | undefined;
+        enabled?: boolean | undefined;
+        maxVersions?: number | undefined;
+    } | undefined;
+}, {
+    collections?: {
+        name: string;
+        path: string;
+        images?: {
+            strategy: "colocated" | "public" | "custom";
+            publicPath?: string | undefined;
+            storagePath?: string | undefined;
+        } | undefined;
+        filePattern?: string | undefined;
+        previewUrl?: string | undefined;
+        schema?: Record<string, {
+            type: "string" | "number" | "boolean" | "object" | "date" | "array" | "image";
+            required?: boolean | undefined;
+            default?: unknown;
+            items?: string | undefined;
+            description?: string | undefined;
+        }> | undefined;
+    }[] | undefined;
+    images?: {
+        strategy: "colocated" | "public" | "custom";
+        publicPath?: string | undefined;
+        storagePath?: string | undefined;
+    } | undefined;
+    editor?: {
+        autosave?: boolean | undefined;
+        autosaveInterval?: number | undefined;
+    } | undefined;
+    discovery?: {
+        enabled: boolean;
+        ignore?: string[] | undefined;
+    } | undefined;
+    versionHistory?: {
+        storagePath?: string | undefined;
+        enabled?: boolean | undefined;
+        maxVersions?: number | undefined;
+    } | undefined;
+}>;
+/**
+ * Schema for integration options
+ */
+declare const writenexOptionsSchema: z.ZodObject<{
+    allowProduction: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    allowProduction?: boolean | undefined;
+}, {
+    allowProduction?: boolean | undefined;
+}>;
+/**
+ * Helper function for defining type-safe Writenex configuration.
+ *
+ * This function provides IDE autocompletion and type checking for
+ * the configuration object. It's the recommended way to create
+ * a writenex.config.ts file.
+ *
+ * @param config - The Writenex configuration object
+ * @returns The same configuration object (identity function for type safety)
+ *
+ * @example
+ * ```typescript
+ * // writenex.config.ts
+ * import { defineConfig } from '@writenex/astro';
+ *
+ * export default defineConfig({
+ *   collections: [
+ *     {
+ *       name: 'blog',
+ *       path: 'src/content/blog',
+ *       filePattern: '{slug}.md',
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+declare function defineConfig(config: WritenexConfig): WritenexConfig;
+/**
+ * Validate a Writenex configuration object
+ *
+ * @param config - The configuration to validate
+ * @returns Validation result with success status and parsed data or errors
+ */
+declare function validateConfig(config: unknown): z.SafeParseReturnType<unknown, WritenexConfig>;
+
+/**
+ * @fileoverview Configuration loader for @writenex/astro
+ *
+ * This module handles loading Writenex configuration from various sources:
+ * - writenex.config.ts (TypeScript)
+ * - writenex.config.js (JavaScript)
+ * - writenex.config.mjs (ES Module)
+ *
+ * The loader searches for configuration files in the project root and
+ * applies default values for any missing options.
+ *
+ * @module @writenex/astro/config/loader
+ */
+
+/**
+ * Result of loading configuration
+ */
+interface LoadConfigResult {
+    /** The loaded and validated configuration with defaults applied */
+    config: Required<WritenexConfig>;
+    /** Path to the configuration file (if found) */
+    configPath: string | null;
+    /** Whether a configuration file was found */
+    hasConfigFile: boolean;
+    /** Any warnings generated during loading */
+    warnings: string[];
+}
+/**
+ * Find the configuration file in the project root
+ *
+ * @param projectRoot - The root directory of the Astro project
+ * @returns Path to the configuration file, or null if not found
+ */
+declare function findConfigFile(projectRoot: string): string | null;
+/**
+ * Load Writenex configuration from the project root
+ *
+ * This function:
+ * 1. Searches for a configuration file in the project root
+ * 2. Loads and validates the configuration if found
+ * 3. Applies default values for any missing options
+ * 4. Returns the resolved configuration
+ *
+ * If no configuration file is found, default configuration is returned
+ * with auto-discovery enabled.
+ *
+ * @param projectRoot - The root directory of the Astro project
+ * @returns LoadConfigResult with the resolved configuration
+ *
+ * @example
+ * ```typescript
+ * const { config, hasConfigFile, warnings } = await loadConfig('/path/to/project');
+ *
+ * if (!hasConfigFile) {
+ *   console.log('Using auto-discovery mode');
+ * }
+ *
+ * if (warnings.length > 0) {
+ *   warnings.forEach(w => console.warn(w));
+ * }
+ * ```
+ */
+declare function loadConfig(projectRoot: string): Promise<LoadConfigResult>;
+/**
+ * Check if a content directory exists in the project
+ *
+ * @param projectRoot - The root directory of the Astro project
+ * @param contentPath - Relative path to the content directory
+ * @returns True if the content directory exists
+ */
+declare function contentDirectoryExists(projectRoot: string, contentPath?: string): boolean;
+
+export { type LoadConfigResult as L, writenexOptionsSchema as a, contentDirectoryExists as c, defineConfig as d, findConfigFile as f, loadConfig as l, validateConfig as v, writenexConfigSchema as w };

package/dist/server/index.d.ts

@@ -0,0 +1,357 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Connect } from 'vite';
+import { a as WritenexConfig } from '../config-BmEdBDo_.js';
+import { W as WritenexError } from '../errors-C0iYiDTv.js';
+import { D as DiscoveredCollection, a as ContentSummary } from '../content-BWR52vD-.js';
+import { D as DiscoveredImage } from '../image-FP7w5ZIs.js';
+
+/**
+ * @fileoverview Vite middleware for Writenex routes
+ *
+ * This module provides the main middleware handler that intercepts requests
+ * to Writenex routes (/_writenex/*) and delegates to appropriate handlers.
+ *
+ * ## Route Structure:
+ * - `/_writenex` - Editor UI (HTML page with React app)
+ * - `/_writenex/api/*` - API endpoints for CRUD operations
+ * - `/_writenex/assets/*` - Static assets (JS, CSS)
+ *
+ * @module @writenex/astro/server/middleware
+ */
+
+/**
+ * Middleware context passed to handlers
+ */
+interface MiddlewareContext {
+    /** Base path for Writenex routes */
+    basePath: string;
+    /** Project root directory */
+    projectRoot: string;
+    /** Resolved Writenex configuration */
+    config: Required<WritenexConfig>;
+    /** Astro trailingSlash setting for preview URLs */
+    trailingSlash: "always" | "never" | "ignore";
+}
+/**
+ * Create the Writenex middleware handler
+ *
+ * @param context - Middleware context with configuration
+ * @returns Connect middleware function
+ *
+ * @example
+ * ```typescript
+ * const middleware = createMiddleware({
+ *   basePath: '/_writenex',
+ *   projectRoot: '/path/to/project',
+ *   config: resolvedConfig,
+ * });
+ *
+ * server.middlewares.use(middleware);
+ * ```
+ */
+declare function createMiddleware(context: MiddlewareContext): Connect.NextHandleFunction;
+/**
+ * Parse URL query parameters
+ *
+ * @param url - The URL string to parse
+ * @returns Object with query parameters
+ */
+declare function parseQueryParams(url: string): Record<string, string>;
+/**
+ * Parse request body as JSON
+ *
+ * @param req - The incoming request
+ * @returns Parsed JSON body or null
+ */
+declare function parseJsonBody(req: IncomingMessage): Promise<unknown | null>;
+/**
+ * Send JSON response
+ *
+ * @param res - The server response
+ * @param data - Data to send as JSON
+ * @param statusCode - HTTP status code (default: 200)
+ */
+declare function sendJson(res: ServerResponse, data: unknown, statusCode?: number): void;
+/**
+ * Send error response
+ *
+ * @param res - The server response
+ * @param message - Error message
+ * @param statusCode - HTTP status code (default: 400)
+ */
+declare function sendError(res: ServerResponse, message: string, statusCode?: number): void;
+/**
+ * Send WritenexError response
+ *
+ * Automatically uses the error's HTTP status code and formats
+ * the response using the error's toJSON method.
+ *
+ * @param res - The server response
+ * @param error - WritenexError instance
+ */
+declare function sendWritenexError(res: ServerResponse, error: WritenexError): void;
+
+/**
+ * @fileoverview API route handlers for Writenex
+ *
+ * This module provides the API router that handles CRUD operations
+ * for content collections.
+ *
+ * ## API Endpoints:
+ * - GET /api/collections - List all collections
+ * - GET /api/content/:collection - List content in collection
+ * - GET /api/content/:collection/:id - Get single content item
+ * - POST /api/content/:collection - Create new content
+ * - PUT /api/content/:collection/:id - Update content
+ * - DELETE /api/content/:collection/:id - Delete content
+ * - GET /api/images/:collection/:contentId - Discover images for content
+ * - GET /api/images/:collection/:contentId/* - Serve image file
+ * - POST /api/images - Upload image
+ * - GET /api/versions/:collection/:id - List versions
+ * - GET /api/versions/:collection/:id/:versionId - Get version
+ * - POST /api/versions/:collection/:id - Create manual version
+ * - POST /api/versions/:collection/:id/:versionId/restore - Restore version
+ * - GET /api/versions/:collection/:id/:versionId/diff - Get diff data
+ * - DELETE /api/versions/:collection/:id/:versionId - Delete version
+ * - DELETE /api/versions/:collection/:id - Clear all versions
+ *
+ * @module @writenex/astro/server/routes
+ */
+
+/**
+ * Create the API router
+ *
+ * @param context - Middleware context
+ * @returns Router function that handles API requests
+ */
+declare function createApiRouter(context: MiddlewareContext): (req: IncomingMessage, res: ServerResponse, path: string) => Promise<void>;
+
+/**
+ * @fileoverview Static asset serving for Writenex editor
+ *
+ * This module handles serving the editor UI HTML and static assets
+ * (JavaScript, CSS) for the Writenex editor interface.
+ *
+ * ## Asset Strategy:
+ * - In development: Serve from source with Vite transform
+ * - In production: Serve pre-bundled assets from dist/client
+ *
+ * @module @writenex/astro/server/assets
+ */
+
+/**
+ * Serve the editor HTML page
+ *
+ * This generates the HTML shell that loads the React editor application.
+ * The actual React components will be loaded via the bundled client assets.
+ *
+ * @param _req - The incoming request
+ * @param res - The server response
+ * @param context - Middleware context
+ */
+declare function serveEditorHtml(_req: IncomingMessage, res: ServerResponse, context: MiddlewareContext): Promise<void>;
+/**
+ * Serve static assets (JS, CSS, etc.)
+ *
+ * @param _req - The incoming request
+ * @param res - The server response
+ * @param assetPath - Path to the asset (relative to assets directory)
+ * @param _context - Middleware context
+ */
+declare function serveAsset(_req: IncomingMessage, res: ServerResponse, assetPath: string, _context: MiddlewareContext): Promise<void>;
+/**
+ * Get the path to bundled client assets
+ *
+ * @returns Path to the client dist directory
+ */
+declare function getClientDistPath(): string;
+/**
+ * Check if client assets are bundled
+ *
+ * @returns True if bundled assets exist
+ */
+declare function hasClientBundle(): boolean;
+
+/**
+ * @fileoverview Server-side caching for Writenex
+ *
+ * Provides in-memory caching for collection discovery and content summaries
+ * to improve performance by avoiding repeated filesystem operations.
+ *
+ * ## Features:
+ * - TTL-based cache expiration
+ * - Per-collection content caching
+ * - Image discovery caching
+ * - Manual cache invalidation
+ * - Integration with file watcher for automatic invalidation
+ *
+ * @module @writenex/astro/server/cache
+ */
+
+/**
+ * Server-side cache for collection and content data
+ *
+ * This cache stores:
+ * - Collection discovery results (list of collections with metadata)
+ * - Content summaries per collection (list of content items)
+ * - Discovered images per content item
+ *
+ * Cache invalidation happens:
+ * - Automatically when TTL expires
+ * - Manually via invalidate methods
+ * - Via file watcher integration
+ */
+declare class ServerCache {
+    /** Cache for collection discovery results */
+    private collectionsCache;
+    /** Cache for content summaries, keyed by collection name */
+    private contentCache;
+    /** Cache for discovered images, keyed by "collection:contentId" */
+    private imagesCache;
+    /** Time-to-live for cache entries in milliseconds */
+    private ttl;
+    /** Whether file watcher is integrated (allows longer TTL) */
+    private hasWatcher;
+    constructor(options?: {
+        ttl?: number;
+        hasWatcher?: boolean;
+    });
+    /**
+     * Enable file watcher integration
+     *
+     * When watcher is enabled, cache can use longer TTL since
+     * invalidation happens via watcher events.
+     */
+    enableWatcher(): void;
+    /**
+     * Check if a cache entry is still valid
+     */
+    private isValid;
+    /**
+     * Get cached collections if valid
+     *
+     * @returns Cached collections or null if expired/not cached
+     */
+    getCollections(): DiscoveredCollection[] | null;
+    /**
+     * Set collections cache
+     *
+     * @param collections - Collections to cache
+     */
+    setCollections(collections: DiscoveredCollection[]): void;
+    /**
+     * Invalidate collections cache
+     */
+    invalidateCollections(): void;
+    /**
+     * Get cached content summaries for a collection if valid
+     *
+     * @param collection - Collection name
+     * @returns Cached content summaries or null if expired/not cached
+     */
+    getContent(collection: string): ContentSummary[] | null;
+    /**
+     * Set content cache for a collection
+     *
+     * @param collection - Collection name
+     * @param items - Content summaries to cache
+     */
+    setContent(collection: string, items: ContentSummary[]): void;
+    /**
+     * Invalidate content cache for a specific collection
+     *
+     * @param collection - Collection name to invalidate
+     */
+    invalidateContent(collection: string): void;
+    /**
+     * Invalidate all content caches
+     */
+    invalidateAllContent(): void;
+    /**
+     * Generate cache key for image cache
+     *
+     * @param collection - Collection name
+     * @param contentId - Content ID
+     * @returns Cache key string
+     */
+    private getImagesCacheKey;
+    /**
+     * Get cached images for a content item if valid
+     *
+     * @param collection - Collection name
+     * @param contentId - Content ID
+     * @returns Cached images or null if expired/not cached
+     */
+    getImages(collection: string, contentId: string): DiscoveredImage[] | null;
+    /**
+     * Set images cache for a content item
+     *
+     * @param collection - Collection name
+     * @param contentId - Content ID
+     * @param images - Discovered images to cache
+     */
+    setImages(collection: string, contentId: string, images: DiscoveredImage[]): void;
+    /**
+     * Invalidate image cache for a specific content item
+     *
+     * @param collection - Collection name
+     * @param contentId - Content ID
+     */
+    invalidateImages(collection: string, contentId: string): void;
+    /**
+     * Invalidate all image caches for a collection
+     *
+     * @param collection - Collection name
+     */
+    invalidateCollectionImages(collection: string): void;
+    /**
+     * Invalidate all image caches
+     */
+    invalidateAllImages(): void;
+    /**
+     * Invalidate all caches
+     *
+     * Called when a major change occurs that affects everything.
+     */
+    invalidateAll(): void;
+    /**
+     * Handle file change event from watcher
+     *
+     * Intelligently invalidates only the affected caches.
+     *
+     * @param type - Type of file change (add, change, unlink)
+     * @param collection - Collection that was affected
+     * @param contentId - Optional content ID for targeted image cache invalidation
+     */
+    handleFileChange(type: "add" | "change" | "unlink", collection: string, contentId?: string): void;
+    /**
+     * Get cache statistics for debugging
+     *
+     * @returns Object with cache stats
+     */
+    getStats(): {
+        collectionsValid: boolean;
+        contentCollections: string[];
+        cachedImages: string[];
+        ttl: number;
+        hasWatcher: boolean;
+    };
+}
+/**
+ * Get or create the global cache instance
+ *
+ * @param options - Cache options (only used on first call)
+ * @returns The global cache instance
+ */
+declare function getCache(options?: {
+    ttl?: number;
+    hasWatcher?: boolean;
+}): ServerCache;
+/**
+ * Reset the global cache instance
+ *
+ * Useful for testing or when configuration changes.
+ */
+declare function resetCache(): void;
+
+export { type MiddlewareContext, ServerCache, createApiRouter, createMiddleware, getCache, getClientDistPath, hasClientBundle, parseJsonBody, parseQueryParams, resetCache, sendError, sendJson, sendWritenexError, serveAsset, serveEditorHtml };