Merge pull request #11 from objectstack-ai/copilot/setup-fumadocs-site

Migrate documentation site to Fumadocs with monorepo structure and shared content

Author: hotlong

.cursorrules.d/objectstack.prompt.md

@@ -0,0 +1,80 @@
+🌌 ObjectStack Master Architecture Context
+
+Role: You are the Chief Architect and CPO of ObjectStack Inc.
+
+Mission: Build the "Post-SaaS Operating System" — an open-core, local-first ecosystem that virtualizes data (SQL/Redis/Excel) and unifies business logic.
+1. The "Galaxy" Architecture (Monorepo Structure)
+We use a Monorepo (pnpm + Turborepo) to manage the ecosystem, but components are designed to be published independently.
+Directory Structure & Responsibilities
+ * packages/protocol (The Constitution) [Apache 2.0]
+   * CRITICAL: Contains the shared manifest.schema.json, TypeScript interfaces, and plugin lifecycle hooks (onInstall, onEnable).
+   * Rule: All other packages depend on this. No circular dependencies.
+ * packages/objectql (Data Engine) [Apache 2.0]
+   * Universal Data Protocol. Compiles GraphQL-like queries into SQL/Redis commands.
+ * packages/objectos (Business Kernel) [AGPL v3]
+   * The Crown Jewel. Identity, RBAC, Workflow, and Audit Logging.
+   * License Note: Strict AGPL to prevent SaaS wrapping by competitors.
+ * packages/objectui (Projection Engine) [MIT]
+   * React/Shadcn UI components for Server-Driven UI (SDUI).
+ * packages/sdk (Plugin Kit) [MIT]
+   * Tools for third-party developers to build Marketplace plugins.
+ * drivers/* [Apache 2.0]
+   * driver-postgres, driver-redis, driver-excel.
+   * Must implement interfaces defined in packages/protocol.
+Commercial & Apps
+ * apps/www (Official Website): Marketing, Landing Pages, "Platform" Showcase.
+ * apps/marketplace (Public Storefront): SEO-optimized Registry for plugins/drivers.
+ * apps/cloud (SaaS Console): Multi-tenant management dashboard (Private).
+ * apps/studio (Desktop IDE): Electron-based local-first tool for schema editing & data management.
+ * modules/enterprise-core (Private Source): SSO, Oracle Drivers, Advanced Audit.
+
+2. Navigation & Information Architecture (The "Mega Menu")
+
+Reflects the strategy: Technology (Platform) vs. Service (Enterprise).
+Top Navbar Layout:
+[Logo] | Platform ▾ | Ecosystem ▾ | Developers ▾ | [Enterprise] | Pricing || [Search] [GitHub] [Console ▾]
+ * Platform ▾ (The Tech Stack)
+   * Col 1 (Framework): ObjectQL, ObjectOS, ObjectUI.
+   * Col 2 (Tools): Object Studio (Highlight: Local-First IDE), ObjectCloud, CLI.
+   * Footer: "Community vs. Enterprise Edition →"
+ * Ecosystem ▾ (The Connections)
+   * Marketplace (Link to apps/marketplace).
+   * Drivers: Icons for Postgres, Redis, Excel, Salesforce.
+ * Enterprise (Direct Link)
+   * High-value entry for SLA, Compliance, and Self-hosted Licensing.
+ * Console ▾ (Auth Entry)
+   * ObjectCloud (SaaS Login).
+   * Enterprise Portal (License Management).
+   * 
+3. The Packaging Protocol (The "Manifest")
+
+We do not rely solely on package.json. We use a strict ObjectStack Manifest standard.
+File: objectstack.config.ts (or strict JSON inside package.json)
+Schema Location: packages/protocol/schemas/manifest.schema.json
+Key Fields:
+ * type: app | plugin | driver
+ * menus: Array of navigation items to inject into the OS sidebar.
+ * permissions: Array of requested capabilities (e.g., finance.read).
+ * entities: Path patterns to auto-load Schema files (e.g., ./src/schemas/*.gql).
+ * lifecycle: Hooks for onInstall, onEnable.
+4. Strategic Rules for AI Generation
+A. Licensing & Headers
+ * When generating code for packages/objectos, ALWAYS add the AGPL v3 header.
+ * When generating code for packages/objectql, use Apache 2.0.
+ * When generating code for apps/studio or apps/www, use MIT.
+B. Terminology
+ * NEVER say "SaaS Product" when referring to the open source core. Call it the "Framework" or "Engine".
+ * ALWAYS emphasize "Polyglot Data". We are not just a SQL wrapper; we handle Redis and Excel native files.
+ * Studio vs. Cloud: Studio is for "Local Data & Development". Cloud is for "Deployment & Collaboration".
+C. Coding Style
+ * Monorepo: Use generic imports (e.g., import { User } from '@objectstack/protocol') instead of relative paths like ../../packages/protocol.
+ * UI: Use Shadcn UI + Tailwind CSS. Dark mode default for developer tools (Studio/Console).
+ * Data Fetching: All UI components must be Server-Driven or strongly typed against the Schema.
+5. Execution Context
+When I ask you to build a feature, first determine:
+ * Which layer does it belong to? (Protocol? Engine? UI?)
+ * Is it Open Source or Commercial?
+ * Does it require updating the Protocol Manifest?
+Example:
+User: "Add a CRM plugin."
+AI: "I will define the CRM data structure in packages/protocol, create a crm-plugin package implementing the manifest.json standard, and register the 'Customer' menu item."

.cursorrules.d/todo-checklist.md

@@ -0,0 +1,125 @@
+---
+title: Documentation
+---
+
+### 🟢 P0: 核心元模型 (The Metamodel)
+
+*没有这部分，ObjectQL 和 ObjectUI 无法通信，系统无法运转。这是“万物皆对象”的法律定义。*
+
+* **[ ] 1. 实体定义协议 (`EntitySchema`)**
+* **定义目标**: 描述一个“对象”长什么样。
+* **关键字段**: `name` (机器名), `label` (显示名), `dataSource` (存哪), `dbName` (物理表名)。
+* **用途**: ObjectQL 解析 `.gql` 文件后生成的 AST 结构；`/_api/metadata/objects/{name}` 的返回值。
+
+
+* **[ ] 2. 字段定义协议 (`FieldSchema`)**
+* **定义目标**: 描述对象里的“属性”。
+* **关键字段**: `type` (text/number/lookup...), `required`, `unique`, `defaultValue`。
+* **关键枚举**: `FieldType` (必须枚举所有支持的类型，如 `master_detail`, `formula`, `image`)。
+* **用途**: 告诉前端渲染什么组件，告诉后端怎么建表。
+
+
+* **[ ] 3. 视图/布局协议 (`LayoutSchema`)**
+* **定义目标**: 描述界面如何排列。
+* **关键结构**:
+* `ListView`: 列定义 (`columns`), 排序 (`sort`), 筛选 (`filters`)。
+* `FormView`: 区域 (`sections`), 字段分组 (`groups`)。
+
+
+* **用途**: ObjectUI 根据这个 JSON 渲染页面，而不是写死 React 代码。
+
+
+
+---
+
+### 🔵 P1: 插件与分发 (Packaging & Runtime)
+
+*没有这部分，你的应用市场和插件机制就是空谈。*
+
+* **[ ] 4. 插件清单协议 (`ManifestSchema`)**
+* **定义目标**: 描述一个软件包（插件/应用）。
+* **文件对应**: `objectstack.config.ts` 或 `package.json > objectstack`。
+* **关键字段**: `id`, `version`, `type` (app/plugin/driver), `permissions` (申请权限), `menus` (导航注入)。
+* **用途**: CLI 打包校验，应用商店展示。
+
+
+* **[ ] 5. 生命周期接口 (`PluginLifecycle`)**
+* **定义目标**: 插件在运行时如何被加载。
+* **接口定义**: `interface ObjectStackPlugin`
+* **关键方法**: `onInstall(ctx)`, `onEnable(ctx)`, `onDisable(ctx)`。
+* **Context 定义**: `ctx.ql` (数据能力), `ctx.os` (系统能力), `ctx.logger`。
+* **用途**: ObjectOS 加载 `node_modules` 时的统一入口标准。
+
+
+* **[ ] 6. 导航菜单协议 (`NavigationSchema`)**
+* **定义目标**: 描述侧边栏菜单结构。
+* **关键字段**: `label`, `icon`, `path`, `children`, `visible_on` (权限控制)。
+* **用途**: 多个插件的菜单合并渲染到 ObjectCloud / Studio 的侧边栏。
+
+
+
+---
+
+### 🟠 P2: 驱动与连接 (Drivers & Logic)
+
+*这部分决定了你的系统扩展性（能不能连 Excel，能不能写自定义代码）。*
+
+* **[ ] 7. 数据驱动接口 (`DriverInterface`)**
+* **定义目标**: 任何数据库要想接入 ObjectQL，必须实现的标准。
+* **核心方法**:
+* `find(entity, query)`
+* `create(entity, data)`
+* `update(entity, id, data)`
+* `delete(entity, id)`
+* `syncSchema(entity)` (DDL 操作：建表/加字段)
+
+
+* **用途**: 让 `driver-postgres`, `driver-excel`, `driver-salesforce` 行为一致。
+
+
+* **[ ] 8. 触发器上下文协议 (`TriggerContext`)**
+* **定义目标**: 当用户写 `beforeInsert` 代码时，传入参数的标准。
+* **接口定义**:
+* `doc` (当前记录)
+* `previousDoc` (修改前的记录)
+* `userId` (谁在操作)
+
+
+* **用途**: 规范化业务逻辑代码的编写。
+
+
+* **[ ] 9. UI 组件契约 (`WidgetContract`)**
+* **定义目标**: 第三方开发者开发自定义 UI 组件（如：地图选择器）的标准。
+* **接口定义**: `interface FieldWidgetProps { value, onChange, readonly, options }`。
+* **用途**: 让社区开发的 React 组件能无缝嵌入到 ObjectUI 的表单中。
+
+
+
+---
+
+### 💾 你的“立法”行动路线图
+
+建议你在 `packages/spec` 仓库中按以下文件结构落地这些协议：
+
+```text
+packages/spec/
+├── src/
+│   ├── types/
+│   │   ├── meta/           <-- P0: Metamodel
+│   │   │   ├── entity.ts   (EntitySchema)
+│   │   │   ├── field.ts    (FieldSchema)
+│   │   │   └── view.ts     (LayoutSchema)
+│   │   ├── bundle/         <-- P1: Packaging
+│   │   │   ├── manifest.ts (ManifestSchema)
+│   │   │   └── menu.ts     (NavigationSchema)
+│   │   ├── runtime/        <-- P2: Logic
+│   │   │   ├── plugin.ts   (Lifecycle)
+│   │   │   └── driver.ts   (DriverInterface)
+│   │   └── auth/           <-- from plugin-auth
+│   │       └── session.ts  (User/Session Interface)
+│   ├── zods/               <-- 对应的 Zod 实现 (用于运行时校验)
+│   └── constants/          <-- 目录约定 (paths)
+└── package.json
+
+```
+

.gitignore

@@ -41,4 +41,13 @@ temp/
 packages/*/dist/
 packages/*/*.tsbuildinfo
 
-.next
+# Next.js
+.next
+out/
+next-env.d.ts
+.vercel
+
+# Fumadocs
+.source/
+apps/*/. source/
+apps/*/.next/

README.md

@@ -10,18 +10,19 @@ This repository contains the core specifications, schemas, and protocols that po
 
 ## 📚 Documentation
 
-The official documentation is co-located in this repository.
+The official documentation is built with Fumadocs and Next.js.
 
-*   **[Concepts](./content/docs/concepts/):** Architecture, Manifesto, and Core Values.
-*   **[Specifications](./packages/spec/json-schema/):** Auto-generated JSON Schemas.
-*   **[API Reference](./content/docs/references/):** Detailed property references generated from code.
+*   **[Documentation Content](./content/docs/):** MDX documentation files (concepts, specifications, references).
+*   **[Documentation Site](./apps/docs/):** Fumadocs-powered Next.js app.
+*   **[Live Site](http://localhost:3000/docs):** Run `pnpm docs:dev` to view locally.
 
 ## 📦 Monorepo Structure
 
 | Package | Description | Status |
 | :--- | :--- | :--- |
 | **[`@objectstack/spec`](packages/spec)** | **THE PROTOCOL**. Contains all Zod definitions, Types, and JSON Schemas. | 🟢 **Active** |
-| `content/docs` | The documentation site source. | 🟢 **Active** |
+| **[`@objectstack/docs`](apps/docs)** | Documentation site built with Fumadocs and Next.js. | 🟢 **Active** |
+| `content/docs/` | Documentation content (MDX files). Shared resource. | 🟢 **Active** |
 | *Other packages* | *Legacy/Migration in progress* | 🟡 *Legacy* |
 
 ## 🛠️ The Protocol Architecture
@@ -67,11 +68,10 @@ pnpm --filter @objectstack/spec build
 # Output:
 # - packages/spec/dist/        (Compiled TS)
 # - packages/spec/json-schema/ (JSON Schemas)
-# - content/docs/references/   (Markdown Docs)
 
-# 3. Start Documentation Site (Optional)
-# (Assuming a doc site runner is configured)
-pnpm dev
+# 3. Start Documentation Site
+pnpm docs:dev
+# Visit http://localhost:3000/docs
 ```
 
 ## 🤝 Contribution

apps/docs/README.md

@@ -0,0 +1,75 @@
+# ObjectStack Documentation Site
+
+This is the documentation site for the ObjectStack Protocol, built with [Fumadocs](https://fumadocs.dev/) and Next.js.
+
+## Structure
+
+```
+Repository Root:
+├── content/docs/     # Documentation content (MDX files)
+│   ├── concepts/
+│   ├── references/
+│   └── specifications/
+
+apps/docs/
+├── app/              # Next.js app directory
+│   ├── docs/         # Documentation pages
+│   ├── layout.tsx    # Root layout
+│   └── source.ts     # Fumadocs source loader
+├── source.config.ts  # Fumadocs collection config (references ../../content/docs)
+├── next.config.mjs   # Next.js configuration
+├── tailwind.config.js
+├── postcss.config.mjs
+└── package.json
+```
+
+## Development
+
+```bash
+# From repository root
+pnpm docs:dev
+
+# Or from apps/docs
+pnpm dev
+```
+
+## Building
+
+```bash
+# From repository root
+pnpm docs:build
+
+# Or from apps/docs
+pnpm build
+```
+
+## Deployment
+
+```bash
+# From repository root
+pnpm docs:start
+
+# Or from apps/docs
+pnpm start
+```
+
+## Features
+
+- 📝 **MDX Support**: Write documentation with React components
+- 🎨 **Tailwind CSS v4**: Modern styling with Tailwind
+- 🔍 **Search**: Built-in search functionality (⌘K)
+- 🌗 **Dark Mode**: Automatic theme switching
+- 📱 **Responsive**: Mobile-friendly design
+- 🚀 **Static Generation**: All 136 pages pre-rendered for optimal performance
+
+## Content Management
+
+Documentation content is stored in the repository root at `/content/docs/` (shared location) with the following structure:
+
+- `concepts/` - Core concepts and architecture
+- `references/` - API and schema references
+- `specifications/` - Detailed specifications
+
+Each directory can have a `meta.json` file to configure navigation order and labels.
+
+**Note**: The content is stored at the root level to allow sharing with other tools and workflows. The Next.js app in `apps/docs/` references this content via relative path in `source.config.ts`.

apps/docs/app/docs/[[...slug]]/page.tsx

@@ -0,0 +1,47 @@
+import { source } from '@/app/source';
+import type { Metadata } from 'next';
+import { DocsPage, DocsBody } from 'fumadocs-ui/page';
+import { notFound } from 'next/navigation';
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+
+export default async function Page(props: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const params = await props.params;
+  const page = await source.getPage(params.slug ?? []);
+  if (!page) notFound();
+
+  const data = page.data as any;
+  const Content = data.body;
+
+  return (
+    <DocsPage toc={data.toc} full={data.full}>
+      <DocsBody>
+        <h1 className="mb-2 text-3xl font-bold text-foreground">{page.data.title}</h1>
+        {page.data.description && (
+          <p className="mb-8 text-lg text-muted-foreground">
+            {page.data.description}
+          </p>
+        )}
+        <Content components={defaultMdxComponents} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(props: {
+  params: Promise<{ slug?: string[] }>;
+}): Promise<Metadata> {
+  const params = await props.params;
+  const page = await source.getPage(params.slug ?? []);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}