Skip to content

Commit 5da8b7a

Browse files
hotlonghotlong
authored
Merge pull request #646 from objectstack-ai/copilot/update-road-map-improvements
2 parents 3564bca + 4a55d38 commit 5da8b7a

5 files changed

Lines changed: 226 additions & 93 deletions

File tree

‎DX_ROADMAP.md‎

Lines changed: 108 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
> **Date:** 2026-02-12
44
> **Scope:** Post v3.0 — Focused entirely on Developer Experience
5-
> **Based On:** Full codebase scan + documentation audit (171 schemas, 191 test files, 40+ doc pages, 4 examples, 19 packages)
5+
> **Based On:** Full codebase audit — 171 schemas, 194 test files (5,243 tests), 150+ doc pages, 4 examples, 19 packages, 12 subpath exports
66
> **Previous:** `ROADMAP.md` (v3.0 Phases 5–11 ✅ Complete)
77
88
---
@@ -13,20 +13,35 @@ ObjectStack v3.0 delivered a production-grade protocol spec with comprehensive t
1313

1414
This roadmap prioritizes improvements based on the **"Time to First Wow"** metric: how quickly a new developer goes from `npm init` to a running application with data, UI, and API.
1515

16-
### Current DX Assessment
16+
### Current DX Assessment (Feb 2026 Audit)
1717

1818
| Area | Score | Notes |
1919
|------|-------|-------|
20-
| **Type Safety** | ⭐⭐⭐⭐⭐ | Zod-first, 7,095+ `.describe()`, full inference |
21-
| **Schema Completeness** | ⭐⭐⭐⭐⭐ | 171 schemas, 1,470 JSON Schemas, OpenAPI 3.1 |
22-
| **Test Coverage** | ⭐⭐⭐⭐⭐ | 191 test files, 5,157+ tests |
23-
| **IDE Autocomplete** | ⭐⭐⭐⭐ | Bundled `objectstack.json`, `.describe()` tooltips |
24-
| **Getting Started** | ⭐⭐⭐ | Docs exist but no interactive playground |
25-
| **Error Messages** | ⭐⭐⭐⭐ | Custom error map with contextual messages and "Did you mean?" suggestions |
26-
| **Helper Functions** | ⭐⭐⭐⭐ | `Field.*`, `ObjectSchema.create()`, `defineStack()`, `defineView()`, `defineApp()`, `defineFlow()`, `defineAgent()` + strict mode |
27-
| **Reference Docs** | ⭐⭐⭐ | API docs generated but no field type gallery or error code reference |
28-
| **Examples** | ⭐⭐⭐ | 4 examples but missing "How to Run" instructions |
29-
| **Migration Story** | ⭐⭐ | V3 guide exists but no automated `codemod` tooling |
20+
| **Type Safety** | ⭐⭐⭐⭐⭐ | Zod v4 first, 7,095+ `.describe()`, full inference, branded types |
21+
| **Schema Completeness** | ⭐⭐⭐⭐⭐ | 171 schemas, 1,470 JSON Schemas, OpenAPI 3.1, bundled `objectstack.json` |
22+
| **Test Coverage** | ⭐⭐⭐⭐⭐ | 194 test files (5,243 tests), 100%+ schema coverage |
23+
| **IDE Autocomplete** | ⭐⭐⭐⭐ | Bundled `objectstack.json`, `.describe()` tooltips, 12 subpath exports |
24+
| **Error Messages** | ⭐⭐⭐⭐⭐ | Custom Zod v4 error map, "Did you mean?" fuzzy suggestions, `safeParsePretty()` |
25+
| **Helper Functions** | ⭐⭐⭐⭐⭐ | 6 `define*` helpers + `ObjectSchema.create()` + `Field.*` + strict `defineStack()` |
26+
| **Getting Started** | ⭐⭐⭐ | Docs exist but no interactive playground or `create-objectstack` wizard |
27+
| **Reference Docs** | ⭐⭐⭐⭐ | Field type gallery ✅, error catalog ✅, query cheat sheet ✅; still missing: Contracts docs, wire format examples |
28+
| **Examples** | ⭐⭐⭐ | 4 examples but `plugin-bi` is placeholder, "How to Run" incomplete, `examples/README.md` references non-existent `minimal-auth` |
29+
| **Migration Story** | ⭐⭐⭐ | V3 migration guide exists; no automated `codemod` tooling |
30+
31+
### Audit Findings Summary (New Issues Discovered)
32+
33+
| # | Finding | Severity | Location |
34+
|---|---------|----------|----------|
35+
| 1 | `examples/README.md` references non-existent `minimal-auth` example | 🔴 Critical | `examples/README.md` L31-63 |
36+
| 2 | `plugin-bi` has NO README, NO scripts, placeholder-only code | 🔴 Critical | `examples/plugin-bi/` |
37+
| 3 | `examples/README.md` says "Total Examples: 3" — should be 4 | 🟡 Medium | `examples/README.md` L379 |
38+
| 4 | `examples/README.md` says "Protocol Version: 0.6.1" — should be 3.0.0 | 🟡 Medium | `examples/README.md` L378 |
39+
| 5 | Contracts docs section is empty (`pages: []`) | 🟡 Medium | `content/docs/references/contracts/meta.json` |
40+
| 6 | `app-todo` Quick Start lacks dev/serve instructions | 🟡 Medium | `examples/app-todo/README.md` |
41+
| 7 | `app-crm` Quick Start lacks port/output details | 🟡 Medium | `examples/app-crm/README.md` |
42+
| 8 | `app-host` README uses `npm run dev` instead of `pnpm dev` | 🟡 Medium | `examples/app-host/README.md` |
43+
| 9 | `defineStudioPlugin` not re-exported at root index.ts (unlike other `define*` helpers) | 🟢 Low | `packages/spec/src/index.ts` |
44+
| 10 | Some root-level schema objects missing `.describe()` (only properties annotated) | 🟢 Low | Various `.zod.ts` files |
3045

3146
---
3247

@@ -61,15 +76,27 @@ This roadmap prioritizes improvements based on the **"Time to First Wow"** metri
6176
| Template: Full-Stack | Server + UI + auth + 3 objects (CRM-lite) | 🟡 Medium |
6277
| Template: Plugin | Bare plugin skeleton with test setup | 🟡 Medium |
6378

79+
### 1.4 Examples Catalog Hygiene (NEW — Audit Finding)
80+
81+
| Task | Details | Priority |
82+
|------|---------|----------|
83+
| Remove `minimal-auth` ghost reference | `examples/README.md` references non-existent `minimal-auth` directory — remove or create it | 🔴 High |
84+
| Fix `plugin-bi` example | Add README.md, add build/typecheck scripts, implement BI objects or mark as stub | 🔴 High |
85+
| Update `examples/README.md` metadata | Protocol Version 0.6.1 → 3.0.0, Total Examples 3 → 4, Last Updated date | 🟡 Medium |
86+
| Fix `app-host` README | Use `pnpm dev` instead of `npm run dev` | 🟡 Medium |
87+
6488
### Phase 1 Checklist
6589

6690
- [ ] Create StackBlitz starter template from `app-todo`
6791
- [ ] Add "Try Online" button to spec README.md and docs site hero
68-
- [ ] Add "How to Run" section to each example README (app-todo, app-crm, app-host)
92+
- [ ] Add "How to Run" section to each example README (app-todo, app-crm, app-host, plugin-bi)
6993
- [ ] Add prerequisites section to getting-started docs
7094
- [ ] Create first-run troubleshooting page
7195
- [ ] Implement `create-objectstack` CLI wizard with 3 templates
7296
- [ ] Record 5-minute getting-started video
97+
- [ ] Fix `examples/README.md`: remove `minimal-auth` ghost reference, update metadata (version, count, date)
98+
- [ ] Fix `plugin-bi` example: add README.md, add package.json scripts, document purpose
99+
- [ ] Fix `app-host` README: use `pnpm dev` instead of `npm run dev`
73100

74101
---
75102

@@ -126,40 +153,48 @@ This roadmap prioritizes improvements based on the **"Time to First Wow"** metri
126153
127154
### 3.1 Field Type Gallery
128155

129-
| Task | Details | Priority |
130-
|------|---------|----------|
131-
| Visual field type reference | Interactive page showing all 46+ field types with live previews | 🔴 High |
132-
| Field configuration reference | Per-type property tables (text: maxLength, pattern; number: min, max, precision) | 🔴 High |
133-
| Field type decision tree | "Which field type should I use?" interactive guide | 🟡 Medium |
134-
| Field validation rules per type | Default validation behavior for each field type | 🟡 Medium |
156+
| Task | Details | Priority | Status |
157+
|------|---------|----------|--------|
158+
| Visual field type reference | Interactive page showing all 48 field types with live previews | 🔴 High | ✅ Done |
159+
| Field configuration reference | Per-type property tables (text: maxLength, pattern; number: min, max, precision) | 🔴 High | ✅ Done |
160+
| Field type decision tree | "Which field type should I use?" interactive guide | 🟡 Medium | ❌ Not started |
161+
| Field validation rules per type | Default validation behavior for each field type | 🟡 Medium | ❌ Not started |
135162

136163
### 3.2 Error & Status Code Reference
137164

138-
| Task | Details | Priority |
139-
|------|---------|----------|
140-
| Error code catalog | All 46 error codes with descriptions, causes, and fixes | 🔴 High |
141-
| HTTP status mapping table | Error category → HTTP status → retry strategy | 🟡 Medium |
142-
| Client-side error handling guide | Patterns for handling errors in React/Vue/vanilla JS | 🟡 Medium |
143-
| Server-side error handling guide | How to throw and format errors from plugins | 🟡 Medium |
165+
| Task | Details | Priority | Status |
166+
|------|---------|----------|--------|
167+
| Error code catalog | All 41+ error codes with descriptions, causes, and fixes | 🔴 High | ✅ Done |
168+
| HTTP status mapping table | Error category → HTTP status → retry strategy | 🟡 Medium | ✅ Done |
169+
| Client-side error handling guide | Patterns for handling errors in React/Vue/vanilla JS | 🟡 Medium | ❌ Not started |
170+
| Server-side error handling guide | How to throw and format errors from plugins | 🟡 Medium | ❌ Not started |
144171

145172
### 3.3 Protocol Documentation
146173

147-
| Task | Details | Priority |
148-
|------|---------|----------|
149-
| Protocol relationship diagram | Visual diagram showing how Data → API → UI layers connect | 🔴 High |
150-
| Query syntax cheat sheet | One-page reference for QuerySchema filters, sorts, pagination | 🔴 High |
151-
| Wire format examples | JSON request/response examples for every API endpoint | 🟡 Medium |
152-
| Security permissions matrix | Object × Role × Permission visual table | 🟡 Medium |
153-
| Backward compatibility policy | Versioning strategy, deprecation timeline, SemVer guarantees | 🟡 Medium |
174+
| Task | Details | Priority | Status |
175+
|------|---------|----------|--------|
176+
| Protocol relationship diagram | Visual diagram showing how Data → API → UI layers connect | 🔴 High | ❌ Not started |
177+
| Query syntax cheat sheet | One-page reference for QuerySchema filters, sorts, pagination | 🔴 High | ✅ Done |
178+
| Wire format examples | JSON request/response examples for every API endpoint | 🟡 Medium | ❌ Not started |
179+
| Security permissions matrix | Object × Role × Permission visual table | 🟡 Medium | ❌ Not started |
180+
| Backward compatibility policy | Versioning strategy, deprecation timeline, SemVer guarantees | 🟡 Medium | ❌ Not started |
154181

155182
### 3.4 Guide Improvements
156183

184+
| Task | Details | Priority | Status |
185+
|------|---------|----------|--------|
186+
| Common patterns guide | Top 10 patterns: CRUD, search, pagination, auth, file upload, realtime, etc. | 🔴 High | ✅ Done |
187+
| Troubleshooting / FAQ page | "My query returns empty" / "Validation fails but data looks correct" | 🟡 Medium | ✅ Done |
188+
| Data flow diagram guide | How data moves from defineStack → kernel → driver → database | 🟡 Medium | ❌ Not started |
189+
| Plugin development tutorial | Step-by-step: create a plugin, register services, respond to hooks | 🟡 Medium | ✅ Done |
190+
191+
### 3.5 Missing Documentation Sections (NEW — Audit Finding)
192+
157193
| Task | Details | Priority |
158194
|------|---------|----------|
159-
| Common patterns guide | Top 10 patterns: CRUD, search, pagination, auth, file upload, realtime, etc. | 🔴 High |
160-
| Troubleshooting / FAQ page | "My query returns empty" / "Validation fails but data looks correct" | 🟡 Medium |
161-
| Data flow diagram guide | How data moves from defineStack → kernel → driver → database | 🟡 Medium |
162-
| Plugin development tutorial | Step-by-step: create a plugin, register services, respond to hooks | 🟡 Medium |
195+
| Populate Contracts docs | `content/docs/references/contracts/meta.json` has `pages: []` — add pages documenting IMetadataService, IAuthService, IStorageService, etc. | 🔴 High |
196+
| Add `defineStudioPlugin` guide | Only `define*` helper not documented at guide level; add usage example to plugin-development guide | 🟡 Medium |
197+
| Error handling guides (client + server) | Best practice patterns for both client-side and server-side error handling | 🟡 Medium |
163198

164199
### Phase 3 Checklist
165200

@@ -173,6 +208,12 @@ This roadmap prioritizes improvements based on the **"Time to First Wow"** metri
173208
- [x] Create common patterns guide (top 10 patterns)
174209
- [x] Create troubleshooting / FAQ page
175210
- [x] Create plugin development tutorial
211+
- [ ] Populate Contracts docs section (currently empty)
212+
- [ ] Add field type decision tree ("Which field type?")
213+
- [ ] Add client-side error handling guide
214+
- [ ] Add server-side error handling guide
215+
- [ ] Add data flow diagram guide (defineStack → kernel → driver → DB)
216+
- [ ] Add security permissions matrix
176217

177218
---
178219

@@ -209,6 +250,14 @@ This roadmap prioritizes improvements based on the **"Time to First Wow"** metri
209250
| `objectstack generate migration` | Database migration from object diff | 🟡 Medium |
210251
| `objectstack generate seed` | Generate seed data from object schemas | 🟢 Low |
211252

253+
### 4.4 Codemod & Migration Tooling (NEW)
254+
255+
| Task | Details | Priority |
256+
|------|---------|----------|
257+
| `objectstack codemod v2-to-v3` | Automated AST transform for v2 → v3 breaking changes (removed fields, renames) | 🟡 Medium |
258+
| Deprecation scanner | CLI command to detect usage of `@deprecated` items with suggested replacements | 🟡 Medium |
259+
| Config validator | Deep validation of `objectstack.config.ts` with cross-reference checks (uses existing `defineStack({ strict: true })`) | 🟡 Medium |
260+
212261
### Phase 4 Checklist
213262

214263
- [ ] Implement `objectstack diff` with breaking change detection
@@ -219,6 +268,8 @@ This roadmap prioritizes improvements based on the **"Time to First Wow"** metri
219268
- [ ] Add JSON Schema for `objectstack.config.ts` IDE support
220269
- [ ] Implement `objectstack generate client` for typed SDK generation
221270
- [ ] Implement `objectstack generate migration` for schema diffs
271+
- [ ] Implement `objectstack codemod v2-to-v3` for automated migration
272+
- [ ] Add deprecation scanner to CLI
222273

223274
---
224275

@@ -310,13 +361,16 @@ This roadmap prioritizes improvements based on the **"Time to First Wow"** metri
310361
## Timeline Summary
311362

312363
```
313-
2026 Q1–Q2 (DX Sprint)
314-
├── Phase 1: First Five Minutes [2 weeks] → Playground, scaffolding, quick-start
315-
├── Phase 2: Schema DX Helpers [2 weeks] → Factories, error messages, types
316-
└── Phase 3: Documentation & Reference [3 weeks] → Field gallery, error catalog, guides
364+
2026 Q1 (Completed)
365+
├── Phase 2: Schema DX Helpers [2 weeks] ✅ Complete — 6 define* helpers, error map, branded types, strict mode
366+
└── Phase 3: Documentation & Reference [3 weeks] 🔄 In Progress — 10/16 items complete
367+
368+
2026 Q1–Q2 (Active)
369+
├── Phase 1: First Five Minutes [2 weeks] → Playground, scaffolding, quick-start, example fixes
370+
└── Phase 3: Documentation (cont.) [1 week] → Contracts docs, wire format, protocol diagram, decision tree
317371
318372
2026 Q2–Q3 (Tooling Sprint)
319-
├── Phase 4: CLI & Tooling DX [2 weeks] → diff, doctor, lint, VSCode extension
373+
├── Phase 4: CLI & Tooling DX [2 weeks] → diff, doctor, lint, VSCode extension, codemod
320374
└── Phase 5: Studio as DX Hub [3 weeks] → Visual designer, code bridge
321375
322376
2026 Q3+ (Ecosystem Sprint)
@@ -327,24 +381,26 @@ This roadmap prioritizes improvements based on the **"Time to First Wow"** metri
327381

328382
| Impact ↓ / Effort → | Low (< 1 week) | Medium (1–2 weeks) | High (> 2 weeks) |
329383
|---------------------|-----------------|---------------------|-------------------|
330-
| **High Impact** | StackBlitz template, "How to Run" docs, Prerequisites check | `create-objectstack` wizard, Custom error map, Field type gallery | VSCode extension, Visual object builder |
331-
| **Medium Impact** | Query cheat sheet, Error code catalog, Export grouping comments | `objectstack diff`, `objectstack doctor`, Common patterns guide | Plugin marketplace, Live file sync |
332-
| **Lower Impact** | Branded types, Contributor page, Example ratings | Plugin starter template, Mock data generator | Diagnostic language server, Auto-migration |
384+
| **High Impact** | Fix examples README (ghost ref, metadata), StackBlitz template, "How to Run" docs | `create-objectstack` wizard, Contracts docs, Protocol diagram | VSCode extension, Visual object builder |
385+
| **Medium Impact** | Fix `plugin-bi` (README + scripts), `app-host` README fix, Field decision tree | `objectstack diff`, `objectstack doctor`, Wire format examples, Codemod tooling | Plugin marketplace, Live file sync |
386+
| **Lower Impact** | `defineStudioPlugin` root re-export, Schema-level `.describe()` | Plugin starter template, Mock data generator, Security matrix | Diagnostic language server, Auto-migration |
333387

334388
---
335389

336390
## Success Criteria
337391

338-
| Metric | Current | Phase 1 | Phase 3 | Phase 6 |
339-
|--------|---------|---------|---------|---------|
392+
| Metric | v3.0 (Current) | Phase 1 | Phase 3 | Phase 6 |
393+
|--------|----------------|---------|---------|---------|
340394
| Time to First App | ~30 min | < 5 min | < 5 min | < 3 min |
341-
| Documentation coverage | ~60% | 70% | 95% | 100% |
395+
| Documentation coverage | ~70% | 80% | 95% | 100% |
342396
| Interactive examples | 0 | 1 (StackBlitz) | 3+ | 10+ |
343397
| Community plugins | 0 | 0 | 2+ | 10+ |
344398
| CLI diagnostic commands | 2 | 4 | 6 | 8+ |
345-
| IDE autocomplete coverage | JSON Schema | JSON Schema + hints | VSCode extension | Language server |
346-
| Error message quality | Zod defaults | Custom error map | Full catalog | AI-assisted |
347-
| Helper functions (`define*`) | 1 (`defineStack`) | 4+ | 6+ | 6+ |
399+
| IDE autocomplete coverage | JSON Schema + bundled | JSON Schema + hints | VSCode extension | Language server |
400+
| Error message quality | Custom Zod v4 error map + "Did you mean?" | Full catalog | Contextual guides | AI-assisted |
401+
| Helper functions (`define*`) | 6 (`defineStack/View/App/Flow/Agent/StudioPlugin`) | 6+ | 6+ | 8+ |
402+
| Test files / Tests | 194 / 5,243 | 194+ / 5,300+ | 200+ / 5,500+ | 210+ / 6,000+ |
403+
| Example quality | 3 working + 1 placeholder | 4 working + 1 scaffold | 6+ curated | 10+ |
348404
| GitHub stars | — | 50+ | 200+ | 500+ |
349405

350406
---
@@ -356,10 +412,10 @@ This roadmap prioritizes improvements based on the **"Time to First Wow"** metri
356412
| `ROADMAP.md` | v3.0 spec hardening (Phases 5–11) | ✅ Complete |
357413
| `apps/studio/ROADMAP.md` | Studio IDE visual features (Phases 0–8) | 🔄 Active |
358414
| `packages/spec/DEVELOPMENT_PLAN.md` | Spec schema audit (Phases 1–4) | ✅ Complete |
359-
| **`DX_ROADMAP.md` (this file)** | **Developer Experience & Adoption** | 🆕 Active |
415+
| **`DX_ROADMAP.md` (this file)** | **Developer Experience & Adoption** | 🔄 Active |
360416

361417
---
362418

363419
**Last Updated:** 2026-02-12
364420
**Maintainers:** ObjectStack Core Team
365-
**Status:** 🔄 Active — Phase 3 In Progress (8/10 items complete), Phase 4 Ready to Start
421+
**Status:** 🔄 Active — Phase 2 ✅ Complete, Phase 3 In Progress (10/16 items), Phase 1 & 4 Ready to Start

0 commit comments

Comments
 (0)