[WIP] Complete development of DX_ROADMAP.md by Copilot · Pull Request #648 · objectstack-ai/objectstack

Copilot · 2026-02-12T12:25:06Z

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

vercel · 2026-02-12T12:25:12Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-play	Error		Feb 12, 2026 3:33pm
spec	Error		Feb 12, 2026 3:33pm

…bility, defineStudioPlugin guide Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

- Add `objectstack diff` for comparing configs and detecting breaking changes - Add `objectstack lint` for style/convention checking (snake_case, labels) - Add `objectstack explain` for human-readable schema reference docs - Enhance `objectstack doctor` with circular deps, missing tests, deprecated usage, unused objects, orphan views - Register all new commands in bin.ts Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

…des/ Move 16 hand-written files (field-type-gallery, error-catalog, contracts docs, wire-format, permissions-matrix, etc.) from content/docs/references/ to content/docs/guides/ where they won't be destroyed by build-docs.ts. Remove 18 stale orphan files from references/ that don't match current source. Add auto-generation warnings to: - build-docs.ts header and generated file template - .cursorrules (documentation conventions section) - .cursorrules.d/objectstack.prompt.md Update all meta.json files for both guides/ and references/. Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

…or deprecation scanner commands Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

…4 DX - Create packages/vscode-objectstack/ with extension, snippets, hover docs - Create packages/spec/config-schema.json for IDE autocomplete - Add `generate schema` CLI sub-command to generate.ts - Update DX_ROADMAP.md Phase 4 checklist Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

…pePicker, RelationshipVisualizer, QueryBuilder, RequestHistory, CodeExporter, CodeImporter, LiveSyncStatus Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

…tion rules as complete Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot

Pull request overview

Completes multiple DX roadmap deliverables by adding new developer tooling (CLI + VS Code extension), expanding Studio DX components, and restructuring documentation so curated/hand-written content lives under content/docs/guides/ while content/docs/references/ remains auto-generated.

Changes:

Added a new VS Code extension package (packages/vscode-objectstack) with snippets, hover help, and basic config diagnostics.
Added new CLI commands (lint, diff, codemod v2-to-v3) and wired them into the main CLI.
Migrated/curated documentation from references/ into guides/, added Contracts docs, and reinforced the auto-generation boundary in build scripts and Cursor rules.

Reviewed changes

Copilot reviewed 66 out of 83 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
packages/vscode-objectstack/tsconfig.json	TypeScript build config for the new VS Code extension package.
packages/vscode-objectstack/src/extension.ts	Implements hover docs + basic diagnostics for ObjectStack files.
packages/vscode-objectstack/snippets/objectstack.json	Adds `os-*` snippets for ObjectStack objects/views/flows/agents/configs.
packages/vscode-objectstack/package.json	Declares extension activation events and contributions (languages/snippets/jsonValidation).
packages/vscode-objectstack/language-configuration.json	Provides bracket/comment auto-close config for the `objectstack` language id.
packages/vscode-objectstack/README.md	Documents extension features and how to build/package from source.
packages/spec/scripts/build-docs.ts	Adds explicit warnings that `content/docs/references/` is auto-generated and disposable.
packages/spec/config-schema.json	Adds a JSON Schema for `objectstack.config.ts` IDE validation/autocomplete.
packages/create-objectstack/tsup.config.ts	Bundler config for the `create-objectstack` scaffolding CLI.
packages/create-objectstack/tsconfig.json	TS compiler settings for `create-objectstack`.
packages/create-objectstack/package.json	Defines the `create-objectstack` package metadata, deps, and bin entry.
packages/create-objectstack/bin/create-objectstack.js	CLI entrypoint for `npx create-objectstack`.
packages/create-objectstack/README.md	Usage and template documentation for `create-objectstack`.
packages/cli/src/commands/lint.ts	Adds `objectstack lint` for naming/label structure checks.
packages/cli/src/commands/diff.ts	Adds `objectstack diff` to compare configs and flag breaking changes.
packages/cli/src/commands/codemod.ts	Adds `objectstack codemod v2-to-v3` for automated text transforms.
packages/cli/src/bin.ts	Wires new commands (`lint`, `diff`, `explain`, `codemod`) into the CLI.
content/docs/references/shared/view.mdx	Removes a hand-written/orphaned reference page from auto-generated area.
content/docs/references/shared/metadata-persistence.mdx	Removes a hand-written/orphaned reference page from auto-generated area.
content/docs/references/shared/meta.json	Updates nav to remove deleted pages.
content/docs/references/security/meta.json	Removes curated page from references nav (moved to guides).
content/docs/references/meta.json	Updates top-level references nav (removes curated sections moved to guides).
content/docs/references/kernel/permission.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/kernel/metadata-persistence.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/kernel/meta.json	Updates kernel references nav to remove deleted pages.
content/docs/references/integration/object-storage.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/integration/meta.json	Collapses integration references nav after removing curated/orphans.
content/docs/references/integration/message-queue.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/integration/mapping.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/integration/http.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/hub/tenant.mdx	Removes hub reference content (category removed).
content/docs/references/hub/registry-config.mdx	Removes hub reference content (category removed).
content/docs/references/hub/plugin-security.mdx	Removes hub reference content (category removed).
content/docs/references/hub/plugin-registry.mdx	Removes hub reference content (category removed).
content/docs/references/hub/meta.json	Removes hub category nav file entirely.
content/docs/references/hub/license.mdx	Removes hub reference content (category removed).
content/docs/references/data/search-engine.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/data/meta.json	Updates data references nav to remove curated pages moved to guides.
content/docs/references/automation/meta.json	Updates automation references nav to remove deleted pages.
content/docs/references/automation/events.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/automation/connector.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/api/view.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/api/package-registry.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/api/object.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/api/meta.json	Updates API references nav to remove curated/orphan pages.
content/docs/references/api/identity.mdx	Removes orphaned reference page from auto-generated area.
content/docs/references/api/connector.mdx	Removes orphaned reference page from auto-generated area.
content/docs/guides/protocol-diagram.mdx	Adds curated protocol relationship diagrams and flow diagrams.
content/docs/guides/plugin-development.mdx	Adds `defineStudioPlugin` documentation to plugin guide.
content/docs/guides/meta.json	Expands guides nav; adds curated references + contracts section.
content/docs/guides/field-type-decision-tree.mdx	Adds a curated “choose a field type” guide.
content/docs/guides/contracts/storage-service.mdx	Adds IStorageService contract reference.
content/docs/guides/contracts/metadata-service.mdx	Adds IMetadataService contract reference.
content/docs/guides/contracts/meta.json	Adds nav metadata for the Contracts guide section.
content/docs/guides/contracts/index.mdx	Adds top-level contracts overview.
content/docs/guides/contracts/data-engine.mdx	Adds IDataEngine contract reference.
content/docs/guides/contracts/cache-service.mdx	Adds ICacheService contract reference.
content/docs/guides/contracts/auth-service.mdx	Adds IAuthService contract reference.
content/docs/guides/backward-compatibility.mdx	Adds backwards compatibility/deprecation policy doc.
apps/studio/src/components/RequestHistory.tsx	Adds request/response history UI with replay + clipboard copy.
apps/studio/src/components/RelationshipVisualizer.tsx	Adds an SVG-based ERD/relationship diagram component.
apps/studio/src/components/LiveSyncStatus.tsx	Adds a live-sync status indicator UI component.
apps/studio/src/components/FieldTypePicker.tsx	Adds a searchable field type picker UI component.
apps/studio/src/components/CodeImporter.tsx	Adds “Import from Code” UI with simple parsing heuristics.
apps/studio/src/components/CodeExporter.tsx	Adds “Export as Code” UI (TypeScript/JSON) for definitions.
DX_ROADMAP.md	Marks roadmap checklist items as completed.
.cursorrules.d/objectstack.prompt.md	Documents doc directory conventions for Cursor prompt context.
.cursorrules	Adds repo-level warning: references are auto-generated; guides are hand-written.

Copilot · 2026-02-12T14:21:02Z

+    "jsonValidation": [
+      {
+        "fileMatch": "objectstack.json",
+        "url": "./schemas/objectstack.schema.json"
+      }
+    ],


jsonValidation.url points to ./schemas/objectstack.schema.json, but this package currently has no schemas/ directory, so VS Code won't be able to load the schema at runtime. Add the missing schema file (and ensure it's included in the VSIX) or update the path/URL to a file that actually ships with the extension.

Copilot · 2026-02-12T14:21:02Z

+const FIELD_TYPE_DOCS: Record<string, string> = {
+  text: 'Single-line text field (max 255 chars by default)',
+  textarea: 'Multi-line text area for longer content',
+  richtext: 'Rich text editor with HTML formatting',
+  number: 'Decimal number with configurable precision',
+  integer: 'Whole number without decimals',
+  currency: 'Monetary value with currency code',
+  boolean: 'True/false toggle',
+  date: 'Calendar date (no time)',
+  datetime: 'Date with time and timezone',
+  select: 'Single-choice picklist (requires `options`)',
+  multiselect: 'Multi-choice picklist (requires `options`)',
+  lookup: 'Reference to another object (requires `reference`)',
+  master_detail: 'Parent-child relationship with cascade delete',
+  formula: 'Computed field using expressions',


FIELD_TYPE_DOCS includes values that don't match the actual FieldType enum in packages/spec/src/data/field.zod.ts (e.g. integer, uuid, geo_point, encrypted) and misses others that do exist (e.g. toggle, radio, checkboxes, tree, summary). This will show incorrect hover info. Consider sourcing this list from @objectstack/spec/data (or generating it) to keep it in sync.

Copilot · 2026-02-12T14:21:02Z

+function generateObjectCode(def: Record<string, unknown>, name?: string): string {
+  const objName = name || (def.name as string) || 'my_object';
+  const lines = [
+    "import { defineStack } from '@objectstack/spec';",
+    '',
+    'export default defineStack({',
+    '  objects: {',
+    `    ${objName}: ${formatValue(def, 2)},`,
+    '  },',
+    '});',


The code generators emit defineStack({ objects: { ... } }) (and similarly for views/flows/agents/apps), but the config schema in this PR models these as arrays (e.g. objects: [{ name, ... }]). Exported code will not match the expected config shape. Consider exporting objects: [ ... ] etc (or updating the schema/CLI to accept the object-map form).

Copilot · 2026-02-12T14:21:03Z

+  // Try to extract defineStack() content
+  const defineStackMatch = trimmed.match(/defineStack\s*\(\s*(\{[\s\S]*\})\s*\)/);
+  if (defineStackMatch) {
+    // Safely evaluate the object literal using Function constructor
+    const objStr = defineStackMatch[1];
+    const evaluated = parseObjectLiteral(objStr);
+
+    // Detect the type from the top-level key
+    for (const key of ['objects', 'views', 'flows', 'agents', 'apps'] as const) {
+      if (evaluated[key]) {
+        const typeMap: Record<string, ParsedDefinition['type']> = {
+          objects: 'object',
+          views: 'view',
+          flows: 'flow',
+          agents: 'agent',
+          apps: 'app',
+        };
+        const entries = Object.entries(evaluated[key] as Record<string, unknown>);
+        if (entries.length > 0) {
+          const [name, def] = entries[0];
+          return {
+            type: typeMap[key],
+            name,
+            definition: def as Record<string, unknown>,
+          };
+        }
+      }
+    }


The defineStack() parsing path assumes objects/views/flows/... are object maps and uses Object.entries(evaluated[key]). In this PR's config schema those are arrays, so a typical objects: [{...}] config won't import correctly. Consider supporting the array form (and updating the placeholder example accordingly).

Copilot · 2026-02-12T14:21:03Z

+  // Try to extract defineStack() content
+  const defineStackMatch = trimmed.match(/defineStack\s*\(\s*(\{[\s\S]*\})\s*\)/);
+  if (defineStackMatch) {
+    // Safely evaluate the object literal using Function constructor


Comment says this “safely evaluate[s] the object literal using Function constructor”, but the implementation uses regex transforms + JSON.parse and never calls Function. Either update the comment or implement the intended evaluation approach (with appropriate sandboxing/constraints).

Suggested change

// Safely evaluate the object literal using Function constructor

// Parse the object literal string using the parseObjectLiteral helper

Copilot · 2026-02-12T14:21:05Z

+import {
+  printHeader,
+  printSuccess,
+  printWarning,
+  printError,
+  printInfo,
+  printStep,
+  createTimer,
+} from '../utils/format.js';


Unused import printWarning.

Copilot · 2026-02-12T14:21:05Z

+import {
+  printHeader,
+  printSuccess,
+  printError,
+  printInfo,
+  printKV,
+} from '../utils/format.js';


Unused import printSuccess.

Copilot · 2026-02-12T14:21:06Z

+import {
+  printHeader,
+  printSuccess,
+  printWarning,
+  printError,
+  printInfo,
+  printStep,
+  createTimer,
+} from '../utils/format.js';


Unused import printWarning.

Copilot · 2026-02-12T14:21:06Z

+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function toCamelCase(str: string): string {


Unused function toCamelCase.

Copilot · 2026-02-12T14:21:06Z

+  lines.push('  constructor(private baseUrl: string, private headers: Record<string, string> = {}) {}');
+  lines.push('');
+  lines.push('  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {');
+  lines.push('    const res = await fetch(`${this.baseUrl}${path}`, {');


This string is not a template literal, but appears to reference the variable path.

Initial plan

2a9cf96

Copilot AI assigned Copilot and hotlong Feb 12, 2026

Copilot started work on behalf of hotlong February 12, 2026 13:20 View session

Copilot AI and others added 6 commits February 12, 2026 13:28

Add DX Roadmap Phase 3 docs: field validation rules, backward compati…

960e75d

…bility, defineStudioPlugin guide Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

feat(cli): add generate client, generate migration, codemod, and doct…

db015d2

…or deprecation scanner commands Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

feat: add create-objectstack package — npm init CLI wizard

d39e1a9

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel Bot had a problem deploying to Preview – spec February 12, 2026 14:03 Failure

vercel Bot had a problem deploying to Preview – objectstack-play February 12, 2026 14:08 Failure

Copilot AI and others added 2 commits February 12, 2026 14:11

feat(studio): add Phase 5 DX Hub components - SchemaDesigner, FieldTy…

0bccdc0

…pePicker, RelationshipVisualizer, QueryBuilder, RequestHistory, CodeExporter, CodeImporter, LiveSyncStatus Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

docs: update DX_ROADMAP.md — mark create-objectstack and field valida…

61ae67f

…tion rules as complete Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

hotlong marked this pull request as ready for review February 12, 2026 14:13

Copilot AI review requested due to automatic review settings February 12, 2026 14:13

Copilot started reviewing on behalf of hotlong February 12, 2026 14:14 View session

hotlong merged commit 1fc6eff into main Feb 12, 2026
5 of 7 checks passed

Copilot AI requested a review from hotlong February 12, 2026 14:14

Copilot stopped work on behalf of hotlong due to an error February 12, 2026 14:14
The session was cancelled by the user.

Copilot AI reviewed Feb 12, 2026

View reviewed changes

vercel Bot had a problem deploying to Preview – spec February 12, 2026 15:28 Failure

vercel Bot had a problem deploying to Preview – objectstack-play February 12, 2026 15:33 Failure

	// Safely evaluate the object literal using Function constructor
	// Parse the object literal string using the parseObjectLiteral helper


		// ─── Helpers ────────────────────────────────────────────────────────

		function toCamelCase(str: string): string {

Uh oh!

Conversation

Copilot AI commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 12, 2026 •

edited

Loading

vercel Bot commented Feb 12, 2026 •

edited

Loading