@gravito/monolith 3.2.0 → 3.2.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @gravito/monolith
 
+## 3.2.1
+
+### Patch Changes
+
+- Convert all workspace:\* dependencies to version numbers for npm publishing
+
+  - Fixed 144 workspace:\* dependencies across 58 packages
+  - Ensures all packages work properly when installed from npm
+  - Resolves issues with bunx and npm installation of CLI tools
+  - All internal dependencies now use explicit version constraints
+
+- Updated dependencies
+  - @gravito/core@1.6.1
+  - @gravito/mass@3.0.2
+
 ## 3.1.0
 
 ### Minor Changes

package/README.md

@@ -53,10 +53,34 @@ bun add @gravito/monolith
 
 ## ✨ Features
 
--   **Markdown Support**: Full Markdown parsing via `marked`.
--   **Frontmatter**: Parses YAML frontmatter using `gray-matter`.
--   **Collections**: Organize content into collections (folders).
--   **Query API**: Fluent API to fetch by slug, list all, etc. `collection('posts').slug('...').fetch()`.
+- 🪐 **Galaxy-Ready Content API**: Native integration with PlanetCore to serve file-based content across all Satellites.
+- 📝 **Markdown-to-State**: Transform flat markdown files into rich, type-safe API responses with zero runtime DB overhead.
+- 📂 **Flexible Collections**: Organize the Galaxy's knowledge into intuitive collections and sub-collections.
+- ⚡ **Zero-Config Performance**: Built-in caching and frontmatter parsing for lightning-fast content retrieval.
+- 🏗️ **SSG Integration**: Works seamlessly with `@gravito/prism` for building blazing-fast static sites.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Monolith acts as the **Knowledge Core (Content Layer)**.
+
+- **Immutable Truth**: Provides a file-based "Single Source of Truth" for documentation, blogs, and marketing content, allowing developers to manage knowledge via Git.
+- **Micro-CMS Interface**: Enables Satellites to fetch static content through a unified Query API, decoupling presentation from raw data storage.
+- **Hybrid Bridge**: Works with `Atlas` to allow Satellites to combine static markdown knowledge with dynamic relational data in a single view.
+
+```mermaid
+graph LR
+    Git([Git Repo]) --> MD[Markdown Files]
+    MD --> Monolith{Monolith Core}
+    Monolith -->|Query| Sat[Satellite: Blog]
+    Sat -->|Render| User([User UI])
+```
+
+## 📚 Documentation
+
+Detailed guides and references for the Galaxy Architecture:
+
+- [🏗️ **Architecture Overview**](./README.md) — File-based CMS core.
+- [📝 **Knowledge Management**](./doc/KNOWLEDGE_MANAGEMENT.md) — **NEW**: Collections, frontmatter, and SSG integration.
 
 ## 📚 API
 

package/dist/index.cjs

@@ -44,8 +44,8 @@ module.exports = __toCommonJS(index_exports);
 
 // src/ContentManager.ts
 var import_node_path = require("path");
+var import_core = require("@gravito/core");
 var import_gray_matter = __toESM(require("gray-matter"), 1);
-var import_marked = require("marked");
 var ContentManager = class {
   /**
    * Create a new ContentManager instance.
@@ -60,19 +60,22 @@ var ContentManager = class {
   cache = /* @__PURE__ */ new Map();
   // In-memory search index: term -> Set<cacheKey>
   searchIndex = /* @__PURE__ */ new Map();
-  renderer = (() => {
-    const renderer = new import_marked.marked.Renderer();
-    renderer.html = (html) => this.escapeHtml(html);
-    renderer.link = (href, title, text) => {
-      if (!href || !this.isSafeUrl(href)) {
-        return text;
+  // Escape HTML helper
+  escapeHtml = (0, import_core.getEscapeHtml)();
+  // RuntimeMarkdownAdapter（自動選擇 Bun 原生或 marked fallback）
+  mdAdapter = (0, import_core.getMarkdownAdapter)();
+  // 完整的 HTML 渲染回調（含 XSS 防護覆寫）
+  renderCallbacks = (0, import_core.createHtmlRenderCallbacks)({
+    html: (rawHtml) => this.escapeHtml(rawHtml),
+    link: (content, opts) => {
+      if (!opts.href || !this.isSafeUrl(opts.href)) {
+        return content;
       }
-      const safeHref = this.escapeHtml(href);
-      const titleAttr = title ? ` title="${this.escapeHtml(title)}"` : "";
-      return `<a href="${safeHref}"${titleAttr}>${text}</a>`;
-    };
-    return renderer;
-  })();
+      const safeHref = this.escapeHtml(opts.href);
+      const titleAttr = opts.title ? ` title="${this.escapeHtml(opts.title)}"` : "";
+      return `<a href="${safeHref}"${titleAttr}>${content}</a>`;
+    }
+  });
   /**
    * Clear all cached content.
    * Useful for hot reload during development.
@@ -139,7 +142,7 @@ var ContentManager = class {
       }
       const fileContent = await this.driver.read(filePath);
       const { data, content, excerpt } = (0, import_gray_matter.default)(fileContent);
-      const html = await import_marked.marked.parse(content, { renderer: this.renderer });
+      const html = this.mdAdapter.render(content, this.renderCallbacks);
       const item = {
         slug,
         body: html,
@@ -255,9 +258,6 @@ var ContentManager = class {
     }
     return value;
   }
-  escapeHtml(value) {
-    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-  }
   isSafeUrl(href) {
     const trimmed = href.trim();
     if (!trimmed) {
@@ -315,13 +315,12 @@ var ContentWatcher = class {
         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)
-        );
+        const timer = setTimeout(() => {
+          this.handleFileChange(collection, filename.toString(), localePrefix);
+          this.debounceTimers.delete(key);
+        }, this.options.debounceMs ?? 100);
+        timer.unref?.();
+        this.debounceTimers.set(key, timer);
       });
       this.watchers.push(watcher);
     } catch (_e) {
@@ -653,8 +652,8 @@ var RouterHelper = class {
     };
     for (const [method, [verb, suffix]] of Object.entries(routes)) {
       if (typeof controller.prototype[method] === "function") {
-        ;
-        app[verb](`${p}${suffix}`, controller.call(method));
+        const route = app[verb];
+        route.call(app, `${p}${suffix}`, controller.call(method));
       }
     }
   }

package/dist/index.d.cts

@@ -2,7 +2,6 @@ import * as _gravito_core from '@gravito/core';
 import { GravitoContext, GravitoOrbit, PlanetCore } from '@gravito/core';
 import { TSchema } from '@gravito/mass';
 export { Schema } from '@gravito/mass';
-import { Hono } from 'hono';
 
 interface ContentDriver {
     read(path: string): Promise<string>;
@@ -30,6 +29,11 @@ interface CollectionConfig {
 }
 /**
  * Manages fetching, parsing, and caching of filesystem-based content.
+ *
+ * 使用 RuntimeMarkdownAdapter 進行 Markdown 渲染，在 Bun 環境下
+ * 自動使用原生 C++ 解析器（10-100x 更快），並保留 XSS 防護的
+ * 自訂渲染回調。
+ *
  * @public
  */
 declare class ContentManager {
@@ -37,7 +41,9 @@ declare class ContentManager {
     private collections;
     private cache;
     private searchIndex;
-    private renderer;
+    private escapeHtml;
+    private readonly mdAdapter;
+    private readonly renderCallbacks;
     /**
      * Clear all cached content.
      * Useful for hot reload during development.
@@ -97,7 +103,6 @@ declare class ContentManager {
     }): ContentItem[];
     private buildSearchIndex;
     private sanitizeSegment;
-    private escapeHtml;
     private isSafeUrl;
 }
 
@@ -230,6 +235,15 @@ declare abstract class FormRequest {
     static middleware(): any;
 }
 
+/**
+ * 路由註冊用的應用介面
+ */
+interface RoutableApp {
+    get(path: string, handler: unknown): unknown;
+    post(path: string, handler: unknown): unknown;
+    put(path: string, handler: unknown): unknown;
+    delete(path: string, handler: unknown): unknown;
+}
 /**
  * Utility for registering resourceful routes.
  * @public
@@ -246,7 +260,7 @@ declare class RouterHelper {
      * PUT    /prefix/:id      -> update
      * DELETE /prefix/:id      -> destroy
      */
-    static resource(app: Hono<any, any, any>, prefix: string, controller: any): void;
+    static resource(app: RoutableApp, prefix: string, controller: any): void;
 }
 
 declare module '@gravito/core' {

package/dist/index.d.ts

@@ -2,7 +2,6 @@ import * as _gravito_core from '@gravito/core';
 import { GravitoContext, GravitoOrbit, PlanetCore } from '@gravito/core';
 import { TSchema } from '@gravito/mass';
 export { Schema } from '@gravito/mass';
-import { Hono } from 'hono';
 
 interface ContentDriver {
     read(path: string): Promise<string>;
@@ -30,6 +29,11 @@ interface CollectionConfig {
 }
 /**
  * Manages fetching, parsing, and caching of filesystem-based content.
+ *
+ * 使用 RuntimeMarkdownAdapter 進行 Markdown 渲染，在 Bun 環境下
+ * 自動使用原生 C++ 解析器（10-100x 更快），並保留 XSS 防護的
+ * 自訂渲染回調。
+ *
  * @public
  */
 declare class ContentManager {
@@ -37,7 +41,9 @@ declare class ContentManager {
     private collections;
     private cache;
     private searchIndex;
-    private renderer;
+    private escapeHtml;
+    private readonly mdAdapter;
+    private readonly renderCallbacks;
     /**
      * Clear all cached content.
      * Useful for hot reload during development.
@@ -97,7 +103,6 @@ declare class ContentManager {
     }): ContentItem[];
     private buildSearchIndex;
     private sanitizeSegment;
-    private escapeHtml;
     private isSafeUrl;
 }
 
@@ -230,6 +235,15 @@ declare abstract class FormRequest {
     static middleware(): any;
 }
 
+/**
+ * 路由註冊用的應用介面
+ */
+interface RoutableApp {
+    get(path: string, handler: unknown): unknown;
+    post(path: string, handler: unknown): unknown;
+    put(path: string, handler: unknown): unknown;
+    delete(path: string, handler: unknown): unknown;
+}
 /**
  * Utility for registering resourceful routes.
  * @public
@@ -246,7 +260,7 @@ declare class RouterHelper {
      * PUT    /prefix/:id      -> update
      * DELETE /prefix/:id      -> destroy
      */
-    static resource(app: Hono<any, any, any>, prefix: string, controller: any): void;
+    static resource(app: RoutableApp, prefix: string, controller: any): void;
 }
 
 declare module '@gravito/core' {

package/dist/index.js

@@ -1,7 +1,11 @@
 // src/ContentManager.ts
 import { join, parse } from "path";
+import {
+  createHtmlRenderCallbacks,
+  getEscapeHtml,
+  getMarkdownAdapter
+} from "@gravito/core";
 import matter from "gray-matter";
-import { marked } from "marked";
 var ContentManager = class {
   /**
    * Create a new ContentManager instance.
@@ -16,19 +20,22 @@ var ContentManager = class {
   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);
-    renderer.link = (href, title, text) => {
-      if (!href || !this.isSafeUrl(href)) {
-        return text;
+  // Escape HTML helper
+  escapeHtml = getEscapeHtml();
+  // RuntimeMarkdownAdapter（自動選擇 Bun 原生或 marked fallback）
+  mdAdapter = getMarkdownAdapter();
+  // 完整的 HTML 渲染回調（含 XSS 防護覆寫）
+  renderCallbacks = createHtmlRenderCallbacks({
+    html: (rawHtml) => this.escapeHtml(rawHtml),
+    link: (content, opts) => {
+      if (!opts.href || !this.isSafeUrl(opts.href)) {
+        return content;
       }
-      const safeHref = this.escapeHtml(href);
-      const titleAttr = title ? ` title="${this.escapeHtml(title)}"` : "";
-      return `<a href="${safeHref}"${titleAttr}>${text}</a>`;
-    };
-    return renderer;
-  })();
+      const safeHref = this.escapeHtml(opts.href);
+      const titleAttr = opts.title ? ` title="${this.escapeHtml(opts.title)}"` : "";
+      return `<a href="${safeHref}"${titleAttr}>${content}</a>`;
+    }
+  });
   /**
    * Clear all cached content.
    * Useful for hot reload during development.
@@ -95,7 +102,7 @@ var ContentManager = class {
       }
       const fileContent = await this.driver.read(filePath);
       const { data, content, excerpt } = matter(fileContent);
-      const html = await marked.parse(content, { renderer: this.renderer });
+      const html = this.mdAdapter.render(content, this.renderCallbacks);
       const item = {
         slug,
         body: html,
@@ -211,9 +218,6 @@ var ContentManager = class {
     }
     return value;
   }
-  escapeHtml(value) {
-    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-  }
   isSafeUrl(href) {
     const trimmed = href.trim();
     if (!trimmed) {
@@ -271,13 +275,12 @@ var ContentWatcher = class {
         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)
-        );
+        const timer = setTimeout(() => {
+          this.handleFileChange(collection, filename.toString(), localePrefix);
+          this.debounceTimers.delete(key);
+        }, this.options.debounceMs ?? 100);
+        timer.unref?.();
+        this.debounceTimers.set(key, timer);
       });
       this.watchers.push(watcher);
     } catch (_e) {
@@ -609,8 +612,8 @@ var RouterHelper = class {
     };
     for (const [method, [verb, suffix]] of Object.entries(routes)) {
       if (typeof controller.prototype[method] === "function") {
-        ;
-        app[verb](`${p}${suffix}`, controller.call(method));
+        const route = app[verb];
+        route.call(app, `${p}${suffix}`, controller.call(method));
       }
     }
   }

package/doc/KNOWLEDGE_MANAGEMENT.md

@@ -0,0 +1,60 @@
+# Knowledge Management Guide
+
+`@gravito/monolith` allows you to treat your markdown files as a structured data source, enabling Git-based content management.
+
+## 1. Defining Collections
+
+Organize your content into logical folders. Each folder becomes a "Collection".
+
+```
+content/
+├── docs/          # Collection: 'docs'
+│   ├── install.md
+│   └── api.md
+└── blog/          # Collection: 'blog'
+    └── hello.md
+```
+
+## 2. Frontmatter as Metadata
+
+Use YAML frontmatter to add type-safe metadata to your content.
+
+```markdown
+---
+title: My Title
+tags: [news, update]
+featured: true
+---
+```
+
+## 3. Querying the Knowledge Core
+
+Use the fluent API to retrieve and filter content.
+
+```typescript
+const content = c.get('content');
+
+// Fetch a single post
+const post = await content.collection('blog')
+  .slug('hello-world')
+  .fetch();
+
+// List all items in a collection
+const posts = await content.collection('blog').all();
+```
+
+## 4. SSG Integration
+
+Combine Monolith with `@gravito/prism` to build extremely fast static sites.
+
+```typescript
+// During SSG phase
+const posts = await content.collection('blog').all();
+for (const post of posts) {
+  ssg.addPage(`/blog/${post.slug}`, 'blog-template', { post });
+}
+```
+
+## 5. Performance: Memory Caching
+
+Monolith caches the parsed markdown and metadata in memory. In a **Galaxy Architecture**, you can enable `Plasma` backing to share this cache across instances.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gravito/monolith",
-  "version": "3.2.0",
+  "sideEffects": false,
+  "version": "3.2.3",
   "description": "Enterprise monolith framework for Gravito Galaxy",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -14,7 +15,8 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "build": "tsup src/index.ts --format esm,cjs",
+    "build:dts": "tsup src/index.ts --format esm,cjs --dts",
     "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",
@@ -31,16 +33,18 @@
   "author": "Carl Lee <carllee0520@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "@gravito/mass": "workspace:*",
+    "@gravito/mass": "^3.0.3",
     "@octokit/rest": "^22.0.1",
-    "gray-matter": "^4.0.3",
+    "gray-matter": "^4.0.3"
+  },
+  "optionalDependencies": {
     "marked": "^11.1.1"
   },
   "peerDependencies": {
-    "@gravito/core": "workspace:*"
+    "@gravito/core": "^2.0.0"
   },
   "devDependencies": {
-    "@gravito/core": "workspace:*",
+    "@gravito/core": "^2.0.6",
     "@types/marked": "^5.0.0",
     "bun-types": "^1.3.5",
     "tsup": "^8.5.1",

package/package.json.bak

@@ -0,0 +1,58 @@
+{
+  "name": "@gravito/monolith",
+  "version": "3.2.0",
+  "description": "Enterprise monolith framework for Gravito Galaxy",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "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",
+    "orbit",
+    "monolith",
+    "backend"
+  ],
+  "author": "Carl Lee <carllee0520@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@gravito/mass": "workspace:*",
+    "@octokit/rest": "^22.0.1",
+    "gray-matter": "^4.0.3",
+    "marked": "^11.1.1"
+  },
+  "peerDependencies": {
+    "@gravito/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@gravito/core": "workspace:*",
+    "@types/marked": "^5.0.0",
+    "bun-types": "^1.3.5",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/gravito-framework/gravito#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gravito-framework/gravito.git",
+    "directory": "packages/monolith"
+  }
+}

package/src/ContentManager.ts

@@ -1,6 +1,12 @@
 import { join, parse } from 'node:path'
+import {
+  createHtmlRenderCallbacks,
+  getEscapeHtml,
+  getMarkdownAdapter,
+  type MarkdownRenderCallbacks,
+  type RuntimeMarkdownAdapter,
+} from '@gravito/core'
 import matter from 'gray-matter'
-import { marked } from 'marked'
 import type { ContentDriver } from './driver/ContentDriver'
 
 /**
@@ -26,6 +32,11 @@ export interface CollectionConfig {
 
 /**
  * Manages fetching, parsing, and caching of filesystem-based content.
+ *
+ * 使用 RuntimeMarkdownAdapter 進行 Markdown 渲染，在 Bun 環境下
+ * 自動使用原生 C++ 解析器（10-100x 更快），並保留 XSS 防護的
+ * 自訂渲染回調。
+ *
  * @public
  */
 export class ContentManager {
@@ -34,19 +45,24 @@ export class ContentManager {
   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)
-    renderer.link = (href: string | null, title: string | null, text: string) => {
-      if (!href || !this.isSafeUrl(href)) {
-        return text
+
+  // Escape HTML helper
+  private escapeHtml = getEscapeHtml()
+
+  // RuntimeMarkdownAdapter（自動選擇 Bun 原生或 marked fallback）
+  private readonly mdAdapter: RuntimeMarkdownAdapter = getMarkdownAdapter()
+  // 完整的 HTML 渲染回調（含 XSS 防護覆寫）
+  private readonly renderCallbacks: MarkdownRenderCallbacks = createHtmlRenderCallbacks({
+    html: (rawHtml: string) => this.escapeHtml(rawHtml),
+    link: (content: string, opts: { href: string; title?: string }) => {
+      if (!opts.href || !this.isSafeUrl(opts.href)) {
+        return content
       }
-      const safeHref = this.escapeHtml(href)
-      const titleAttr = title ? ` title="${this.escapeHtml(title)}"` : ''
-      return `<a href="${safeHref}"${titleAttr}>${text}</a>`
-    }
-    return renderer
-  })()
+      const safeHref = this.escapeHtml(opts.href)
+      const titleAttr = opts.title ? ` title="${this.escapeHtml(opts.title)}"` : ''
+      return `<a href="${safeHref}"${titleAttr}>${content}</a>`
+    },
+  })
 
   /**
    * Clear all cached content.
@@ -134,7 +150,8 @@ export class ContentManager {
       const fileContent = await this.driver.read(filePath)
       const { data, content, excerpt } = matter(fileContent)
 
-      const html = await marked.parse(content, { renderer: this.renderer })
+      // 使用 RuntimeMarkdownAdapter.render() 搭配完整 HTML 回調（含 XSS 防護）
+      const html = this.mdAdapter.render(content, this.renderCallbacks)
 
       const item: ContentItem = {
         slug,
@@ -272,15 +289,6 @@ export class ContentManager {
     return value
   }
 
-  private escapeHtml(value: string): string {
-    return value
-      .replace(/&/g, '&amp;')
-      .replace(/</g, '&lt;')
-      .replace(/>/g, '&gt;')
-      .replace(/"/g, '&quot;')
-      .replace(/'/g, '&#39;')
-  }
-
   private isSafeUrl(href: string): boolean {
     const trimmed = href.trim()
     if (!trimmed) {

package/src/ContentWatcher.ts

@@ -54,13 +54,12 @@ export class ContentWatcher {
           clearTimeout(this.debounceTimers.get(key))
         }
 
-        this.debounceTimers.set(
-          key,
-          setTimeout(() => {
-            this.handleFileChange(collection, filename.toString(), localePrefix)
-            this.debounceTimers.delete(key)
-          }, this.options.debounceMs ?? 100)
-        )
+        const timer = setTimeout(() => {
+          this.handleFileChange(collection, filename.toString(), localePrefix)
+          this.debounceTimers.delete(key)
+        }, this.options.debounceMs ?? 100)
+        timer.unref?.()
+        this.debounceTimers.set(key, timer)
       })
 
       this.watchers.push(watcher)

package/src/Router.ts

@@ -1,4 +1,12 @@
-import type { Hono } from 'hono'
+/**
+ * 路由註冊用的應用介面
+ */
+interface RoutableApp {
+  get(path: string, handler: unknown): unknown
+  post(path: string, handler: unknown): unknown
+  put(path: string, handler: unknown): unknown
+  delete(path: string, handler: unknown): unknown
+}
 
 /**
  * Utility for registering resourceful routes.
@@ -16,7 +24,7 @@ export class RouterHelper {
    * PUT    /prefix/:id      -> update
    * DELETE /prefix/:id      -> destroy
    */
-  public static resource(app: Hono<any, any, any>, prefix: string, controller: any) {
+  public static resource(app: RoutableApp, prefix: string, controller: any) {
     const p = prefix.startsWith('/') ? prefix : `/${prefix}`
 
     // Mapping: Method -> [HTTP Verb, Path Suffix]
@@ -32,7 +40,8 @@ export class RouterHelper {
 
     for (const [method, [verb, suffix]] of Object.entries(routes)) {
       if (typeof controller.prototype[method] === 'function') {
-        ;(app as any)[verb](`${p}${suffix}`, controller.call(method))
+        const route = app[verb as keyof RoutableApp] as (path: string, handler: unknown) => unknown
+        route.call(app, `${p}${suffix}`, controller.call(method))
       }
     }
   }

package/src/middleware/TrimStrings.ts

@@ -1,10 +1,10 @@
-import type { MiddlewareHandler } from 'hono'
+import type { GravitoContext, GravitoNext } from '@gravito/core'
 
 /**
  * Automatically trim all strings in the request body and query.
  */
-export const trimStrings = (): MiddlewareHandler => {
-  return async (c, next) => {
+export const trimStrings = () => {
+  return async (c: GravitoContext, next: GravitoNext) => {
     // We proxy the req.json and req.query methods to return trimmed data
     // This is more efficient than pre-processing everything if the controller doesn't use it.
 
@@ -13,7 +13,7 @@ export const trimStrings = (): MiddlewareHandler => {
       try {
         const body = await c.req.json()
         clean(body, (val) => (typeof val === 'string' ? val.trim() : val))
-        // Since Hono's body is already read, we might need to store it in context
+        // Since body is already read, we might need to store it in context
         // But for now, let's assume we use a simpler approach for the prototype.
       } catch {
         // Skip if not valid JSON

package/tests/content-watcher.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test'
 import { existsSync } from 'node:fs'
 import { mkdir, rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
@@ -53,4 +53,17 @@ describe('ContentWatcher', () => {
 
     watcher.close()
   })
+
+  it('should call close without errors', async () => {
+    // Test basic functionality: ContentWatcher can be instantiated and closed
+    // without errors. The actual file watching behavior is tested in the first test.
+    const manager = new ContentManager(new LocalDriver(TMP_DIR))
+    manager.defineCollection('docs', { path: 'docs' })
+
+    const watcher = new ContentWatcher(manager, TMP_DIR, { debounceMs: 100 })
+    watcher.watch('docs')
+
+    // Verify watcher can be closed without errors
+    expect(() => watcher.close()).not.toThrow()
+  })
 })

package/tests/content.test.ts

@@ -40,3 +40,63 @@ describe('Orbit Content Manager', () => {
     expect(items[0].slug).toBe('install')
   })
 })
+
+// ============ Phase 1 遷移驗證測試 ============
+
+describe('ContentManager - RuntimeMarkdownAdapter 遷移', () => {
+  const rootDir = join(import.meta.dir, 'fixtures')
+
+  test('使用 RuntimeMarkdownAdapter 產生的 HTML 與既有行為一致', async () => {
+    const manager = new ContentManager(new LocalDriver(rootDir))
+    manager.defineCollection('docs', { path: 'docs' })
+
+    const item = await manager.find('docs', 'install', 'en')
+    expect(item).not.toBeNull()
+    // 關鍵驗證：HTML 輸出格式和 marked 一致
+    expect(item?.body).toContain('<h1>Installation</h1>')
+    expect(item?.body).toContain('<p>To install Gravito, run:</p>')
+    expect(item?.body).toContain('<pre><code class="language-bash">')
+  })
+
+  test('自訂 link 渲染產生安全的 HTML', async () => {
+    const manager = new ContentManager(new LocalDriver(rootDir))
+    manager.defineCollection('docs', { path: 'docs' })
+
+    // ContentManager 的自訂 renderer 應過濾 javascript: URLs
+    // 透過 renderCallbacks 驗證自訂 link 渲染
+    const item = await manager.find('docs', 'install', 'en')
+    expect(item).not.toBeNull()
+    // body 中不應含有 javascript: 協議
+    expect(item?.body).not.toContain('javascript:')
+  })
+
+  test('gray-matter frontmatter 解析在遷移後保持不變', async () => {
+    const manager = new ContentManager(new LocalDriver(rootDir))
+    manager.defineCollection('docs', { path: 'docs' })
+
+    const item = await manager.find('docs', 'install', 'en')
+    expect(item).not.toBeNull()
+    // Frontmatter 欄位完整
+    expect(item?.meta.title).toBe('Installation Guide')
+    expect(item?.meta.description).toBe('How to install Gravito')
+    expect(item?.meta.date).toBeDefined()
+    // raw 欄位應為 markdown 內容（不含 frontmatter）
+    expect(item?.raw).toContain('# Installation')
+    expect(item?.raw).not.toContain('---')
+  })
+
+  test('快取機制在遷移後正常運作', async () => {
+    const manager = new ContentManager(new LocalDriver(rootDir))
+    manager.defineCollection('docs', { path: 'docs' })
+
+    // 第一次讀取
+    const item1 = await manager.find('docs', 'install', 'en')
+    // 第二次讀取（應從快取取得）
+    const item2 = await manager.find('docs', 'install', 'en')
+
+    expect(item1).not.toBeNull()
+    expect(item2).not.toBeNull()
+    // 快取應回傳相同物件
+    expect(item1).toBe(item2)
+  })
+})

package/tsconfig.json

@@ -2,13 +2,8 @@
   "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "./dist",
-    "baseUrl": ".",
     "skipLibCheck": true,
-    "types": ["bun-types"],
-    "paths": {
-      "@gravito/core": ["../../packages/core/src/index.ts"],
-      "@gravito/*": ["../../packages/*/src/index.ts"]
-    }
+    "types": ["bun-types"]
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist", "**/*.test.ts"]