Merge branch 'main' into copilot/organize-raw-data-structure

Author: hotlong

.github/workflows/ci.yml

@@ -28,7 +28,7 @@ jobs:
 
     - name: Install dependencies
       run: pnpm install --frozen-lockfile
-
+      
     - name: Build packages
       run: pnpm run build
 

.vscode/launch.json

@@ -0,0 +1,53 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Studio: Basic Script",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/packages/cli/dist/index.js",
+      "args": [
+        "studio",
+        "--dir",
+        "examples/starters/basic-script"
+      ],
+      "console": "integratedTerminal",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "env": {
+        "NODE_ENV": "development"
+      }
+    },
+    {
+      "name": "Studio: Express API",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/packages/cli/dist/index.js",
+      "args": [
+        "studio",
+        "--dir",
+        "examples/starters/express-api"
+      ],
+      "console": "integratedTerminal",
+      "skipFiles": [
+        "<node_internals>/**"
+      ]
+    },
+    {
+      "name": "Studio: Preset Usage",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/packages/cli/dist/index.js",
+      "args": [
+        "studio",
+        "--dir",
+        "examples/scenarios/preset-usage"
+      ],
+      "console": "integratedTerminal",
+      "skipFiles": [
+        "<node_internals>/**"
+      ]
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,34 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Run Studio: Basic Script",
+      "type": "shell",
+      "command": "node",
+      "args": [
+        "packages/cli/dist/index.js",
+        "studio",
+        "--dir",
+        "examples/starters/basic-script"
+      ],
+      "group": "test",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": false,
+        "panel": "shared",
+        "showReuseMessage": true,
+        "clear": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Build All Packages",
+      "type": "shell",
+      "command": "pnpm",
+      "args": ["run", "build"],
+      "group": "build",
+      "problemMatcher": ["$tsc"]
+    }
+  ]
+}

API_REFACTORING_SUMMARY.md

@@ -0,0 +1,114 @@
+# API Refactoring Summary
+
+## Overview
+Successfully refactored the ObjectQL server package to conform with the new API specification documented in `docs/api/README.md`.
+
+## Key Achievements
+
+### 1. REST API Implementation ✅
+Created a complete REST-style API adapter supporting:
+- `GET /api/data/:object` - List records with filtering, sorting, pagination
+- `GET /api/data/:object/:id` - Get single record
+- `POST /api/data/:object` - Create new record (HTTP 201)
+- `PUT/PATCH /api/data/:object/:id` - Update record
+- `DELETE /api/data/:object/:id` - Delete record
+
+### 2. Enhanced Error Handling ✅
+- Standardized error codes: `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `INTERNAL_ERROR`, `DATABASE_ERROR`, `RATE_LIMIT_EXCEEDED`
+- Proper HTTP status code mapping (400, 401, 403, 404, 409, 429, 500)
+- Detailed error responses with error code, message, and optional details
+
+### 3. AI Context Support ✅
+- Added `ai_context` field to `ObjectQLRequest`
+- Supports intent, natural language descriptions, and use case tracking
+- Logged for debugging and analytics
+
+### 4. Metadata API Enhancements ✅
+- `GET /api/metadata/objects/:name/fields/:field` - Get detailed field metadata
+- `GET /api/metadata/objects/:name/actions` - List available actions
+- Enhanced field metadata with validation properties
+
+### 5. Improved JSON-RPC API ✅
+- Better error categorization and handling
+- Support for both string ID and query object in `findOne`
+- Standardized response formats
+- AI context logging
+
+### 6. Example Updates ✅
+- Updated express-api example to demonstrate all API styles
+- Added sample curl commands for testing
+- Clear console output showing all available endpoints
+
+## Testing
+- ✅ All existing tests pass (3/3)
+- ✅ New REST API tests added (7/7)
+- ✅ Total: 10/10 tests passing
+- ✅ Zero TypeScript errors
+
+## Usage Examples
+
+### JSON-RPC API
+```bash
+curl -X POST http://localhost:3004/api/objectql \
+  -H "Content-Type: application/json" \
+  -d '{"op": "find", "object": "User", "args": {}}'
+```
+
+### REST API
+```bash
+# List users
+curl http://localhost:3004/api/data/User
+
+# Get specific user
+curl http://localhost:3004/api/data/User/1
+
+# Create user
+curl -X POST http://localhost:3004/api/data/User \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice", "email": "alice@example.com"}'
+
+# Update user
+curl -X PUT http://localhost:3004/api/data/User/1 \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice Updated"}'
+
+# Delete user
+curl -X DELETE http://localhost:3004/api/data/User/1
+```
+
+### Metadata API
+```bash
+# List all objects
+curl http://localhost:3004/api/metadata/objects
+
+# Get object schema
+curl http://localhost:3004/api/metadata/objects/User
+
+# Get field metadata
+curl http://localhost:3004/api/metadata/objects/User/fields/email
+
+# List actions
+curl http://localhost:3004/api/metadata/objects/User/actions
+```
+
+## Files Changed
+- `packages/server/src/types.ts` - Enhanced type definitions
+- `packages/server/src/server.ts` - Improved error handling
+- `packages/server/src/adapters/rest.ts` - NEW: REST API adapter
+- `packages/server/src/adapters/node.ts` - Enhanced JSON-RPC handler
+- `packages/server/src/metadata.ts` - Added new metadata endpoints
+- `packages/server/src/index.ts` - Export REST handler
+- `packages/server/test/rest.test.ts` - NEW: REST API tests
+- `examples/starters/express-api/src/index.ts` - Updated example
+
+## Commits
+1. `6f58cea` - Initial changes with types and server enhancements
+2. `3c395a9` - Complete REST API implementation and tests
+
+## Next Steps (Optional)
+- [ ] Add rate limiting implementation
+- [ ] Add WebSocket API support
+- [ ] Add GraphQL API support
+- [ ] Add bulk operations support
+- [ ] Add field-level permission checks
+- [ ] Add request/response compression

README.md

@@ -34,6 +34,13 @@ It is **not** an ORM, but a high-level data protocol designed for AI agents, low
 * This structure is optimized for LLMs (like ChatGPT/Claude) to understand schema and generate accurate, safe business logic without hallucinating SQL syntax.
 
 
+* **✅ Metadata-Driven Validation:**
+* Define validation rules declaratively in YAML/JSON metadata.
+* Support for field-level, cross-field, and state machine validation.
+* Configurable severity levels (error, warning, info) and triggers (create, update, delete).
+* Template messages with internationalization support.
+
+
 * **⚡ Modern & Lightweight:**
 * Written in 100% **TypeScript**.
 * **Zero heavy legacy dependencies.** No runtime environment requirements beyond Node.js.
@@ -119,6 +126,100 @@ const resultsSql = await app.datasource('runtime').find(query);
 
 ```
 
+Both queries return the same results, but the underlying native query is optimized for MongoDB or PostgreSQL.
+
+### 3. Validation
+
+Define validation rules declaratively in your object metadata:
+
+```typescript
+import { ObjectConfig, Validator } from '@objectql/core';
+import { ValidationContext } from '@objectql/types';
+
+// Define object with validation rules
+const projectObject: ObjectConfig = {
+    name: 'project',
+    fields: {
+        name: { 
+            type: 'text', 
+            required: true,
+            validation: {
+                min_length: 3,
+                max_length: 100,
+                pattern: '^[a-zA-Z0-9\\s]+$'
+            }
+        },
+        email: {
+            type: 'email',
+            validation: {
+                format: 'email',
+                message: 'Please enter a valid email address'
+            }
+        },
+        start_date: { type: 'date' },
+        end_date: { type: 'date' },
+        status: { 
+            type: 'select', 
+            options: [
+                { label: 'Planning', value: 'planning' },
+                { label: 'Active', value: 'active' },
+                { label: 'Completed', value: 'completed' }
+            ]
+        }
+    },
+    validation: {
+        rules: [
+            // Cross-field validation
+            {
+                name: 'valid_date_range',
+                type: 'cross_field',
+                rule: {
+                    field: 'end_date',
+                    operator: '>=',
+                    compare_to: 'start_date'
+                },
+                message: 'End date must be on or after start date',
+                error_code: 'INVALID_DATE_RANGE'
+            },
+            // State machine validation
+            {
+                name: 'status_transition',
+                type: 'state_machine',
+                field: 'status',
+                transitions: {
+                    planning: { allowed_next: ['active', 'cancelled'] },
+                    active: { allowed_next: ['completed', 'cancelled'] },
+                    completed: { allowed_next: [], is_terminal: true }
+                },
+                message: 'Invalid status transition'
+            }
+        ]
+    }
+};
+
+// Execute validation programmatically
+const validator = new Validator({ language: 'en' });
+
+const result = await validator.validate(
+    projectObject.validation.rules,
+    {
+        record: { start_date: '2024-01-01', end_date: '2023-12-31' },
+        operation: 'create'
+    }
+);
+
+if (!result.valid) {
+    console.log('Validation errors:', result.errors);
+}
+```
+
+**Supported validation types:**
+- **Field-level**: required, email, URL, min/max, length, pattern
+- **Cross-field**: compare fields with operators (=, !=, >, >=, <, <=, in, contains, etc.)
+- **State machine**: enforce valid state transitions
+- **Severity levels**: error, warning, info
+- **I18n**: multi-language error messages with fallback
+
 ## 🎨 Web Console
 
 ObjectQL includes a beautiful web-based admin console for database management.
@@ -211,6 +312,33 @@ aggregations:
 
 See [Visual Reporting Guide](./docs/guide/visual-reporting.md) for complete documentation.
 
+## 📡 API Reference
+
+ObjectQL provides **multiple API styles** to suit different use cases:
+
+* **[Complete API Reference](./docs/api/README.md)** - Comprehensive guide to all API endpoints
+* **[JSON-RPC API](./docs/api/README.md#json-rpc-style-api)** - Universal protocol for all operations
+* **[REST API](./docs/api/README.md#rest-style-api)** - Traditional REST endpoints
+* **[Metadata API](./docs/api/README.md#metadata-api)** - Runtime schema discovery and introspection
+* **[Authentication Guide](./docs/api/authentication.md)** - Securing your APIs with JWT, API keys, and more
+
+**Quick Example:**
+```bash
+# Create a record via JSON-RPC
+curl -X POST http://localhost:3000/api/objectql \
+  -H "Content-Type: application/json" \
+  -d '{
+    "op": "create",
+    "object": "tasks",
+    "args": {
+      "name": "Complete API documentation",
+      "priority": "high"
+    }
+  }'
+```
+
+See the [API Reference](./docs/api/README.md) for complete documentation with examples.
+
 ## 🛣 Roadmap
 
 * [ ] **Phase 1: Core Protocol:** Define stable `UnifiedQuery` types and AST parser.

docs/.vitepress/config.mts

@@ -17,10 +17,24 @@ export default defineConfig({
       { text: 'Guide', link: '/guide/' },
       { text: 'AI-Native', link: '/ai/' },
       { text: 'Protocol', link: '/spec/' },
+      { text: 'API Reference', link: '/api/' },
     ],
 
     // Sidebar Configuration
     sidebar: {
+      // Sidebar for API section
+      '/api/': [
+        {
+          text: 'API Reference',
+          items: [
+            { text: 'Overview', link: '/api/' },
+            { text: 'Quick Reference', link: '/api/quick-reference' },
+            { text: 'Authentication', link: '/api/authentication' },
+            { text: 'Full Specification', link: '/api/README' },
+          ]
+        }
+      ],
+
       // Sidebar for AI section
       '/ai/': [
          {