@imjp/writenex-astro 0.1.0

package/src/integration.ts

@@ -0,0 +1,228 @@
+/**
+ * @fileoverview Astro integration for Writenex visual editor
+ *
+ * This module provides the main Astro integration that injects the Writenex
+ * editor UI and API routes into an Astro project.
+ *
+ * ## Features:
+ * - Injects editor UI at /_writenex
+ * - Provides API routes for content CRUD operations
+ * - Auto-discovers content collections
+ * - Production guard to prevent accidental exposure
+ *
+ * ## Usage:
+ * ```typescript
+ * // astro.config.mjs
+ * import { defineConfig } from 'astro/config';
+ * import writenex from '@writenex/astro';
+ *
+ * export default defineConfig({
+ *   integrations: [writenex()],
+ * });
+ * ```
+ *
+ * @module @writenex/astro/integration
+ */
+
+import type { AstroIntegration } from "astro";
+import type { WritenexOptions, WritenexConfig } from "@/types";
+import { loadConfig } from "@/config/loader";
+import { createMiddleware } from "@/server/middleware";
+import { ContentWatcher } from "@/filesystem/watcher";
+import { getCache } from "@/server/cache";
+
+/**
+ * Default base path for the Writenex editor UI
+ */
+const DEFAULT_BASE_PATH = "/_writenex";
+
+/**
+ * Package name for logging
+ */
+const PACKAGE_NAME = "@writenex/astro";
+
+/**
+ * Creates the Writenex Astro integration.
+ *
+ * This integration injects the Writenex visual editor into your Astro project,
+ * providing a WYSIWYG interface for editing content collections.
+ *
+ * @param options - Integration options
+ * @param options.allowProduction - Allow running in production (default: false)
+ * @returns Astro integration object
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * export default defineConfig({
+ *   integrations: [writenex()],
+ * });
+ *
+ * // With options
+ * export default defineConfig({
+ *   integrations: [
+ *     writenex({
+ *       allowProduction: true,  // Enable in production (use with caution)
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export default function writenex(options?: WritenexOptions): AstroIntegration {
+  const { allowProduction = false } = options ?? {};
+
+  // Use fixed base path for consistency and branding
+  const basePath = DEFAULT_BASE_PATH;
+
+  // Track if we should be active
+  let isActive = true;
+
+  // Store loaded configuration
+  let resolvedConfig: Required<WritenexConfig> | null = null;
+
+  // Store project root
+  let projectRoot = "";
+
+  // Store Astro's trailingSlash setting
+  let astroTrailingSlash: "always" | "never" | "ignore" = "ignore";
+
+  // File watcher instance
+  let watcher: ContentWatcher | null = null;
+
+  // Track if editor URL has been logged (to avoid duplicate logs)
+  let hasLoggedEditorUrl = false;
+
+  return {
+    name: PACKAGE_NAME,
+    hooks: {
+      /**
+       * Configuration setup hook
+       *
+       * This hook runs during Astro's config resolution phase.
+       * We use it to:
+       * 1. Check if we should run (production guard)
+       * 2. Load Writenex configuration
+       * 3. Register any necessary Vite plugins
+       */
+      "astro:config:setup": async ({ command, logger, config }) => {
+        // Production guard: disable in production unless explicitly allowed
+        if (command === "build" && !allowProduction) {
+          logger.warn(
+            "Disabled in production build. Use allowProduction: true to override."
+          );
+          isActive = false;
+          return;
+        }
+
+        // Store project root
+        projectRoot = config.root.pathname;
+
+        // Capture Astro's trailingSlash setting for preview URLs
+        astroTrailingSlash = config.trailingSlash ?? "ignore";
+
+        // Load Writenex configuration
+        const { config: loadedConfig, warnings } =
+          await loadConfig(projectRoot);
+        resolvedConfig = loadedConfig;
+
+        // Log any configuration warnings
+        for (const warning of warnings) {
+          logger.warn(warning);
+        }
+      },
+
+      /**
+       * Server setup hook
+       *
+       * This hook runs when the Astro dev server starts.
+       * We use it to:
+       * 1. Inject middleware for API routes
+       * 2. Serve the editor UI
+       * 3. Start file watcher for cache invalidation
+       */
+      "astro:server:setup": ({ server }) => {
+        // Skip if disabled (production guard triggered)
+        if (!isActive || !resolvedConfig) {
+          return;
+        }
+
+        // Create and register the middleware
+        const middleware = createMiddleware({
+          basePath,
+          projectRoot,
+          config: resolvedConfig,
+          trailingSlash: astroTrailingSlash,
+        });
+
+        server.middlewares.use(middleware);
+
+        // Setup cache with file watcher integration
+        const cache = getCache({ hasWatcher: true });
+
+        // Start file watcher for cache invalidation
+        watcher = new ContentWatcher(projectRoot, "src/content", {
+          onChange: (event) => {
+            cache.handleFileChange(event.type, event.collection);
+          },
+        });
+
+        watcher.start();
+      },
+
+      /**
+       * Server start hook
+       *
+       * This hook runs after the dev server has started and is listening.
+       * We use it to log the full editor URL with the actual server address.
+       */
+      "astro:server:start": ({ address, logger }) => {
+        if (!isActive || hasLoggedEditorUrl) {
+          return;
+        }
+
+        // Build the full URL from the server address
+        // Normalize loopback addresses to "localhost" for better readability
+        const protocol = "http";
+        const rawHost = address.address;
+        const isLoopback =
+          rawHost === "" ||
+          rawHost === "::" ||
+          rawHost === "127.0.0.1" ||
+          rawHost === "::1";
+        const host = isLoopback ? "localhost" : rawHost;
+        const port = address.port;
+        const editorUrl = `${protocol}://${host}:${port}${basePath}`;
+
+        logger.info(`Writenex editor running at: ${editorUrl}`);
+        hasLoggedEditorUrl = true;
+      },
+
+      /**
+       * Server done hook
+       *
+       * This hook runs when the server is shutting down.
+       * We use it to clean up the file watcher.
+       */
+      "astro:server:done": async () => {
+        if (watcher) {
+          await watcher.stop();
+          watcher = null;
+        }
+      },
+
+      /**
+       * Build done hook
+       *
+       * This hook runs after the build completes.
+       * Currently just logs a warning if production mode is enabled.
+       */
+      "astro:build:done": ({ logger }) => {
+        if (allowProduction) {
+          logger.warn(
+            "Production mode enabled. Ensure your deployment is secured."
+          );
+        }
+      },
+    },
+  };
+}

package/src/server/assets.ts

@@ -0,0 +1,254 @@
+/**
+ * @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
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, extname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { MiddlewareContext } from "./middleware";
+
+/**
+ * Get the package root directory
+ *
+ * This function determines the package root based on where the code is running from.
+ * When installed from npm, the structure is:
+ *   node_modules/@writenex/astro/dist/index.js
+ *
+ * We need to find the package root to locate dist/client/ assets.
+ */
+function getPackageRoot(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  const currentDir = fileURLToPath(new URL(".", import.meta.url));
+
+  // When bundled, import.meta.url points to the dist/index.js file
+  // We need to go up one level to get to package root
+  if (currentFile.endsWith("dist/index.js") || currentDir.endsWith("dist/")) {
+    return join(currentDir, "..");
+  }
+
+  // When running from source (development), we're in src/server/
+  // Go up 2 levels to get to package root
+  if (currentDir.includes("/src/")) {
+    return join(currentDir, "..", "..");
+  }
+
+  // Fallback: assume we're in dist
+  return join(currentDir, "..");
+}
+
+const PACKAGE_ROOT = getPackageRoot();
+
+/**
+ * MIME types for static assets
+ */
+const MIME_TYPES: Record<string, string> = {
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+};
+
+/**
+ * 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
+ */
+export async function serveEditorHtml(
+  _req: IncomingMessage,
+  res: ServerResponse,
+  context: MiddlewareContext
+): Promise<void> {
+  const { basePath } = context;
+
+  const html = generateEditorHtml(basePath);
+
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "text/html; charset=utf-8");
+  res.setHeader("Cache-Control", "no-cache");
+  res.end(html);
+}
+
+/**
+ * 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
+ */
+export async function serveAsset(
+  _req: IncomingMessage,
+  res: ServerResponse,
+  assetPath: string,
+  _context: MiddlewareContext
+): Promise<void> {
+  // Determine asset location
+  // Assets are always in dist/client (pre-bundled by tsup)
+  const distPath = join(PACKAGE_ROOT, "dist", "client", assetPath);
+
+  if (!existsSync(distPath)) {
+    console.error("[writenex] Asset not found:", distPath);
+    res.statusCode = 404;
+    res.setHeader("Content-Type", "text/plain");
+    res.end(`Asset not found: ${assetPath}`);
+    return;
+  }
+
+  const filePath = distPath;
+
+  try {
+    const content = await readFile(filePath);
+    const ext = extname(assetPath).toLowerCase();
+    const mimeType = MIME_TYPES[ext] ?? "application/octet-stream";
+
+    res.statusCode = 200;
+    res.setHeader("Content-Type", mimeType);
+    res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+    res.end(content);
+  } catch (error) {
+    console.error(`[writenex] Failed to serve asset: ${assetPath}`, error);
+    res.statusCode = 500;
+    res.setHeader("Content-Type", "text/plain");
+    res.end("Failed to read asset");
+  }
+}
+
+/**
+ * Generate the editor HTML shell
+ *
+ * This creates the HTML page that bootstraps the React editor application.
+ * It includes:
+ * - Meta tags for viewport and charset
+ * - CSS for the editor
+ * - React mount point
+ * - JavaScript bundle
+ *
+ * @param basePath - Base path for the editor
+ * @returns HTML string
+ */
+function generateEditorHtml(basePath: string): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="robots" content="noindex, nofollow">
+  <title>Writenex - Content Editor</title>
+  
+  <!-- Editor styles -->
+  <link rel="stylesheet" href="${basePath}/assets/index.css">
+  <link rel="stylesheet" href="${basePath}/assets/styles.css">
+  
+  <style>
+    /* Critical CSS for initial load */
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    
+    html, body, #root {
+      height: 100%;
+      width: 100%;
+    }
+    
+    body {
+      font-family: 'Plus Jakarta Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+      background-color: #0a0a0a;
+      color: #fafafa;
+    }
+    
+    /* Loading state */
+    .writenex-loading {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      height: 100%;
+      gap: 1rem;
+    }
+    
+    .writenex-loading-spinner {
+      width: 40px;
+      height: 40px;
+      border: 3px solid rgba(59, 130, 246, 0.2);
+      border-top-color: #3b82f6;
+      border-radius: 50%;
+      animation: spin 1s linear infinite;
+    }
+    
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+    
+    .writenex-loading-text {
+      color: #71717a;
+      font-size: 0.875rem;
+    }
+  </style>
+</head>
+<body>
+  <div id="root">
+    <!-- Loading state shown while React loads -->
+    <div class="writenex-loading">
+      <div class="writenex-loading-spinner"></div>
+      <div class="writenex-loading-text">Loading Writenex Editor...</div>
+    </div>
+  </div>
+  
+  <!-- Configuration for the client app -->
+  <script>
+    window.__WRITENEX_CONFIG__ = {
+      basePath: "${basePath}",
+      apiBase: "${basePath}/api",
+    };
+  </script>
+  
+  <!-- Editor application -->
+  <script type="module" src="${basePath}/assets/index.js"></script>
+</body>
+</html>`;
+}
+
+/**
+ * Get the path to bundled client assets
+ *
+ * @returns Path to the client dist directory
+ */
+export function getClientDistPath(): string {
+  return join(PACKAGE_ROOT, "dist", "client");
+}
+
+/**
+ * Check if client assets are bundled
+ *
+ * @returns True if bundled assets exist
+ */
+export function hasClientBundle(): boolean {
+  const indexPath = join(getClientDistPath(), "index.js");
+  return existsSync(indexPath);
+}