@gravito/monolith 3.0.0 → 3.2.0

package/dist/index.d.ts

@@ -4,6 +4,16 @@ import { TSchema } from '@gravito/mass';
 export { Schema } from '@gravito/mass';
 import { Hono } from 'hono';
 
+interface ContentDriver {
+    read(path: string): Promise<string>;
+    exists(path: string): Promise<boolean>;
+    list(dir: string): Promise<string[]>;
+}
+
+/**
+ * Represents a single content item (file).
+ * @public
+ */
 interface ContentItem {
     slug: string;
     body: string;
@@ -11,20 +21,42 @@ interface ContentItem {
     meta: Record<string, any>;
     raw: string;
 }
+/**
+ * Configuration for a content collection.
+ * @public
+ */
 interface CollectionConfig {
     path: string;
 }
+/**
+ * Manages fetching, parsing, and caching of filesystem-based content.
+ * @public
+ */
 declare class ContentManager {
-    private rootDir;
+    private readonly driver;
     private collections;
     private cache;
+    private searchIndex;
     private renderer;
+    /**
+     * Clear all cached content.
+     * Useful for hot reload during development.
+     */
+    clearCache(): void;
+    /**
+     * Invalidate a specific content item.
+     * @param collection - The collection name.
+     * @param slug - The file slug.
+     * @param locale - The locale. Defaults to 'en'.
+     */
+    invalidate(collection: string, slug: string, locale?: string): void;
+    getCollectionConfig(name: string): CollectionConfig | undefined;
     /**
      * Create a new ContentManager instance.
      *
-     * @param rootDir - The root directory of the application.
+     * @param driver - The content driver to use.
      */
-    constructor(rootDir: string);
+    constructor(driver: ContentDriver);
     /**
      * Register a new content collection.
      *
@@ -52,6 +84,18 @@ declare class ContentManager {
      * @throws {Error} If the collection is not defined.
      */
     list(collectionName: string, locale?: string): Promise<ContentItem[]>;
+    /**
+     * Search for content items across collections and locales.
+     *
+     * @param query - The search query.
+     * @param options - Optional filters for collection and locale.
+     * @returns An array of matching ContentItems.
+     */
+    search(query: string, options?: {
+        collection?: string;
+        locale?: string;
+    }): ContentItem[];
+    private buildSearchIndex;
     private sanitizeSegment;
     private escapeHtml;
     private isSafeUrl;
@@ -67,10 +111,27 @@ declare class Sanitizer {
     static clean(data: any): any;
 }
 
+/**
+ * Base class for all Monolith Controllers.
+ *
+ * Provides basic functionality for calling actions and sanitizing data.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare abstract class BaseController {
     protected sanitizer: Sanitizer;
     call(ctx: GravitoContext, method: string): Promise<Response>;
 }
+/**
+ * Controller class with request context awareness and helper methods.
+ *
+ * This class provides a more feature-rich base for controllers that
+ * need direct access to the request context and common response helpers.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare abstract class Controller {
     protected context: GravitoContext;
     /**
@@ -107,6 +168,40 @@ declare abstract class Controller {
     static call(method: string): any;
 }
 
+interface GitHubDriverOptions {
+    owner: string;
+    repo: string;
+    ref?: string;
+    auth?: string;
+}
+declare class GitHubDriver implements ContentDriver {
+    private octokit;
+    private owner;
+    private repo;
+    private ref?;
+    constructor(options: GitHubDriverOptions);
+    read(path: string): Promise<string>;
+    exists(path: string): Promise<boolean>;
+    list(dir: string): Promise<string[]>;
+}
+
+declare class LocalDriver implements ContentDriver {
+    private rootDir;
+    constructor(rootDir: string);
+    read(path: string): Promise<string>;
+    exists(path: string): Promise<boolean>;
+    list(dir: string): Promise<string[]>;
+}
+
+/**
+ * Base class for Monolith Form Requests.
+ *
+ * Provides a structured way to handle request validation and authorization
+ * for the Monolith architecture.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare abstract class FormRequest {
     protected context: GravitoContext;
     /**
@@ -135,6 +230,10 @@ declare abstract class FormRequest {
     static middleware(): any;
 }
 
+/**
+ * Utility for registering resourceful routes.
+ * @public
+ */
 declare class RouterHelper {
     /**
      * Register standard resource routes for a controller.
@@ -155,14 +254,24 @@ declare module '@gravito/core' {
         content: ContentManager;
     }
 }
+/**
+ * Configuration for Orbit Monolith (Content Engine).
+ * @public
+ */
 interface ContentConfig {
     root?: string;
+    driver?: ContentDriver;
     collections?: Record<string, CollectionConfig>;
 }
+/**
+ * Orbit Monolith Service.
+ * Provides flat-file CMS capabilities to Gravito applications.
+ * @public
+ */
 declare class OrbitMonolith implements GravitoOrbit {
     private config;
     constructor(config?: ContentConfig);
     install(core: PlanetCore): void;
 }
 
-export { BaseController, type CollectionConfig, type ContentConfig, type ContentItem, ContentManager, Controller, FormRequest, OrbitMonolith, RouterHelper as Route };
+export { BaseController, type CollectionConfig, type ContentConfig, type ContentDriver, type ContentItem, ContentManager, Controller, FormRequest, GitHubDriver, type GitHubDriverOptions, LocalDriver, OrbitMonolith, RouterHelper as Route };

package/dist/index.js

@@ -1,5 +1,4 @@
 // src/ContentManager.ts
-import { readdir, readFile, stat } from "fs/promises";
 import { join, parse } from "path";
 import matter from "gray-matter";
 import { marked } from "marked";
@@ -7,14 +6,16 @@ var ContentManager = class {
   /**
    * Create a new ContentManager instance.
    *
-   * @param rootDir - The root directory of the application.
+   * @param driver - The content driver to use.
    */
-  constructor(rootDir) {
-    this.rootDir = rootDir;
+  constructor(driver) {
+    this.driver = driver;
   }
   collections = /* @__PURE__ */ new Map();
   // Simple memory cache: collection:locale:slug -> ContentItem
   cache = /* @__PURE__ */ new Map();
+  // In-memory search index: term -> Set<cacheKey>
+  searchIndex = /* @__PURE__ */ new Map();
   renderer = (() => {
     const renderer = new marked.Renderer();
     renderer.html = (html) => this.escapeHtml(html);
@@ -28,6 +29,31 @@ var ContentManager = class {
     };
     return renderer;
   })();
+  /**
+   * Clear all cached content.
+   * Useful for hot reload during development.
+   */
+  clearCache() {
+    this.cache.clear();
+    this.searchIndex.clear();
+  }
+  /**
+   * Invalidate a specific content item.
+   * @param collection - The collection name.
+   * @param slug - The file slug.
+   * @param locale - The locale. Defaults to 'en'.
+   */
+  invalidate(collection, slug, locale = "en") {
+    const safeSlug = this.sanitizeSegment(slug);
+    const safeLocale = this.sanitizeSegment(locale);
+    if (safeSlug && safeLocale) {
+      const cacheKey = `${collection}:${safeLocale}:${safeSlug}`;
+      this.cache.delete(cacheKey);
+    }
+  }
+  getCollectionConfig(name) {
+    return this.collections.get(name);
+  }
   /**
    * Register a new content collection.
    *
@@ -57,16 +83,17 @@ var ContentManager = class {
       return null;
     }
     const cacheKey = `${collectionName}:${locale}:${slug}`;
-    if (this.cache.has(cacheKey)) {
-      return this.cache.get(cacheKey);
+    const cachedItem = this.cache.get(cacheKey);
+    if (cachedItem) {
+      return cachedItem;
     }
-    const filePath = join(this.rootDir, config.path, safeLocale, `${safeSlug}.md`);
+    const filePath = join(config.path, safeLocale, `${safeSlug}.md`);
     try {
-      const exists = await stat(filePath).then(() => true).catch(() => false);
+      const exists = await this.driver.exists(filePath);
       if (!exists) {
         return null;
       }
-      const fileContent = await readFile(filePath, "utf-8");
+      const fileContent = await this.driver.read(filePath);
       const { data, content, excerpt } = matter(fileContent);
       const html = await marked.parse(content, { renderer: this.renderer });
       const item = {
@@ -77,6 +104,7 @@ var ContentManager = class {
         excerpt
       };
       this.cache.set(cacheKey, item);
+      this.buildSearchIndex(cacheKey, item);
       return item;
     } catch (e) {
       console.error(`[Orbit-Content] Error reading file: ${filePath}`, e);
@@ -101,9 +129,9 @@ var ContentManager = class {
     if (!safeLocale) {
       return [];
     }
-    const dirPath = join(this.rootDir, config.path, safeLocale);
+    const dirPath = join(config.path, safeLocale);
     try {
-      const files = await readdir(dirPath);
+      const files = await this.driver.list(dirPath);
       const items = [];
       for (const file of files) {
         if (!file.endsWith(".md")) {
@@ -120,6 +148,54 @@ var ContentManager = class {
       return [];
     }
   }
+  /**
+   * Search for content items across collections and locales.
+   *
+   * @param query - The search query.
+   * @param options - Optional filters for collection and locale.
+   * @returns An array of matching ContentItems.
+   */
+  search(query, options = {}) {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (terms.length === 0) {
+      return [];
+    }
+    const matches = /* @__PURE__ */ new Set();
+    for (const term of terms) {
+      const keys = this.searchIndex.get(term);
+      if (keys) {
+        for (const key of keys) {
+          matches.add(key);
+        }
+      }
+    }
+    const results = [];
+    for (const key of matches) {
+      const item = this.cache.get(key);
+      if (!item) {
+        continue;
+      }
+      const [collection, locale] = key.split(":");
+      if (options.collection && options.collection !== collection) {
+        continue;
+      }
+      if (options.locale && options.locale !== locale) {
+        continue;
+      }
+      results.push(item);
+    }
+    return results;
+  }
+  buildSearchIndex(cacheKey, item) {
+    const text = `${item.slug} ${item.meta.title || ""} ${item.raw} ${item.excerpt || ""}`.toLowerCase();
+    const terms = text.split(/[^\w\d]+/).filter((t) => t.length > 2);
+    for (const term of terms) {
+      if (!this.searchIndex.has(term)) {
+        this.searchIndex.set(term, /* @__PURE__ */ new Set());
+      }
+      this.searchIndex.get(term)?.add(cacheKey);
+    }
+  }
   sanitizeSegment(value) {
     if (!value) {
       return null;
@@ -156,6 +232,128 @@ var ContentManager = class {
   }
 };
 
+// src/ContentWatcher.ts
+import { readdirSync, watch } from "fs";
+import { join as join2 } from "path";
+var ContentWatcher = class {
+  constructor(contentManager, rootDir, options = {}) {
+    this.contentManager = contentManager;
+    this.rootDir = rootDir;
+    this.options = options;
+  }
+  watchers = [];
+  debounceTimers = /* @__PURE__ */ new Map();
+  watch(collectionName) {
+    const config = this.contentManager.getCollectionConfig(collectionName);
+    if (!config) {
+      console.warn(`[ContentWatcher] Collection '${collectionName}' not found`);
+      return;
+    }
+    const watchPath = join2(this.rootDir, config.path);
+    this.addWatcher(watchPath, collectionName);
+    try {
+      const entries = readdirSync(watchPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          this.addWatcher(join2(watchPath, entry.name), collectionName, entry.name);
+        }
+      }
+    } catch (_e) {
+    }
+  }
+  addWatcher(watchPath, collection, localePrefix) {
+    try {
+      const watcher = watch(watchPath, { recursive: true }, (_eventType, filename) => {
+        if (!filename) {
+          return;
+        }
+        const key = `${collection}:${localePrefix || ""}:${filename}`;
+        if (this.debounceTimers.has(key)) {
+          clearTimeout(this.debounceTimers.get(key));
+        }
+        this.debounceTimers.set(
+          key,
+          setTimeout(() => {
+            this.handleFileChange(collection, filename.toString(), localePrefix);
+            this.debounceTimers.delete(key);
+          }, this.options.debounceMs ?? 100)
+        );
+      });
+      this.watchers.push(watcher);
+    } catch (_e) {
+      try {
+        const watcher = watch(watchPath, { recursive: false }, (_eventType, filename) => {
+          if (!filename) {
+            return;
+          }
+          this.handleFileChange(collection, filename.toString(), localePrefix);
+        });
+        this.watchers.push(watcher);
+      } catch (err) {
+        console.error(`[ContentWatcher] Failed to watch ${watchPath}:`, err);
+      }
+    }
+  }
+  handleFileChange(collection, filename, localePrefix) {
+    const parts = filename.split(/[/\\]/);
+    let locale;
+    let file;
+    if (parts.length >= 2) {
+      locale = parts[parts.length - 2];
+      file = parts[parts.length - 1];
+    } else if (localePrefix) {
+      locale = localePrefix;
+      file = parts[0];
+    } else {
+      return;
+    }
+    if (!file.endsWith(".md")) {
+      return;
+    }
+    const slug = file.replace(/\.md$/, "");
+    this.contentManager.invalidate(collection, slug, locale);
+  }
+  close() {
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+    this.watchers = [];
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+  }
+};
+
+// src/driver/LocalDriver.ts
+import { readdir, readFile, stat } from "fs/promises";
+import { join as join3 } from "path";
+var LocalDriver = class {
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  async read(path) {
+    const fullPath = join3(this.rootDir, path);
+    return readFile(fullPath, "utf-8");
+  }
+  async exists(path) {
+    try {
+      await stat(join3(this.rootDir, path));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async list(dir) {
+    try {
+      const fullPath = join3(this.rootDir, dir);
+      return await readdir(fullPath);
+    } catch {
+      return [];
+    }
+  }
+};
+
 // src/index.ts
 import { Schema } from "@gravito/mass";
 
@@ -255,6 +453,69 @@ var Controller = class {
   }
 };
 
+// src/driver/GitHubDriver.ts
+import { Octokit } from "@octokit/rest";
+var GitHubDriver = class {
+  octokit;
+  owner;
+  repo;
+  ref;
+  constructor(options) {
+    this.octokit = new Octokit({ auth: options.auth });
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.ref = options.ref;
+  }
+  async read(path) {
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        ref: this.ref
+      });
+      if (Array.isArray(data) || !("content" in data)) {
+        throw new Error(`Path is not a file: ${path}`);
+      }
+      return Buffer.from(data.content, "base64").toString("utf-8");
+    } catch (e) {
+      if (e.status === 404) {
+        throw new Error(`File not found: ${path}`);
+      }
+      throw e;
+    }
+  }
+  async exists(path) {
+    try {
+      await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        ref: this.ref
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async list(dir) {
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: dir,
+        ref: this.ref
+      });
+      if (!Array.isArray(data)) {
+        return [];
+      }
+      return data.map((item) => item.name);
+    } catch {
+      return [];
+    }
+  }
+};
+
 // src/FormRequest.ts
 import { validate } from "@gravito/mass";
 var FormRequest = class {
@@ -303,7 +564,9 @@ var FormRequest = class {
           for (const issue of issues) {
             const path = Array.isArray(issue.path) ? issue.path.join(".") : issue.path || "root";
             const key = path.replace(/^\//, "").replace(/\//g, ".");
-            if (!errors[key]) errors[key] = [];
+            if (!errors[key]) {
+              errors[key] = [];
+            }
             errors[key].push(issue.message || "Validation failed");
           }
           return ctx.json(
@@ -360,7 +623,16 @@ var OrbitMonolith = class {
   }
   install(core) {
     const root = this.config.root || process.cwd();
-    const manager = new ContentManager(root);
+    let driver;
+    let isLocal = false;
+    if (this.config.driver) {
+      driver = this.config.driver;
+      isLocal = driver instanceof LocalDriver;
+    } else {
+      driver = new LocalDriver(root);
+      isLocal = true;
+    }
+    const manager = new ContentManager(driver);
     if (this.config.collections) {
       for (const [name, config] of Object.entries(this.config.collections)) {
         manager.defineCollection(name, config);
@@ -370,6 +642,15 @@ var OrbitMonolith = class {
       c.set("content", manager);
       return await next();
     });
+    if (process.env.NODE_ENV === "development" && isLocal) {
+      const watcher = new ContentWatcher(manager, root);
+      if (this.config.collections) {
+        for (const name of Object.keys(this.config.collections)) {
+          watcher.watch(name);
+        }
+      }
+      core.logger.info("Orbit Monolith Hot Reload Active \u{1F525}");
+    }
     core.logger.info("Orbit Monolith installed \u2B1B\uFE0F");
   }
 };
@@ -378,6 +659,8 @@ export {
   ContentManager,
   Controller,
   FormRequest,
+  GitHubDriver,
+  LocalDriver,
   OrbitMonolith,
   RouterHelper as Route,
   Schema