@imjp/writenex-astro 0.1.0

package/src/config/loader.ts

@@ -0,0 +1,174 @@
+/**
+ * @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
+ */
+
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { join, resolve } from "node:path";
+import type { WritenexConfig } from "@/types";
+import { validateConfig } from "./schema";
+import { applyConfigDefaults } from "./defaults";
+
+/**
+ * Supported configuration file names in order of priority
+ */
+const CONFIG_FILE_NAMES = [
+  "writenex.config.ts",
+  "writenex.config.mts",
+  "writenex.config.js",
+  "writenex.config.mjs",
+];
+
+/**
+ * Result of loading configuration
+ */
+export 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
+ */
+export function findConfigFile(projectRoot: string): string | null {
+  for (const fileName of CONFIG_FILE_NAMES) {
+    const filePath = join(projectRoot, fileName);
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+
+/**
+ * Load configuration from a file
+ *
+ * @param configPath - Path to the configuration file
+ * @returns The loaded configuration object
+ * @throws Error if the file cannot be loaded or parsed
+ */
+async function loadConfigFile(configPath: string): Promise<WritenexConfig> {
+  try {
+    // Convert to file URL for dynamic import (required for Windows compatibility)
+    const fileUrl = pathToFileURL(resolve(configPath)).href;
+
+    // Dynamic import the configuration file
+    const module = await import(fileUrl);
+
+    // Support both default export and named export
+    const config = module.default ?? module.config ?? module;
+
+    return config as WritenexConfig;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to load configuration from ${configPath}: ${message}`
+    );
+  }
+}
+
+/**
+ * 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));
+ * }
+ * ```
+ */
+export async function loadConfig(
+  projectRoot: string
+): Promise<LoadConfigResult> {
+  const warnings: string[] = [];
+  let userConfig: WritenexConfig = {};
+  let configPath: string | null = null;
+  let hasConfigFile = false;
+
+  // Try to find and load configuration file
+  configPath = findConfigFile(projectRoot);
+
+  if (configPath) {
+    hasConfigFile = true;
+
+    try {
+      userConfig = await loadConfigFile(configPath);
+
+      // Validate the loaded configuration
+      const validationResult = validateConfig(userConfig);
+
+      if (!validationResult.success) {
+        const errors = validationResult.error.errors
+          .map((e) => `${e.path.join(".")}: ${e.message}`)
+          .join(", ");
+        warnings.push(`Configuration validation warnings: ${errors}`);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      warnings.push(`Failed to load config file: ${message}. Using defaults.`);
+      userConfig = {};
+    }
+  }
+
+  // Apply defaults to the configuration
+  const config = applyConfigDefaults(userConfig);
+
+  return {
+    config,
+    configPath,
+    hasConfigFile,
+    warnings,
+  };
+}
+
+/**
+ * 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
+ */
+export function contentDirectoryExists(
+  projectRoot: string,
+  contentPath: string = "src/content"
+): boolean {
+  const fullPath = join(projectRoot, contentPath);
+  return existsSync(fullPath);
+}

package/src/config/schema.ts

@@ -0,0 +1,161 @@
+/**
+ * @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
+ */
+
+import { z } from "zod";
+import type { WritenexConfig } from "@/types";
+
+/**
+ * Schema for field type definitions
+ */
+const fieldTypeSchema = z.enum([
+  "string",
+  "number",
+  "boolean",
+  "date",
+  "array",
+  "image",
+  "object",
+]);
+
+/**
+ * Schema for individual schema field definition
+ */
+const schemaFieldSchema = z.object({
+  type: fieldTypeSchema,
+  required: z.boolean().optional(),
+  default: z.unknown().optional(),
+  items: z.string().optional(),
+  description: z.string().optional(),
+});
+
+/**
+ * Schema for collection schema (record of field definitions)
+ */
+const collectionSchemaSchema = z.record(z.string(), schemaFieldSchema);
+
+/**
+ * Schema for image strategy
+ */
+const imageStrategySchema = z.enum(["colocated", "public", "custom"]);
+
+/**
+ * Schema for image configuration
+ */
+const imageConfigSchema = z.object({
+  strategy: imageStrategySchema,
+  publicPath: z.string().optional(),
+  storagePath: z.string().optional(),
+});
+
+/**
+ * Schema for collection configuration
+ */
+const collectionConfigSchema = z.object({
+  name: z.string().min(1, "Collection name is required"),
+  path: z.string().min(1, "Collection path is required"),
+  filePattern: z.string().optional(),
+  previewUrl: z.string().optional(),
+  schema: collectionSchemaSchema.optional(),
+  images: imageConfigSchema.optional(),
+});
+
+/**
+ * Schema for discovery configuration
+ */
+const discoveryConfigSchema = z.object({
+  enabled: z.boolean(),
+  ignore: z.array(z.string()).optional(),
+});
+
+/**
+ * Schema for editor configuration
+ */
+const editorConfigSchema = z.object({
+  autosave: z.boolean().optional(),
+  autosaveInterval: z.number().positive().optional(),
+});
+
+/**
+ * Schema for version history configuration
+ */
+const versionHistoryConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  maxVersions: z.number().int().positive().optional(),
+  storagePath: z.string().optional(),
+});
+
+/**
+ * Main Writenex configuration schema
+ */
+export const writenexConfigSchema = z.object({
+  collections: z.array(collectionConfigSchema).optional(),
+  images: imageConfigSchema.optional(),
+  editor: editorConfigSchema.optional(),
+  discovery: discoveryConfigSchema.optional(),
+  versionHistory: versionHistoryConfigSchema.optional(),
+});
+
+/**
+ * Schema for integration options
+ */
+export const writenexOptionsSchema = z.object({
+  allowProduction: z.boolean().optional(),
+});
+
+/**
+ * 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',
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export function defineConfig(config: WritenexConfig): WritenexConfig {
+  // Validate the configuration
+  const result = writenexConfigSchema.safeParse(config);
+
+  if (!result.success) {
+    const errors = result.error.errors
+      .map((e) => `  - ${e.path.join(".")}: ${e.message}`)
+      .join("\n");
+    console.warn(`[writenex] Invalid configuration:\n${errors}`);
+  }
+
+  return config;
+}
+
+/**
+ * Validate a Writenex configuration object
+ *
+ * @param config - The configuration to validate
+ * @returns Validation result with success status and parsed data or errors
+ */
+export function validateConfig(
+  config: unknown
+): z.SafeParseReturnType<unknown, WritenexConfig> {
+  return writenexConfigSchema.safeParse(config);
+}

package/src/core/constants.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Shared constants for @writenex/astro
+ *
+ * This module provides centralized constants used across the integration,
+ * including version information, default paths, and configuration limits.
+ *
+ * @module @writenex/astro/core/constants
+ */
+
+/**
+ * Current version of the @writenex/astro package
+ */
+export const WRITENEX_VERSION = "1.0.0";
+
+/**
+ * Default base path for the Writenex editor UI
+ */
+export const DEFAULT_BASE_PATH = "/_writenex";
+
+/**
+ * Default API path for Writenex API endpoints
+ */
+export const DEFAULT_API_PATH = "/_writenex/api";
+
+/**
+ * Supported image MIME types for upload
+ */
+export const SUPPORTED_IMAGE_TYPES = [
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+  "image/svg+xml",
+] as const;
+
+/**
+ * Maximum allowed image file size in bytes (10MB)
+ */
+export const MAX_IMAGE_SIZE = 10 * 1024 * 1024;