Add server integration and CLI documentation

Introduces a new server integration guide for ObjectQL, detailing usage with Node.js, Express, and Next.js, and describing the HTTP protocol. Adds a README for the CLI package with installation and command usage. Updates main README and guide index to reference new server features and documentation.

Author: hotlong

README.md

@@ -44,7 +44,9 @@ It is **not** an ORM, but a high-level data protocol designed for AI agents, low
 * The core logic is completely decoupled from storage drivers.
 * Easily extensible to support other data sources (e.g., REST APIs, GraphQL, SQLite).
 
-
+* **🌐 Universal Server:**
+* Built-in HTTP adapter (`@objectql/server`) to run anywhere (Node, Express, Next.js).
+* Standardized JSON API for CRUD and Actions.
 
 ## 📦 Installation
 

docs/guide/index.md

@@ -14,6 +14,7 @@ ObjectQL connects to your database via drivers.
 *   [**MongoDB**](./drivers/mongo.md): MongoDB support.
 
 ## 3. Building Apps
+*   [**Server Integration**](./server-integration.md): Running ObjectQL on Node, Express, or Next.js.
 *   [**Hooks**](./logic-hooks.md): Writing triggers (before/after create, update, delete).
 *   [**Custom Actions**](./logic-actions.md): Defining custom RPC endpoints.
 *   [**AI Applications**](./ai.md): Building AI-powered apps.

docs/guide/server-integration.md

@@ -0,0 +1,99 @@
+# Server Integration
+
+ObjectQL is designed to be framework-agnostic. While it can be used directly as a library, we provide a standard `@objectql/server` package to expose your application via HTTP.
+
+## The `@objectql/server` Package
+
+This package provides a standardized way to handle HTTP requests, similar to libraries like `better-auth`. It receives a standard JSON request body and routes it to the correct internal ObjectQL operation (`find`, `create`, `action`, etc.).
+
+### Installation
+
+```bash
+pnpm add @objectql/server
+```
+
+## Supported Frameworks
+
+### 1. Node.js (Raw HTTP)
+
+You can mount the handler directly on a native Node.js `http.Server`.
+
+```typescript
+import { createNodeHandler } from '@objectql/server';
+import { app } from './my-objectql-app'; // Your ObjectQL instance
+import { createServer } from 'http';
+
+const server = createServer(createNodeHandler(app));
+server.listen(3000);
+```
+
+### 2. Express
+
+Mount ObjectQL on any route path.
+
+```typescript
+import express from 'express';
+import { createNodeHandler } from '@objectql/server';
+import { app } from './my-objectql-app';
+
+const server = express();
+// ObjectQL server adapter handles body parsing automatically,
+// but works fine if you already used express.json()
+server.all('/api/objectql', createNodeHandler(app));
+
+server.listen(3000);
+```
+
+### 3. Next.js (Pages Router)
+
+```typescript
+// pages/api/objectql.ts
+import { createNodeHandler } from '@objectql/server';
+import { app } from '../../lib/store';
+
+export const config = {
+  api: {
+    bodyParser: false, // Let ObjectQL handle it, or true if you prefer
+  },
+};
+
+export default createNodeHandler(app);
+```
+
+## The Protocol
+
+The server exposes a single endpoint that accepts POST requests with a JSON body defined by `ObjectQLRequest`:
+
+```typescript
+interface ObjectQLRequest {
+    op: 'find' | 'findOne' | 'create' | 'update' | 'delete' | 'count' | 'action';
+    object: string;
+    args: any;
+    user?: any; // For passing authentication context
+}
+```
+
+**Example (cURL):**
+
+```bash
+curl -X POST http://localhost:3000/api/objectql \
+  -H "Content-Type: application/json" \
+  -d '{
+    "op": "create",
+    "object": "User",
+    "args": {
+      "data": { "name": "Alice", "email": "alice@example.com" }
+    }
+  }'
+```
+
+## Dev Server
+
+For rapid prototyping, `@objectql/cli` provides a built-in dev server.
+
+```bash
+# Serves the current directory schema on port 3000
+objectql serve
+```
+
+See [CLI Documentation](../package/cli) for more details.

packages/cli/README.md

@@ -0,0 +1,41 @@
+# @objectql/cli
+
+Command Line Interface for ObjectQL.
+
+## Installation
+
+```bash
+npm install -g @objectql/cli
+# OR
+pnpm add -D @objectql/cli
+```
+
+## Commands
+
+### `generate` (alias: `g`)
+
+Generate TypeScript interfaces from your `object.yml` definitions.
+
+```bash
+objectql generate -s src -o src/generated
+```
+
+### `serve` (alias: `s`)
+
+Start a lightweight development server with an in-memory database. Perfect for rapid prototyping without setting up a backend project.
+
+```bash
+# Start server in current directory (port 3000)
+objectql serve
+
+# Specify options
+objectql serve --dir ./src/schema --port 8080
+```
+
+### `repl` (alias: `r`)
+
+Start an interactive shell to query your data.
+
+```bash
+objectql repl
+```