Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 22 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

![ObjectStack Protocol](https://img.shields.io/badge/ObjectStack-Protocol-black)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

> **The "Constitution" of the Post-SaaS Operating System.**

Expand Down Expand Up @@ -32,14 +32,14 @@ ObjectStack is a metadata-driven platform built on three foundational protocols:
- [Quick Reference](./content/docs/references/quick-reference.mdx) — Fast protocol lookup

- **Protocol References:**
- [Protocol Reference](./content/docs/references/) — All protocol specifications (139 Zod schemas)
- [Protocol Reference](./content/docs/references/) — All protocol specifications (175 Zod schemas)
- [ObjectQL](./content/docs/objectql/) — Data layer documentation
- [ObjectUI](./content/docs/objectui/) — UI layer documentation
- [ObjectOS](./content/docs/objectos/) — System layer documentation

- **Development:**
- [Developer Guide](./content/docs/developer/) — Tutorials and best practices
- [Package Reference](./content/docs/framework/packages.mdx) — All 15 packages
- [Package Reference](./content/docs/concepts/packages.mdx) — All 25 packages
- [Contributing Guide](./CONTRIBUTING.md) — How to contribute

## 🚀 Quick Start
Expand All @@ -64,7 +64,7 @@ os studio

```bash
# 1. Clone and install
git clone https://github.com/nicecui/spec.git
git clone https://github.com/objectstack-ai/spec.git
cd spec
pnpm install

Expand Down Expand Up @@ -127,6 +127,7 @@ os doctor # Check environment health
| [`@objectstack/objectql`](packages/objectql) | ObjectQL query engine and schema registry | 🟢 Active |
| [`@objectstack/runtime`](packages/runtime) | Runtime utilities, DriverPlugin, AppPlugin | 🟢 Active |
| [`@objectstack/metadata`](packages/metadata) | Metadata loading and persistence | 🟢 Active |
| [`@objectstack/rest`](packages/rest) | REST API Server — auto-generated endpoints from protocol | 🟢 Active |

### Client Packages

Expand All @@ -142,13 +143,29 @@ os doctor # Check environment health
| [`@objectstack/driver-memory`](packages/plugins/driver-memory) | In-memory driver (reference implementation, zero deps) | 🟢 Active |
| [`@objectstack/plugin-hono-server`](packages/plugins/plugin-hono-server) | HTTP server plugin (Hono-based, auto-discovery) | 🟢 Active |
| [`@objectstack/plugin-msw`](packages/plugins/plugin-msw) | Mock Service Worker plugin for browser testing | 🟢 Active |
| [`@objectstack/plugin-auth`](packages/plugins/plugin-auth) | Authentication & identity plugin (structure implemented) | 🟡 In Development |
| [`@objectstack/plugin-auth`](packages/plugins/plugin-auth) | Authentication & identity plugin (better-auth based) | 🟡 In Development |
| [`@objectstack/plugin-security`](packages/plugins/plugin-security) | RBAC, Row-Level Security, and Field-Level Security | 🟢 Active |
| [`@objectstack/plugin-dev`](packages/plugins/plugin-dev) | Dev mode — auto-enables all services with in-memory stubs | 🟢 Active |

### Framework Adapters

| Package | Description | Status |
| :--- | :--- | :--- |
| [`@objectstack/express`](packages/adapters/express) | Express adapter | 🟢 Active |
| [`@objectstack/fastify`](packages/adapters/fastify) | Fastify adapter | 🟢 Active |
| [`@objectstack/hono`](packages/adapters/hono) | Hono adapter (Node.js, Bun, Deno, Cloudflare Workers) | 🟢 Active |
| [`@objectstack/nestjs`](packages/adapters/nestjs) | NestJS module integration | 🟢 Active |
| [`@objectstack/nextjs`](packages/adapters/nextjs) | Next.js App Router adapter | 🟢 Active |
| [`@objectstack/nuxt`](packages/adapters/nuxt) | Nuxt adapter (h3-based) | 🟢 Active |
| [`@objectstack/sveltekit`](packages/adapters/sveltekit) | SvelteKit adapter | 🟢 Active |

### Tools & Apps

| Package | Description | Status |
| :--- | :--- | :--- |
| [`@objectstack/cli`](packages/cli) | CLI: init, dev, serve, studio, compile, validate, generate | 🟢 Active |
| [`create-objectstack`](packages/create-objectstack) | Project scaffolder (`npx create-objectstack`) | 🟢 Active |
| [`objectstack-vscode`](packages/vscode-objectstack) | VSCode extension — autocomplete, validation, diagnostics | 🟢 Active |
| [`@objectstack/studio`](apps/studio) | Studio UI (Object Explorer, Schema Inspector) | 🟢 Active |
| [`@objectstack/docs`](apps/docs) | Documentation site (Fumadocs + Next.js) | 🟢 Active |

Expand Down
225 changes: 207 additions & 18 deletions content/docs/concepts/packages.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Complete reference of all ObjectStack packages in the monorepo

# Package Reference

ObjectStack is distributed as a monorepo containing **16 packages** organized into core packages, adapters, and plugins.
ObjectStack is distributed as a monorepo containing **25 packages** organized into core packages, adapters, and plugins.

> **Note for AI Agents**: Each package's `README.md` contains a specific "AI Development Context" section describing its architectural role and usage rules.

Expand All @@ -14,10 +14,11 @@ ObjectStack is distributed as a monorepo containing **16 packages** organized in
| Category | Count | Description |
| :--- | :---: | :--- |
| [Core Packages](#core-packages) | 9 | Essential runtime, protocols, client SDKs, and CLI |
| [Adapter Packages](#adapter-packages) | 3 | Framework adapters (Hono, NestJS, Next.js) |
| [Plugin Packages](#plugin-packages) | 4 | Drivers, server, and authentication plugins |
| [Framework Adapters](#framework-adapters) | 7 | Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit |
| [Plugin Packages](#plugin-packages) | 6 | Drivers, server, auth, security, dev, and MSW plugins |
| [Tools](#tools) | 3 | Project scaffolder, VSCode extension, REST API server |

**Total: 16 packages**
**Total: 25 packages**

---

Expand All @@ -42,7 +43,7 @@ ObjectStack is distributed as a monorepo containing **16 packages** organized in
- `Integration` - Integration protocol schemas
- `Shared` - Shared utilities and identifiers

**Protocol Count:** 139 Zod schemas
**Protocol Count:** 175 Zod schemas

**Learn more:** [Protocol Reference](/docs/references)

Expand Down Expand Up @@ -291,10 +292,40 @@ ObjectStack is distributed as a monorepo containing **16 packages** organized in

---

## Adapter Packages
## Framework Adapters

Framework adapters that bridge ObjectStack's unified `HttpDispatcher` to specific HTTP frameworks.

### @objectstack/express

**Description:** Express Framework Adapter

**Purpose:** Converts ObjectStack's standard HTTP dispatch interface to Express routes.

**Key Features:**
- Maps standard routes to Express handlers
- Supports Express v5 middleware chain
- Bearer token authentication via AuthPlugin

**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---

### @objectstack/fastify

**Description:** Fastify Framework Adapter

**Purpose:** Converts ObjectStack's standard HTTP dispatch interface to Fastify routes.

**Key Features:**
- Maps standard routes to Fastify handlers
- Supports Fastify v5 plugin system
- Bearer token authentication via AuthPlugin

**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---

### @objectstack/hono

**Description:** Hono Framework Adapter
Expand Down Expand Up @@ -334,9 +365,39 @@ Framework adapters that bridge ObjectStack's unified `HttpDispatcher` to specifi
**Key Features:**
- App Router integration
- API route handlers
- Server-side data access
- Server-side data access and server actions

**Implementation Status:** 🔄 **IN PROGRESS**
**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---

### @objectstack/nuxt

**Description:** Nuxt Framework Adapter

**Purpose:** Integrates ObjectStack with Nuxt server routes via h3.

**Key Features:**
- h3 event handler integration
- Nitro server route support
- Bearer token authentication via AuthPlugin

**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---

### @objectstack/sveltekit

**Description:** SvelteKit Framework Adapter

**Purpose:** Integrates ObjectStack with SvelteKit hooks and server routes.

**Key Features:**
- SvelteKit handle hook integration
- Server route handlers
- Bearer token authentication via AuthPlugin

**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---

Expand Down Expand Up @@ -428,22 +489,22 @@ Framework adapters that bridge ObjectStack's unified `HttpDispatcher` to specifi

**Description:** Authentication & Identity Plugin for ObjectStack

**Purpose:** Provides authentication and identity management services for ObjectStack applications with plugin structure ready for better-auth integration.
**Purpose:** Provides authentication and identity management services for ObjectStack applications with better-auth integration.

**Key Features:**
- **Plugin Lifecycle**: Full init/start/destroy lifecycle implementation
- **Service Registration**: Registers `auth` service in ObjectKernel
- **HTTP Route Scaffolding**: `/api/v1/auth/*` endpoints via IHttpServer
- **Configuration Support**: Uses `AuthConfig` schema from `@objectstack/spec/system`
- **OAuth Provider Support**: Configuration for Google, GitHub, Microsoft, etc.
- **Advanced Features**: Organization/team support, 2FA, passkeys, magic links (planned)
- **Session Management**: Configurable session expiry and refresh (planned)
- **ObjectQL Database**: Uses ObjectQL for data persistence (no ORM required)
- **Advanced Features**: Organization/team support, 2FA, passkeys, magic links

**API Routes:**
- `POST /api/v1/auth/login` - User login
- `POST /api/v1/auth/register` - User registration
- `POST /api/v1/auth/logout` - User logout
- `GET /api/v1/auth/session` - Get current session
- `POST /api/v1/auth/sign-in/email` - Sign in with email and password
- `POST /api/v1/auth/sign-up/email` - Register new user
- `POST /api/v1/auth/sign-out` - Sign out
- `GET /api/v1/auth/get-session` - Get current session

**Use Cases:**
- Adding authentication to ObjectStack applications
Expand All @@ -459,6 +520,122 @@ Framework adapters that bridge ObjectStack's unified `HttpDispatcher` to specifi

---

### @objectstack/plugin-security

**Description:** Security Plugin for ObjectStack — RBAC, RLS, and Field-Level Security Runtime

**Purpose:** Provides runtime security enforcement for ObjectStack applications, including role-based access control, row-level security, and field-level masking.

**Key Features:**
- **RBAC Permission Evaluator**: Checks object-level CRUD permissions per user role
- **Row-Level Security (RLS)**: Compiles policy expressions into ObjectQL query filters
- **Field-Level Masking**: Strips non-readable fields from query results
- **ObjectQL Middleware Integration**: Transparent security enforcement on every operation
- **Most-Permissive Merging**: If any role grants access, the operation is allowed

**Security Chain (4 steps):**
1. Resolve permission sets from user roles
2. Check CRUD permissions on objects
3. Inject RLS filters into queries
4. Mask restricted fields in results

**Use Cases:**
- Multi-tenant applications with role-based access
- Data isolation between teams/organizations
- Compliance requirements (field masking for sensitive data)

**Implementation Status:** ✅ **FULLY IMPLEMENTED** - Production ready

---

### @objectstack/plugin-dev

**Description:** Development Mode Plugin for ObjectStack

**Purpose:** Auto-enables all 17+ kernel services with in-memory implementations for a full-featured API development environment.

**Key Features:**
- **Zero Configuration**: Single plugin enables entire development stack
- **In-Memory Services**: All services use in-memory implementations
- **Full Protocol Support**: Auth, Data, Metadata, Storage, Analytics, and more
- **Hot Reload Compatible**: Works with `os dev` for hot-reload workflows

**Use Cases:**
- Rapid prototyping without database setup
- Local development and testing
- CI/CD pipeline testing

**Implementation Status:** ✅ **FULLY IMPLEMENTED** - Development ready

---

## Tools

### @objectstack/rest

**Description:** ObjectStack REST API Server — automatic REST endpoint generation from protocol

**Purpose:** Turns ObjectStack schema definitions into fully functional CRUD endpoints with zero boilerplate.

**Key Features:**
- **Auto-Generated Endpoints**: CRUD routes from object schemas
- **Batch Operations**: `/createMany`, `/updateMany`, `/deleteMany`, `/batch` endpoints
- **Metadata API**: `/meta`, `/meta/{type}`, `/meta/{type}/{name}` for runtime introspection
- **Discovery Endpoint**: `/api/v1` for API self-documentation
- **Route Manager**: Centralized route registration, grouping, and middleware chain
- **HTTP Caching**: ETag and Last-Modified header support
- **Configurable Paths**: Plural, kebab-case, and camelCase path transformations

**Use Cases:**
- Auto-generating REST APIs from metadata
- Building production API servers
- Custom route management

**Implementation Status:** ✅ **FULLY IMPLEMENTED** - Production ready

---

### create-objectstack

**Description:** Create a new ObjectStack project — `npx create-objectstack`

**Purpose:** Interactive project scaffolder for quickly creating new ObjectStack projects.

**Key Features:**
- **Interactive Mode**: Guided project setup with prompts
- **Template Support**: `full-stack`, `api-only`, `plugin` templates
- **Dependency Installation**: Automatic `pnpm install` (skippable)
- **Zero Config**: Works out-of-the-box with sensible defaults

**Use Cases:**
- Starting new ObjectStack projects
- Creating plugin packages
- Scaffolding from templates

**Implementation Status:** ✅ **FULLY IMPLEMENTED** - Production ready

---

### objectstack-vscode

**Description:** ObjectStack Protocol — Autocomplete, validation, and inline diagnostics for `.object.ts`, `.view.ts`, and `objectstack.config.ts` files

**Purpose:** VSCode extension providing IDE support for ObjectStack protocol development.

**Key Features:**
- **Autocomplete**: IntelliSense for ObjectStack schemas
- **Validation**: Real-time schema validation with error diagnostics
- **Protocol Awareness**: Understands `.object.ts`, `.view.ts`, and config files

**Use Cases:**
- ObjectStack development in VSCode
- Real-time feedback on schema definitions
- Productivity improvement

**Implementation Status:** ✅ **FULLY IMPLEMENTED**

---

## Package Dependencies

### Dependency Graph
Expand All @@ -473,19 +650,31 @@ Framework adapters that bridge ObjectStack's unified `HttpDispatcher` to specifi
│ ↓
│ └─→ @objectstack/runtime (uses objectql engine)
│ ↓
│ ├─→ @objectstack/rest (REST API generation)
│ ├─→ @objectstack/client (consumes runtime APIs)
│ │ ↓
│ │ └─→ @objectstack/client-react (wraps client)
│ └─→ Adapters:
│ ├─→ @objectstack/express (Express routes)
│ ├─→ @objectstack/fastify (Fastify routes)
│ ├─→ @objectstack/hono (Hono routes)
│ ├─→ @objectstack/nestjs (NestJS modules)
│ └─→ @objectstack/nextjs (Next.js routes)
│ ├─→ @objectstack/nextjs (Next.js routes)
│ ├─→ @objectstack/nuxt (Nuxt/h3 routes)
│ └─→ @objectstack/sveltekit (SvelteKit hooks)
└─→ @objectstack/cli (validates against spec schemas)

Plugins (depend on core packages):
├─→ @objectstack/driver-memory (implements driver interface)
├─→ @objectstack/plugin-hono-server (HTTP server via @objectstack/hono)
└─→ @objectstack/plugin-msw (mocks for testing via runtime)
├─→ @objectstack/plugin-msw (mocks for testing via runtime)
├─→ @objectstack/plugin-auth (authentication via better-auth)
├─→ @objectstack/plugin-security (RBAC, RLS, field masking)
└─→ @objectstack/plugin-dev (dev mode, all services in-memory)

Tools:
├─→ create-objectstack (project scaffolder)
└─→ objectstack-vscode (VSCode extension)
```

### Installation
Expand Down Expand Up @@ -534,7 +723,7 @@ All packages in the monorepo are versioned together and released simultaneously
<Card
href="/docs/references"
title="Protocol Reference"
description="Explore the 139 protocol schemas"
description="Explore the 175 protocol schemas"
/>
<Card
href="/docs/developers"
Expand Down
2 changes: 1 addition & 1 deletion content/docs/guides/cheatsheets/quick-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: Fast lookup table for all ObjectStack protocols

# Quick Reference Guide

Fast lookup for all 139 ObjectStack protocols organized by category.
Fast lookup for all 175 ObjectStack protocols organized by category.

<Callout type="info">
Click on any protocol name to view its complete API reference.
Expand Down
Loading