feat(plugin-dev): simulate all kernel services for full API dev environment

- Add AppPlugin integration to register project metadata (objects, views, dashboards)
- Add REST API plugin via createRestApiPlugin (metadata read/write endpoints)
- Add Dispatcher plugin (auth, GraphQL, analytics, packages, storage, automation)
- Add `stack` option to DevPluginOptions for loading project metadata
- Fix DevPluginConfigSchema doc examples per reviewer feedback
- Add z.string().min(1) constraint on service record keys
- Add test for empty service key rejection
- Update README with full API endpoint documentation

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

Author: Copilot

packages/plugins/plugin-dev/README.md

@@ -1,10 +1,16 @@
 # @objectstack/plugin-dev
 
-> Development Mode Plugin for ObjectStack — auto-enables all services with in-memory implementations.
+> Development Mode Plugin for ObjectStack — auto-enables all kernel services for a full-featured API development environment.
 
 ## Overview
 
-Instead of manually wiring up ObjectQL, drivers, auth, HTTP server, and REST endpoints for local development, use `DevPlugin` to get a fully functional stack in one line.
+Instead of manually wiring up ObjectQL, drivers, auth, HTTP server, REST endpoints, dispatcher, and metadata for local development, use `DevPlugin` to get a fully functional stack in one line.
+
+The dev environment simulates **all kernel services** so you can:
+- CRUD business objects via REST API
+- Read, modify, and save views/apps/dashboards via metadata API (`PUT /api/v1/meta/:type/:name`)
+- Use GraphQL, analytics, storage, and automation endpoints
+- Authenticate with dev credentials (no real auth provider needed)
 
 ## Usage
 
@@ -25,6 +31,19 @@ export default defineStack({
 });
 ```
 
+### Full-stack dev with project metadata
+
+```typescript
+import config from './objectstack.config';
+import { DevPlugin } from '@objectstack/plugin-dev';
+
+// Load all project metadata (objects, views, etc.) into the dev server
+export default defineStack({
+  ...config,
+  plugins: [new DevPlugin({ stack: config })],
+});
+```
+
 ### With options
 
 ```typescript
@@ -33,7 +52,8 @@ plugins: [
     port: 4000,
     seedAdminUser: true,
     services: {
-      auth: false,      // Skip auth for quick prototyping
+      auth: false,        // Skip auth for quick prototyping
+      dispatcher: false,  // Skip extended API routes
     },
   }),
 ]
@@ -43,14 +63,32 @@ plugins: [
 
 | Service | Package | Description |
 |---------|---------|-------------|
-| ObjectQL | `@objectstack/objectql` | Data engine (query, CRUD, hooks) |
+| ObjectQL | `@objectstack/objectql` | Data engine (query, CRUD, hooks, metadata) |
 | InMemoryDriver | `@objectstack/driver-memory` | In-memory database (no DB install) |
+| App/Metadata | `@objectstack/runtime` | Project metadata (objects, views, apps, dashboards) |
 | Auth | `@objectstack/plugin-auth` | Authentication with dev credentials |
 | Hono Server | `@objectstack/plugin-hono-server` | HTTP server on configured port |
-| REST API | `@objectstack/rest` | Auto-generated CRUD endpoints |
+| REST API | `@objectstack/rest` | Auto-generated CRUD + metadata endpoints |
+| Dispatcher | `@objectstack/runtime` | Auth routes, GraphQL, analytics, packages, storage |
 
 All services are **optional** — if a peer package isn't installed, it is silently skipped.
 
+## API Endpoints (when all services enabled)
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/v1/data/:object` | List records |
+| `POST /api/v1/data/:object` | Create record |
+| `GET /api/v1/data/:object/:id` | Get record |
+| `PUT /api/v1/data/:object/:id` | Update record |
+| `DELETE /api/v1/data/:object/:id` | Delete record |
+| `GET /api/v1/meta` | List metadata types |
+| `GET /api/v1/meta/:type` | List metadata of type |
+| `GET /api/v1/meta/:type/:name` | Get metadata item |
+| `PUT /api/v1/meta/:type/:name` | Save metadata item |
+| `POST /api/v1/graphql` | GraphQL endpoint |
+| `GET /.well-known/objectstack` | Service discovery |
+
 ## Options
 
 | Option | Type | Default | Description |
@@ -62,6 +100,7 @@ All services are **optional** — if a peer package isn't installed, it is silen
 | `verbose` | `boolean` | `true` | Enable verbose logging |
 | `services` | `Record<string, boolean>` | all `true` | Enable/disable individual services |
 | `extraPlugins` | `Plugin[]` | `[]` | Additional plugins to load |
+| `stack` | `object` | — | Stack definition to load as project metadata |
 
 ## License
 

packages/plugins/plugin-dev/src/dev-plugin.test.ts

@@ -14,12 +14,13 @@ describe('DevPlugin', () => {
     expect(plugin).toBeDefined();
   });
 
-  it('should accept custom options', () => {
+  it('should accept custom options including stack', () => {
     const plugin = new DevPlugin({
       port: 4000,
       seedAdminUser: false,
       verbose: false,
-      services: { auth: false },
+      services: { auth: false, dispatcher: false },
+      stack: { manifest: { id: 'test', name: 'test', version: '1.0.0', type: 'app' } },
     });
     expect(plugin).toBeDefined();
   });
@@ -69,6 +70,7 @@ describe('DevPlugin', () => {
         auth: false,
         server: false,
         rest: false,
+        dispatcher: false,
       },
     });
 

packages/plugins/plugin-dev/src/dev-plugin.ts

@@ -44,7 +44,7 @@ export interface DevPluginOptions {
    * Override which services to enable. By default all core services are enabled.
    * Set a service name to `false` to skip it.
    *
-   * Available services: 'objectql', 'driver', 'auth', 'server', 'rest'
+   * Available services: 'objectql', 'driver', 'auth', 'server', 'rest', 'dispatcher'
    */
   services?: Partial<Record<string, boolean>>;
 
@@ -53,21 +53,44 @@ export interface DevPluginOptions {
    * Useful for adding custom project plugins while still getting the dev defaults.
    */
   extraPlugins?: Plugin[];
+
+  /**
+   * Stack definition to load as a project.
+   * When provided, the DevPlugin wraps it in an AppPlugin so that all
+   * metadata (objects, views, apps, dashboards, etc.) is registered with
+   * the kernel and exposed through the REST/metadata APIs.
+   *
+   * This is what makes `new DevPlugin({ stack: config })` equivalent to
+   * a full `os serve --dev` environment: views can be read, modified, and
+   * saved through the API.
+   *
+   * @example
+   * ```ts
+   * import config from './objectstack.config';
+   * plugins: [new DevPlugin({ stack: config })]
+   * ```
+   */
+  stack?: Record<string, any>;
 }
 
 /**
  * Development Mode Plugin for ObjectStack
  *
- * A convenience plugin that auto-configures the entire platform stack
- * for local development. Instead of manually wiring:
+ * A convenience plugin that auto-configures the **entire** platform stack
+ * for local development, simulating all kernel services so developers
+ * can work in a full-featured API environment without external dependencies.
+ *
+ * Instead of manually wiring:
  *
  * ```ts
  * plugins: [
  *   new ObjectQLPlugin(),
  *   new DriverPlugin(new InMemoryDriver()),
  *   new AuthPlugin({ secret: '...', baseUrl: '...' }),
  *   new HonoServerPlugin({ port: 3000 }),
- *   // ...
+ *   createRestApiPlugin(),
+ *   createDispatcherPlugin(),
+ *   new AppPlugin(config),
  * ]
  * ```
  *
@@ -77,13 +100,17 @@ export interface DevPluginOptions {
  * plugins: [new DevPlugin()]
  * ```
  *
- * The DevPlugin will:
- * 1. Register an ObjectQL engine (data layer)
- * 2. Register an InMemoryDriver (no database required)
- * 3. Register an Auth plugin (with dev credentials)
- * 4. Register a Hono HTTP server
- * 5. Register REST API endpoints
- * 6. Optionally seed a default admin user
+ * ## Services enabled
+ *
+ * | Service      | Package                           | Description                               |
+ * |--------------|-----------------------------------|-------------------------------------------|
+ * | ObjectQL     | `@objectstack/objectql`           | Data engine (query, CRUD, hooks)          |
+ * | Driver       | `@objectstack/driver-memory`      | In-memory database (no DB install)        |
+ * | Auth         | `@objectstack/plugin-auth`        | Authentication with dev credentials       |
+ * | HTTP Server  | `@objectstack/plugin-hono-server` | HTTP server on configured port            |
+ * | REST API     | `@objectstack/rest`               | Auto-generated CRUD + metadata endpoints  |
+ * | Dispatcher   | `@objectstack/runtime`            | Auth, GraphQL, analytics, packages, etc.  |
+ * | App/Metadata | `@objectstack/runtime`            | Project metadata (objects, views, apps)   |
  *
  * All services can be individually disabled via `options.services`.
  * Peer packages are loaded via dynamic import and silently skipped if missing.
@@ -122,13 +149,13 @@ export class DevPlugin implements Plugin {
 
     const enabled = (name: string) => this.options.services?.[name] !== false;
 
-    // 1. ObjectQL Engine (data layer)
+    // 1. ObjectQL Engine (data layer + metadata service)
     if (enabled('objectql')) {
       try {
         const { ObjectQLPlugin } = await import('@objectstack/objectql');
         const qlPlugin = new ObjectQLPlugin();
         this.childPlugins.push(qlPlugin);
-        ctx.logger.info('  ✔ ObjectQL engine enabled');
+        ctx.logger.info('  ✔ ObjectQL engine enabled (data + metadata)');
       } catch {
         ctx.logger.warn('  ✘ @objectstack/objectql not installed — skipping data engine');
       }
@@ -148,7 +175,21 @@ export class DevPlugin implements Plugin {
       }
     }
 
-    // 3. Auth Plugin
+    // 3. App Plugin — registers project metadata (objects, views, apps, dashboards, etc.)
+    //    This is the key piece that enables full API development:
+    //    once metadata is registered, REST endpoints can read/write views, etc.
+    if (this.options.stack) {
+      try {
+        const { AppPlugin } = await import('@objectstack/runtime') as any;
+        const appPlugin = new AppPlugin(this.options.stack);
+        this.childPlugins.push(appPlugin);
+        ctx.logger.info('  ✔ App metadata loaded from stack definition');
+      } catch {
+        ctx.logger.warn('  ✘ @objectstack/runtime not installed — skipping app metadata');
+      }
+    }
+
+    // 4. Auth Plugin
     if (enabled('auth')) {
       try {
         const { AuthPlugin } = await import('@objectstack/plugin-auth') as any;
@@ -163,7 +204,7 @@ export class DevPlugin implements Plugin {
       }
     }
 
-    // 4. Hono HTTP Server
+    // 5. Hono HTTP Server
     if (enabled('server')) {
       try {
         const { HonoServerPlugin } = await import('@objectstack/plugin-hono-server') as any;
@@ -177,28 +218,30 @@ export class DevPlugin implements Plugin {
       }
     }
 
-    // 5. REST API endpoints
+    // 6. REST API endpoints (CRUD + metadata read/write)
     if (enabled('rest')) {
       try {
-        const restModule = await import('@objectstack/rest') as any;
-        // REST may export a plugin class or a factory function
-        const RestPlugin = (restModule as any).RestPlugin
-          ?? (restModule as any).createRestPlugin
-          ?? (restModule as any).default;
-        if (typeof RestPlugin === 'function') {
-          const restPlugin = RestPlugin.prototype?.init
-            ? new RestPlugin()
-            : RestPlugin();
-          if (restPlugin) {
-            this.childPlugins.push(restPlugin);
-            ctx.logger.info('  ✔ REST API endpoints enabled');
-          }
-        }
+        const { createRestApiPlugin } = await import('@objectstack/rest') as any;
+        const restPlugin = createRestApiPlugin();
+        this.childPlugins.push(restPlugin);
+        ctx.logger.info('  ✔ REST API endpoints enabled (CRUD + metadata)');
       } catch {
         ctx.logger.debug('  ℹ @objectstack/rest not installed — skipping REST endpoints');
       }
     }
 
+    // 7. Dispatcher (auth routes, GraphQL, analytics, packages, storage, automation)
+    if (enabled('dispatcher')) {
+      try {
+        const { createDispatcherPlugin } = await import('@objectstack/runtime') as any;
+        const dispatcherPlugin = createDispatcherPlugin();
+        this.childPlugins.push(dispatcherPlugin);
+        ctx.logger.info('  ✔ Dispatcher enabled (auth, GraphQL, analytics, packages, storage)');
+      } catch {
+        ctx.logger.debug('  ℹ Dispatcher not available — skipping extended API routes');
+      }
+    }
+
     // Extra user-provided plugins
     if (this.options.extraPlugins) {
       this.childPlugins.push(...this.options.extraPlugins);
@@ -241,6 +284,10 @@ export class DevPlugin implements Plugin {
     ctx.logger.info('─────────────────────────────────────────');
     ctx.logger.info('🟢 ObjectStack Dev Server ready');
     ctx.logger.info(`   http://localhost:${this.options.port}`);
+    ctx.logger.info('');
+    ctx.logger.info('   API:       /api/v1/data/:object');
+    ctx.logger.info('   Metadata:  /api/v1/meta/:type/:name');
+    ctx.logger.info('   Discovery: /.well-known/objectstack');
     ctx.logger.info('─────────────────────────────────────────');
   }
 

packages/plugins/plugin-dev/src/index.ts

@@ -6,8 +6,15 @@
  * Development Mode Plugin for ObjectStack.
  *
  * Auto-enables all platform services (ObjectQL, InMemoryDriver, Auth,
- * Hono HTTP server, REST API) with in-memory implementations so that
- * developers can run the full stack locally without external dependencies.
+ * Hono HTTP server, REST API, Dispatcher, Metadata) with in-memory
+ * implementations so that developers can run the full stack locally
+ * without external dependencies.
+ *
+ * Provides a complete API development environment where you can:
+ * - CRUD business objects
+ * - Read/write metadata (views, apps, dashboards, etc.)
+ * - Use GraphQL, analytics, and automation endpoints
+ * - Authenticate with dev credentials
  *
  * @example Zero-config
  * ```typescript
@@ -20,15 +27,13 @@
  * });
  * ```
  *
- * @example With options
+ * @example Full-stack dev with project metadata
  * ```typescript
- * plugins: [
- *   new DevPlugin({
- *     port: 4000,
- *     seedAdminUser: true,
- *     services: { auth: false }, // disable auth
- *   }),
- * ]
+ * import config from './objectstack.config';
+ * import { DevPlugin } from '@objectstack/plugin-dev';
+ *
+ * // Loads all project metadata (objects, views, etc.) into the dev server
+ * plugins: [new DevPlugin({ stack: config })]
  * ```
  */
 

packages/spec/src/kernel/dev-plugin.test.ts

@@ -223,5 +223,12 @@ describe('Dev Mode Plugin Protocol', () => {
         DevPluginConfigSchema.safeParse({ simulatedLatency: -10 }).success,
       ).toBe(false);
     });
+
+    it('should reject empty string as service key', () => {
+      const result = DevPluginConfigSchema.safeParse({
+        services: { '': { enabled: true } },
+      });
+      expect(result.success).toBe(false);
+    });
   });
 });