@gravito/monolith 3.0.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/monolith",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Enterprise monolith framework for Gravito Galaxy",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -15,9 +15,12 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",
-    "test": "bun test",
-    "test:coverage": "bun test --coverage --coverage-threshold=80",
-    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck"
+    "test": "bun test --timeout=10000",
+    "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
+    "test:unit": "bun test tests/ --timeout=10000",
+    "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'"
   },
   "keywords": [
     "gravito",
@@ -28,9 +31,10 @@
   "author": "Carl Lee <carllee0520@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "marked": "^11.1.1",
+    "@gravito/mass": "workspace:*",
+    "@octokit/rest": "^22.0.1",
     "gray-matter": "^4.0.3",
-    "@gravito/mass": "workspace:*"
+    "marked": "^11.1.1"
   },
   "peerDependencies": {
     "@gravito/core": "workspace:*"
@@ -51,4 +55,4 @@
     "url": "git+https://github.com/gravito-framework/gravito.git",
     "directory": "packages/monolith"
   }
-}
+}

package/scripts/check-coverage.ts

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const lcovPath = process.argv[2] ?? 'coverage/lcov.info'
+const threshold = Number.parseFloat(process.env.COVERAGE_THRESHOLD ?? '80')
+
+const root = resolve(process.cwd())
+const srcRoot = `${resolve(root, 'src')}/`
+
+// 檢查 lcov.info 是否存在
+if (!existsSync(lcovPath)) {
+  console.error(`Coverage file not found: ${lcovPath}`)
+  process.exit(1)
+}
+
+let content: string
+try {
+  content = readFileSync(lcovPath, 'utf-8')
+} catch (error) {
+  console.error(`Failed to read coverage file: ${error}`)
+  process.exit(1)
+}
+
+const lines = content.split('\n')
+
+let currentFile: string | null = null
+let total = 0
+let hit = 0
+
+for (const line of lines) {
+  if (line.startsWith('SF:')) {
+    const filePath = line.slice(3).trim()
+    const abs = resolve(root, filePath)
+    currentFile = abs.startsWith(srcRoot) ? abs : null
+    continue
+  }
+
+  if (!currentFile) {
+    continue
+  }
+
+  if (line.startsWith('DA:')) {
+    const parts = line.slice(3).split(',')
+    if (parts.length >= 2) {
+      total += 1
+      const count = Number.parseInt(parts[1] ?? '0', 10)
+      if (count > 0) {
+        hit += 1
+      }
+    }
+  }
+}
+
+const percent = total === 0 ? 0 : (hit / total) * 100
+const rounded = Math.round(percent * 100) / 100
+
+if (rounded < threshold) {
+  console.error(
+    `monolith coverage ${rounded}% is below threshold ${threshold}%. Covered lines: ${hit}/${total}.`
+  )
+  process.exit(1)
+}
+
+console.log(`monolith coverage ${rounded}% (${hit}/${total}) meets threshold ${threshold}%.`)

package/src/ContentManager.ts

@@ -1,8 +1,12 @@
-import { readdir, readFile, stat } from 'node:fs/promises'
 import { join, parse } from 'node:path'
 import matter from 'gray-matter'
 import { marked } from 'marked'
+import type { ContentDriver } from './driver/ContentDriver'
 
+/**
+ * Represents a single content item (file).
+ * @public
+ */
 export interface ContentItem {
   slug: string
   body: string // The HTML content
@@ -12,14 +16,24 @@ export interface ContentItem {
   raw: string // The raw markdown
 }
 
+/**
+ * Configuration for a content collection.
+ * @public
+ */
 export interface CollectionConfig {
   path: string // e.g., 'resources/content/docs'
 }
 
+/**
+ * Manages fetching, parsing, and caching of filesystem-based content.
+ * @public
+ */
 export class ContentManager {
   private collections = new Map<string, CollectionConfig>()
   // Simple memory cache: collection:locale:slug -> ContentItem
   private cache = new Map<string, ContentItem>()
+  // In-memory search index: term -> Set<cacheKey>
+  private searchIndex = new Map<string, Set<string>>()
   private renderer = (() => {
     const renderer = new marked.Renderer()
     renderer.html = (html: string) => this.escapeHtml(html)
@@ -34,12 +48,41 @@ export class ContentManager {
     return renderer
   })()
 
+  /**
+   * Clear all cached content.
+   * Useful for hot reload during development.
+   */
+  clearCache(): void {
+    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: string, slug: string, locale = 'en'): void {
+    const safeSlug = this.sanitizeSegment(slug)
+    const safeLocale = this.sanitizeSegment(locale)
+
+    if (safeSlug && safeLocale) {
+      const cacheKey = `${collection}:${safeLocale}:${safeSlug}`
+      this.cache.delete(cacheKey)
+    }
+  }
+
+  getCollectionConfig(name: string): CollectionConfig | undefined {
+    return this.collections.get(name)
+  }
+
   /**
    * Create a new ContentManager instance.
    *
-   * @param rootDir - The root directory of the application.
+   * @param driver - The content driver to use.
    */
-  constructor(private rootDir: string) {}
+  constructor(private readonly driver: ContentDriver) {}
 
   /**
    * Register a new content collection.
@@ -73,23 +116,22 @@ export class ContentManager {
     }
 
     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
     }
 
     // Determine path strategy
-    // Strategy: {root}/{path}/{locale}/{slug}.md
-    const filePath = join(this.rootDir, config.path, safeLocale, `${safeSlug}.md`)
+    // Strategy: {path}/{locale}/{slug}.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 })
@@ -103,6 +145,7 @@ export class ContentManager {
       }
 
       this.cache.set(cacheKey, item)
+      this.buildSearchIndex(cacheKey, item)
       return item
     } catch (e) {
       console.error(`[Orbit-Content] Error reading file: ${filePath}`, e)
@@ -130,10 +173,10 @@ export class ContentManager {
       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: ContentItem[] = []
 
       for (const file of files) {
@@ -154,6 +197,65 @@ export class ContentManager {
     }
   }
 
+  /**
+   * 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[] {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean)
+    if (terms.length === 0) {
+      return []
+    }
+
+    const matches = new Set<string>()
+
+    for (const term of terms) {
+      const keys = this.searchIndex.get(term)
+      if (keys) {
+        for (const key of keys) {
+          matches.add(key)
+        }
+      }
+    }
+
+    const results: ContentItem[] = []
+    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
+  }
+
+  private buildSearchIndex(cacheKey: string, item: ContentItem): void {
+    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, new Set())
+      }
+      this.searchIndex.get(term)?.add(cacheKey)
+    }
+  }
+
   private sanitizeSegment(value: string): string | null {
     if (!value) {
       return null

package/src/ContentWatcher.ts

@@ -0,0 +1,123 @@
+import { type FSWatcher, readdirSync, watch } from 'node:fs'
+import { join } from 'node:path'
+import type { ContentManager } from './ContentManager'
+
+interface WatcherOptions {
+  debounceMs?: number
+}
+
+export class ContentWatcher {
+  private watchers: FSWatcher[] = []
+  private debounceTimers = new Map<string, ReturnType<typeof setTimeout>>()
+
+  constructor(
+    private contentManager: ContentManager,
+    private rootDir: string,
+    private options: WatcherOptions = {}
+  ) {}
+
+  watch(collectionName: string): void {
+    const config = this.contentManager.getCollectionConfig(collectionName)
+    if (!config) {
+      console.warn(`[ContentWatcher] Collection '${collectionName}' not found`)
+      return
+    }
+
+    const watchPath = join(this.rootDir, config.path)
+
+    // Watch the collection directory (recursive if supported)
+    this.addWatcher(watchPath, collectionName)
+
+    // On some platforms (like Linux), recursive watch is not supported.
+    // We manually watch the immediate subdirectories (locales).
+    try {
+      const entries = readdirSync(watchPath, { withFileTypes: true })
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          this.addWatcher(join(watchPath, entry.name), collectionName, entry.name)
+        }
+      }
+    } catch (_e) {
+      // Directory might not exist yet
+    }
+  }
+
+  private addWatcher(watchPath: string, collection: string, localePrefix?: string) {
+    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) {
+      // If recursive fails, try without it
+      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)
+      }
+    }
+  }
+
+  private handleFileChange(collection: string, filename: string, localePrefix?: string) {
+    // Handle both / and \ as separators
+    const parts = filename.split(/[/\\]/)
+
+    let locale: string
+    let file: string
+
+    if (parts.length >= 2) {
+      // If filename is "en/test.md"
+      locale = parts[parts.length - 2]
+      file = parts[parts.length - 1]
+    } else if (localePrefix) {
+      // If we are watching a locale directory directly
+      locale = localePrefix
+      file = parts[0]
+    } else {
+      // No locale found, and no prefix. Monolith expects collection/locale/slug.md
+      return
+    }
+
+    if (!file.endsWith('.md')) {
+      return
+    }
+
+    const slug = file.replace(/\.md$/, '')
+
+    this.contentManager.invalidate(collection, slug, locale)
+  }
+
+  close(): void {
+    for (const watcher of this.watchers) {
+      watcher.close()
+    }
+    this.watchers = []
+
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer)
+    }
+    this.debounceTimers.clear()
+  }
+}

package/src/Controller.ts

@@ -1,6 +1,14 @@
 import type { GravitoContext } from '@gravito/core'
 import { Sanitizer } from './Sanitizer.js'
 
+/**
+ * Base class for all Monolith Controllers.
+ *
+ * Provides basic functionality for calling actions and sanitizing data.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export abstract class BaseController {
   protected sanitizer = new Sanitizer()
 
@@ -14,6 +22,15 @@ export abstract class BaseController {
   }
 }
 
+/**
+ * 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
+ */
 export abstract class Controller {
   protected context!: GravitoContext
 

package/src/FormRequest.ts

@@ -2,6 +2,15 @@ import type { GravitoContext, GravitoNext } from '@gravito/core'
 import { type TSchema, validate } from '@gravito/mass'
 import { Sanitizer } from './Sanitizer.js'
 
+/**
+ * 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
+ */
 export abstract class FormRequest {
   protected context!: GravitoContext
 
@@ -65,7 +74,9 @@ export abstract class FormRequest {
           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')
           }
 

package/src/Router.ts

@@ -1,5 +1,9 @@
 import type { Hono } from 'hono'
 
+/**
+ * Utility for registering resourceful routes.
+ * @public
+ */
 export class RouterHelper {
   /**
    * Register standard resource routes for a controller.

package/src/driver/ContentDriver.ts

@@ -0,0 +1,5 @@
+export interface ContentDriver {
+  read(path: string): Promise<string>
+  exists(path: string): Promise<boolean>
+  list(dir: string): Promise<string[]>
+}

package/src/driver/GitHubDriver.ts

@@ -0,0 +1,80 @@
+import { Octokit } from '@octokit/rest'
+import type { ContentDriver } from './ContentDriver'
+
+export interface GitHubDriverOptions {
+  owner: string
+  repo: string
+  ref?: string
+  auth?: string
+}
+
+export class GitHubDriver implements ContentDriver {
+  private octokit: Octokit
+  private owner: string
+  private repo: string
+  private ref?: string
+
+  constructor(options: GitHubDriverOptions) {
+    this.octokit = new Octokit({ auth: options.auth })
+    this.owner = options.owner
+    this.repo = options.repo
+    this.ref = options.ref
+  }
+
+  async read(path: string): Promise<string> {
+    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: any) {
+      if (e.status === 404) {
+        throw new Error(`File not found: ${path}`)
+      }
+      throw e
+    }
+  }
+
+  async exists(path: string): Promise<boolean> {
+    try {
+      // Use HEAD request if possible, or just lightweight get
+      // getContents with defaults gets JSON metadata
+      await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        ref: this.ref,
+      })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async list(dir: string): Promise<string[]> {
+    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 []
+    }
+  }
+}

package/src/driver/LocalDriver.ts

@@ -0,0 +1,30 @@
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { ContentDriver } from './ContentDriver'
+
+export class LocalDriver implements ContentDriver {
+  constructor(private rootDir: string) {}
+
+  async read(path: string): Promise<string> {
+    const fullPath = join(this.rootDir, path)
+    return readFile(fullPath, 'utf-8')
+  }
+
+  async exists(path: string): Promise<boolean> {
+    try {
+      await stat(join(this.rootDir, path))
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async list(dir: string): Promise<string[]> {
+    try {
+      const fullPath = join(this.rootDir, dir)
+      return await readdir(fullPath)
+    } catch {
+      return []
+    }
+  }
+}

package/src/index.ts

@@ -1,5 +1,8 @@
 import type { GravitoOrbit, PlanetCore } from '@gravito/core'
 import { type CollectionConfig, ContentManager } from './ContentManager'
+import { ContentWatcher } from './ContentWatcher'
+import type { ContentDriver } from './driver/ContentDriver'
+import { LocalDriver } from './driver/LocalDriver'
 
 declare module '@gravito/core' {
   interface Variables {
@@ -7,17 +10,38 @@ declare module '@gravito/core' {
   }
 }
 
+/**
+ * Configuration for Orbit Monolith (Content Engine).
+ * @public
+ */
 export interface ContentConfig {
   root?: string // Defaults to process.cwd()
+  driver?: ContentDriver
   collections?: Record<string, CollectionConfig>
 }
 
+/**
+ * Orbit Monolith Service.
+ * Provides flat-file CMS capabilities to Gravito applications.
+ * @public
+ */
 export class OrbitMonolith implements GravitoOrbit {
   constructor(private config: ContentConfig = {}) {}
 
   install(core: PlanetCore): void {
     const root = this.config.root || process.cwd()
-    const manager = new ContentManager(root)
+    let driver: ContentDriver
+    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)
 
     // Register Collections from Config
     if (this.config.collections) {
@@ -35,6 +59,16 @@ export class OrbitMonolith implements GravitoOrbit {
       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 🔥')
+    }
+
     core.logger.info('Orbit Monolith installed ⬛️')
   }
 }
@@ -42,5 +76,8 @@ export class OrbitMonolith implements GravitoOrbit {
 export { Schema } from '@gravito/mass'
 export * from './ContentManager'
 export * from './Controller'
+export * from './driver/ContentDriver'
+export * from './driver/GitHubDriver'
+export * from './driver/LocalDriver'
 export * from './FormRequest'
 export { RouterHelper as Route } from './Router'