Skip to content

Commit 26dcafc

Browse files
hotlongCopilot
andcommitted
docs(README): align with current package inventory and CLI
- Add missing core packages: @objectstack/formula, @objectstack/platform-objects - Add missing driver: @objectstack/driver-mongodb - Add missing plugins: plugin-sharing, plugin-approvals, plugin-email, plugin-webhooks, plugin-reports - Add missing services: service-cloud, service-settings - Remove non-existent plugin-setup - Promote @objectstack/objectos, @objectstack/cloud, @objectstack/console and @objectstack/account to the Tools & Apps section (they are real apps, not examples) - Update Quick Start to use `npx create-objectstack` and `pnpm dev` instead of the non-existent `npx @objectstack/cli init` and `os studio` flow - Update Monorepo Scripts to reflect actual scripts in root package.json (no `pnpm studio`; add `dev:cloud`, `dev:crm`, `studio:start`) - Expand CLI Commands to cover create / start / lint / explain plus the cloud / projects / publish family - Replace stale `Packages | 42` metric with 51 source packages and add apps / adapters / drivers counts - Link the north-star concept doc next to ARCHITECTURE.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 4d2067a commit 26dcafc

1 file changed

Lines changed: 51 additions & 27 deletions

File tree

README.md

Lines changed: 51 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ ObjectStack is built around three protocol layers:
2828

2929
All core definitions start with **Zod schemas** (1,600+ exported schemas across 200 schema files). TypeScript types, JSON Schemas, REST routes, UI metadata, and agent tools are derived from the same source of truth.
3030

31-
See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full microkernel and layer architecture documentation.
31+
See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full microkernel and layer architecture documentation, and [content/docs/concepts/north-star.mdx](./content/docs/concepts/north-star.mdx) for the product north star (Studio · Org/Project/Branch · per-project ObjectOS · compiled app artifacts).
3232

3333
## Key Features
3434

@@ -70,18 +70,17 @@ This makes ObjectStack a backend substrate for AI-native business applications:
7070

7171
```bash
7272
# Create a new project
73-
npx @objectstack/cli init my-app
73+
npx create-objectstack my-app
7474
cd my-app
7575

76-
# Start development server
77-
os dev
78-
79-
# Open Studio IDE
80-
os studio
76+
# Start dev server (REST API + Studio IDE)
77+
pnpm dev
8178
# → API: http://localhost:3000/api/v1/
8279
# → Studio: http://localhost:3000/_studio/
8380
```
8481

82+
Alternatively, with the CLI installed: `os init my-app && cd my-app && os dev`.
83+
8584
### For Framework Contributors
8685

8786
```bash
@@ -106,28 +105,38 @@ pnpm docs:dev
106105
| Script | Description |
107106
| :--- | :--- |
108107
| `pnpm build` | Build all packages (excludes docs) |
109-
| `pnpm dev` | Start development server |
110-
| `pnpm studio` | Launch Studio IDE with dev server |
111-
| `pnpm test` | Run all tests |
108+
| `pnpm dev` | Run the reference `@objectstack/objectos` host in dev mode |
109+
| `pnpm dev:cloud` | Run `@objectstack/cloud` (multi-project, control-plane mode) |
110+
| `pnpm dev:crm` | Run the CRM example end-to-end (`@example/app-crm`) |
111+
| `pnpm studio:start` | Start the prebuilt Studio IDE |
112+
| `pnpm test` | Run all tests (Turborepo) |
112113
| `pnpm doctor` | Check environment health |
113-
| `pnpm setup` | Install dependencies and build spec |
114-
| `pnpm docs:dev` | Start documentation site locally |
114+
| `pnpm setup` | Install dependencies and build the spec package |
115+
| `pnpm docs:dev` | Start the documentation site locally |
115116
| `pnpm docs:build` | Build documentation for production |
116117

117118
## CLI Commands
118119

120+
The CLI binary ships as both `os` and `objectstack`.
121+
119122
```bash
120123
os init [name] # Scaffold a new project
121-
os dev # Start dev server with hot-reload
122-
os studio # Start dev server + Studio IDE
123-
os serve # Start production server
124-
os compile # Build deployable JSON artifact
125-
os validate # Validate configuration against protocol
126-
os info # Display metadata summary
127-
os generate # Scaffold objects, views, and flows
124+
os create # Interactive project / object scaffolder
125+
os dev # Start dev server with hot-reload (REST + Studio)
126+
os studio # Open the Studio IDE
127+
os start # Start the production server
128+
os serve # Serve a compiled artifact
129+
os compile # Build a deployable JSON Project Artifact
130+
os validate # Validate metadata against the protocol
131+
os lint # Lint metadata for best-practice violations
132+
os info # Display project metadata summary
133+
os generate # Scaffold objects, views, flows, agents, migrations
128134
os doctor # Check environment health
135+
os explain # Explain protocol concepts on the command line
129136
```
130137

138+
Cloud, package registry, and project management subcommands (`os projects`, `os publish`, `os login`, `os whoami`, `os cloud …`) are available when targeting an ObjectStack Cloud control plane.
139+
131140
## Package Directory
132141

133142
### Core
@@ -137,6 +146,8 @@ os doctor # Check environment health
137146
| [`@objectstack/spec`](packages/spec) | Protocol definitions — Zod schemas, TypeScript types, JSON Schemas, constants |
138147
| [`@objectstack/core`](packages/core) | Microkernel runtime — Plugin system, DI container, EventBus, Logger |
139148
| [`@objectstack/types`](packages/types) | Shared TypeScript type utilities |
149+
| [`@objectstack/formula`](packages/formula) | Canonical expression engine — CEL (cel-js) + ObjectStack stdlib for formula fields, predicates, conditions, dynamic defaults |
150+
| [`@objectstack/platform-objects`](packages/platform-objects) | Built-in platform object schemas — identity, security, audit, tenant |
140151

141152
### Engine
142153

@@ -153,7 +164,8 @@ os doctor # Check environment health
153164
| :--- | :--- |
154165
| [`@objectstack/driver-memory`](packages/plugins/driver-memory) | In-memory driver (development and testing) |
155166
| [`@objectstack/driver-sql`](packages/plugins/driver-sql) | SQL driver — PostgreSQL, MySQL, SQLite (production) |
156-
| [`@objectstack/driver-turso`](packages/plugins/driver-turso) | Turso/libSQL driver |
167+
| [`@objectstack/driver-turso`](packages/plugins/driver-turso) | Turso / libSQL driver |
168+
| [`@objectstack/driver-mongodb`](packages/plugins/driver-mongodb) | MongoDB driver (native document database) |
157169

158170
### Client
159171

@@ -168,12 +180,16 @@ os doctor # Check environment health
168180
| :--- | :--- |
169181
| [`@objectstack/plugin-hono-server`](packages/plugins/plugin-hono-server) | Hono-based HTTP server plugin |
170182
| [`@objectstack/plugin-mcp-server`](packages/plugins/plugin-mcp-server) | Model Context Protocol server — exposes ObjectStack to AI agents |
171-
| [`@objectstack/plugin-msw`](packages/plugins/plugin-msw) | Mock Service Worker plugin for browser testing |
172183
| [`@objectstack/plugin-auth`](packages/plugins/plugin-auth) | Authentication plugin (better-auth) |
173184
| [`@objectstack/plugin-security`](packages/plugins/plugin-security) | RBAC, Row-Level Security, Field-Level Security |
174-
| [`@objectstack/plugin-dev`](packages/plugins/plugin-dev) | Developer mode — in-memory stubs for all services |
185+
| [`@objectstack/plugin-sharing`](packages/plugins/plugin-sharing) | Record-level sharing — `sys_record_share` + enforcement middleware |
186+
| [`@objectstack/plugin-approvals`](packages/plugins/plugin-approvals) | Multi-step approval engine — `sys_approval_process` + `sys_approval_request` |
175187
| [`@objectstack/plugin-audit`](packages/plugins/plugin-audit) | Audit logging plugin |
176-
| [`@objectstack/plugin-setup`](packages/plugins/plugin-setup) | First-run setup wizard |
188+
| [`@objectstack/plugin-email`](packages/plugins/plugin-email) | Pluggable outbound email transport |
189+
| [`@objectstack/plugin-webhooks`](packages/plugins/plugin-webhooks) | Outbound webhook delivery — fan-out `data.record.*` events |
190+
| [`@objectstack/plugin-reports`](packages/plugins/plugin-reports) | Saved reports + scheduled email digests |
191+
| [`@objectstack/plugin-dev`](packages/plugins/plugin-dev) | Developer mode — in-memory stubs for all services |
192+
| [`@objectstack/plugin-msw`](packages/plugins/plugin-msw) | Mock Service Worker plugin for browser testing |
177193

178194
### Services
179195

@@ -183,12 +199,14 @@ os doctor # Check environment health
183199
| [`@objectstack/service-analytics`](packages/services/service-analytics) | Analytics — aggregations, time series, funnels, dashboards |
184200
| [`@objectstack/service-automation`](packages/services/service-automation) | Automation engine — flows, triggers, DAG-based workflows |
185201
| [`@objectstack/service-cache`](packages/services/service-cache) | Cache — in-memory, Redis, multi-tier |
202+
| [`@objectstack/service-cloud`](packages/services/service-cloud) | Cloud orchestration — multi-project, control-plane, deployment |
186203
| [`@objectstack/service-feed`](packages/services/service-feed) | Activity feed / chatter |
187204
| [`@objectstack/service-i18n`](packages/services/service-i18n) | Internationalization service |
188205
| [`@objectstack/service-job`](packages/services/service-job) | Cron & interval job scheduler |
189206
| [`@objectstack/service-package`](packages/services/service-package) | Package registry — publish, version, retrieve metadata packages |
190207
| [`@objectstack/service-queue`](packages/services/service-queue) | Background job queue (in-memory, BullMQ) |
191208
| [`@objectstack/service-realtime`](packages/services/service-realtime) | Real-time events and subscriptions |
209+
| [`@objectstack/service-settings`](packages/services/service-settings) | Settings — manifest registry + K/V resolver (Env > Tenant > User) |
192210
| [`@objectstack/service-storage`](packages/services/service-storage) | File storage (local, S3, R2, GCS) |
193211
| [`@objectstack/service-tenant`](packages/services/service-tenant) | Multi-tenant context and routing |
194212

@@ -206,12 +224,16 @@ os doctor # Check environment health
206224

207225
### Tools & Apps
208226

209-
| Package | Description |
227+
| Package / App | Description |
210228
| :--- | :--- |
211-
| [`@objectstack/cli`](packages/cli) | CLI — `init`, `dev`, `serve`, `studio`, `compile`, `validate`, `generate` |
229+
| [`@objectstack/cli`](packages/cli) | CLI binary (`os` / `objectstack`) `init`, `dev`, `serve`, `studio`, `compile`, `validate`, `generate`, `lint`, `doctor` |
212230
| [`create-objectstack`](packages/create-objectstack) | Project scaffolder (`npx create-objectstack`) |
213231
| [`objectstack-vscode`](packages/vscode-objectstack) | VS Code extension — autocomplete, validation, diagnostics |
232+
| [`@objectstack/objectos`](apps/objectos) | Reference host — local and self-contained ObjectOS runtime |
233+
| [`@objectstack/cloud`](apps/cloud) | Cloud host — multi-project, control-plane connected, deployable to Vercel / Workers |
214234
| [`@objectstack/studio`](apps/studio) | Studio IDE — metadata explorer, schema inspector, AI assistant |
235+
| [`@objectstack/console`](apps/console) | Cloud console — org / project / branch management UI |
236+
| [`@objectstack/account`](apps/account) | Account & identity portal — sign in, organizations, connected apps |
215237
| [`@objectstack/docs`](apps/docs) | Documentation site (Fumadocs + Next.js) |
216238

217239
### Examples
@@ -220,13 +242,15 @@ os doctor # Check environment health
220242
| :--- | :--- | :--- |
221243
| [`@example/app-todo`](examples/app-todo) | Task management app — objects, views, dashboards, flows | Beginner |
222244
| [`@example/app-crm`](examples/app-crm) | Enterprise CRM — accounts, contacts, opportunities, leads | Intermediate |
223-
| [`@objectstack/objectos`](apps/objectos) | ObjectOS Runtime — multi-app orchestration with plugins | Advanced |
224245

225246
## Codebase Metrics
226247

227248
| Metric | Value |
228249
| :--- | :--- |
229-
| Packages | 42 |
250+
| Source packages | 51 |
251+
| Apps | 6 (objectos, cloud, studio, console, account, docs) |
252+
| Framework adapters | 7 (Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit) |
253+
| Database drivers | 4 (Memory, SQL, Turso/libSQL, MongoDB) |
230254
| Zod schema files | 200 |
231255
| Exported schemas | 1,600+ |
232256
| `.describe()` annotations | 8,750+ |

0 commit comments

Comments
 (0)