merge: integrate latest main (plugin-setup, vercel fix) and resolve CHANGELOG conflict

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

Author: Copilot

.changeset/config.json

@@ -22,6 +22,7 @@
       "@objectstack/plugin-msw",
       "@objectstack/plugin-dev",
       "@objectstack/plugin-security",
+      "@objectstack/plugin-setup",
       "@objectstack/express",
       "@objectstack/fastify",
       "@objectstack/hono",

.changeset/fix-vercel-api-html-response.md

@@ -0,0 +1,18 @@
+---
+"@objectstack/studio": patch
+---
+
+Fix Vercel deployment API endpoints returning HTML instead of JSON.
+
+Replace the custom `getRequestListener` export in `server/index.ts` with the
+standard `handle()` adapter from `@hono/node-server/vercel` and the
+outer→inner Hono delegation pattern (`inner.fetch(c.req.raw)`).
+
+- The `handle()` adapter correctly wraps the Hono app with the
+  `(IncomingMessage, ServerResponse) => Promise<void>` signature that
+  Vercel's Node.js runtime expects for serverless functions in `api/`.
+- `@hono/node-server/vercel`'s `getRequestListener()` already handles
+  Vercel's pre-buffered `rawBody` natively, removing the need for the
+  custom body-extraction helper.
+- The outer→inner delegation pattern matches the documented ObjectStack
+  Vercel deployment guide and the `@objectstack/hono` adapter test suite.

CHANGELOG.md

@@ -23,6 +23,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (`AIToolDefinition`, `AIToolCall`, `AIToolResult`, `AIMessageWithTools`,
   `AIRequestOptionsWithTools`, `AIStreamEvent`), and conversation management
   (`IAIConversationService`, `AIConversation`) to `packages/spec/src/contracts/ai-service.ts`
+- **`@objectstack/plugin-setup` — Platform Setup App plugin** — New internal plugin
+  (`packages/plugins/plugin-setup`) that owns and finalizes the platform Setup App.
+  Ships four built-in Setup Areas (Administration, Platform, System, AI) as empty
+  skeletons. Other plugins contribute navigation items via the `setupNav` service
+  during their `init` phase. At `start`, SetupPlugin merges all contributions,
+  filters out empty areas, and registers the finalized Setup App as an internal
+  platform app. This establishes clear architectural separation: **spec** = protocol
+  only, **objectql** = data/query only, **plugins** = system feature and UI composition.
 
 ### Documentation
 - **Unified API query syntax documentation with Spec canonical format** — Rewrote

ROADMAP.md

@@ -53,6 +53,7 @@ the ecosystem for enterprise workloads.
 | Authentication (better-auth) | ✅ | `@objectstack/plugin-auth` |
 | Auth in MSW/Mock Mode | ✅ | `@objectstack/plugin-auth` + `@objectstack/runtime` |
 | RBAC / RLS / FLS Security | ✅ | `@objectstack/plugin-security` |
+| Platform Setup App | ✅ | `@objectstack/plugin-setup` |
 | CLI (16 commands) | ✅ | `@objectstack/cli` |
 | Dev Mode Plugin | ✅ | `@objectstack/plugin-dev` |
 | Next.js Adapter | ✅ | `@objectstack/nextjs` |
@@ -900,6 +901,7 @@ Final polish and advanced features.
 | `@objectstack/driver-memory` | 3.0.8 | ✅ | ✅ Stable | 9/10 |
 | `@objectstack/plugin-auth` | 3.0.8 | ✅ | ✅ Stable | 9/10 |
 | `@objectstack/plugin-security` | 3.0.8 | — | ✅ Stable | 9/10 |
+| `@objectstack/plugin-setup` | 3.3.1 | ✅ | ✅ Stable | 8/10 |
 | `@objectstack/plugin-dev` | 3.0.8 | — | ✅ Stable | 10/10 |
 | `@objectstack/plugin-hono-server` | 3.0.8 | — | ✅ Stable | 9/10 |
 | `@objectstack/plugin-msw` | 3.0.8 | — | ✅ Stable | 9/10 |

apps/studio/server/index.ts

@@ -10,15 +10,14 @@
  * legacy `(IncomingMessage, ServerResponse)` signature — NOT the Web standard
  * `(Request) → Response` format.
  *
- * We use `getRequestListener()` from `@hono/node-server` which properly
- * converts `IncomingMessage → Request`, calls our fetch callback, then writes
- * the `Response` back to `ServerResponse`.
+ * We use `handle()` from `@hono/node-server/vercel` which is the standard
+ * Vercel adapter for Hono.  It internally uses `getRequestListener()` to
+ * convert `IncomingMessage → Request` (including Vercel's pre-buffered
+ * `rawBody`) and writes the `Response` back to `ServerResponse`.
  *
- * For POST/PUT/PATCH requests, Vercel pre-buffers the body on the
- * IncomingMessage as `rawBody` (Buffer) or `body` (parsed).  We extract it
- * directly and build a clean `Request` so the inner Hono app receives a
- * body it can `.json()` without depending on Node stream-to-ReadableStream
- * conversion (which can hang when the stream has already been consumed).
+ * The outer Hono app delegates all requests to the inner ObjectStack Hono
+ * app via `inner.fetch(c.req.raw)`, matching the pattern documented in
+ * the ObjectStack deployment guide and validated by the hono adapter tests.
  *
  * All kernel/service initialisation is co-located here so there are no
  * extensionless relative module imports — which would break Node's ESM
@@ -34,8 +33,8 @@ import { SecurityPlugin } from '@objectstack/plugin-security';
 import { AuditPlugin } from '@objectstack/plugin-audit';
 import { FeedServicePlugin } from '@objectstack/service-feed';
 import { MetadataPlugin } from '@objectstack/metadata';
-import { getRequestListener } from '@hono/node-server';
-import type { Hono } from 'hono';
+import { handle } from '@hono/node-server/vercel';
+import { Hono } from 'hono';
 import { createBrokerShim } from '../src/lib/create-broker-shim.js';
 import studioConfig from '../objectstack.config.js';
 
@@ -198,93 +197,41 @@ async function ensureApp(): Promise<Hono> {
     return _app;
 }
 
-// ---------------------------------------------------------------------------
-// Body extraction helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Extract the request body from the Vercel IncomingMessage.
- *
- * Vercel's Node.js runtime pre-buffers the full request body and attaches it
- * to the IncomingMessage as `rawBody` (Buffer) and/or `body` (parsed).
- * Reading from these properties is synchronous and avoids the fragile
- * IncomingMessage → ReadableStream conversion that can hang when the
- * underlying Node stream has already been consumed.
- *
- * Returns `null` for GET/HEAD/OPTIONS or when no body is available.
- */
-function extractBody(incoming: any, method: string, contentType: string | undefined): BodyInit | null {
-    if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS') {
-        return null;
-    }
-
-    // 1. rawBody (Buffer or string) — most reliable, set by Vercel runtime
-    if (incoming?.rawBody != null) {
-        if (typeof incoming.rawBody === 'string') return incoming.rawBody;
-        if (typeof incoming.rawBody.toString === 'function') return incoming.rawBody;
-        return String(incoming.rawBody);
-    }
-
-    // 2. body (parsed by Vercel) — re-serialize based on content-type
-    if (incoming?.body != null) {
-        if (typeof incoming.body === 'string') return incoming.body;
-        if (contentType?.includes('application/json')) return JSON.stringify(incoming.body);
-        return String(incoming.body);
-    }
-
-    return null;
-}
-
 // ---------------------------------------------------------------------------
 // Vercel handler
 // ---------------------------------------------------------------------------
 
 /**
- * `getRequestListener` from `@hono/node-server` converts
- * `IncomingMessage → Request`, calls our fetch callback, then writes the
- * `Response` back to `ServerResponse` (including `res.end()`).
+ * Outer Hono app — delegates all requests to the inner ObjectStack app.
+ *
+ * `handle()` from `@hono/node-server/vercel` wraps any Hono app and returns
+ * the `(IncomingMessage, ServerResponse) => Promise<void>` signature that
+ * Vercel's Node.js runtime expects for serverless functions.  Internally it
+ * uses `getRequestListener()`, which already handles Vercel's pre-buffered
+ * `rawBody` (Buffer) on the IncomingMessage for POST/PUT/PATCH requests.
  *
- * For requests with a body, we extract it from the IncomingMessage directly
- * (bypassing the Node stream → ReadableStream conversion) and create a new
- * Request that the inner Hono app can safely `.json()`.
+ * The outer→inner delegation pattern (`inner.fetch(c.req.raw)`) is the
+ * standard ObjectStack Vercel deployment pattern documented in the deployment
+ * guide and covered by the @objectstack/hono adapter test suite.
  */
-export default getRequestListener(async (request, env) => {
-    const method = request.method;
-    const url = request.url;
+const app = new Hono();
 
-    console.log(`[Vercel] ${method} ${url}`);
+app.all('*', async (c) => {
+    console.log(`[Vercel] ${c.req.method} ${c.req.url}`);
 
     try {
-        const app = await ensureApp();
-        const incoming = (env as any)?.incoming;
-
-        // For body methods, extract body from IncomingMessage and build a clean Request
-        if (method !== 'GET' && method !== 'HEAD' && method !== 'OPTIONS' && incoming) {
-            const contentType = incoming.headers?.['content-type'];
-            const body = extractBody(incoming, method, contentType);
-
-            if (body != null) {
-                console.log(`[Vercel] Body extracted from IncomingMessage (${typeof body === 'string' ? body.length + ' chars' : 'Buffer'})`);
-                const newReq = new Request(url, {
-                    method,
-                    headers: request.headers,
-                    body,
-                });
-                return await app.fetch(newReq);
-            }
-
-            console.log('[Vercel] No rawBody/body on IncomingMessage — using proxy request');
-        }
-
-        return await app.fetch(request);
+        const inner = await ensureApp();
+        return await inner.fetch(c.req.raw);
     } catch (err: any) {
         console.error('[Vercel] Handler error:', err?.message || err);
-        return new Response(
-            JSON.stringify({
+        return c.json(
+            {
                 success: false,
                 error: { message: err?.message || 'Internal Server Error', code: 500 },
-            }),
-            { status: 500, headers: { 'Content-Type': 'application/json' } },
+            },
+            500,
         );
     }
 });
+
+export default handle(app);

packages/plugins/plugin-setup/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @objectstack/plugin-setup
+
+## 3.3.1
+
+### Added
+
+- Initial release of the Setup Plugin.
+- Defines the platform Setup App identity (name, label, icon, permissions, branding).
+- Ships 4 built-in Setup Areas: Administration, Platform, System, AI.
+- Provides `setupNav` service for contribution-based navigation composition.
+- Auto-filters empty areas and supports custom area extensions.

packages/plugins/plugin-setup/README.md

@@ -0,0 +1,110 @@
+# @objectstack/plugin-setup
+
+Setup Plugin for ObjectStack — owns and composes the platform **Setup App** with area-based navigation.
+
+## Overview
+
+The Setup App is the central administration interface of the ObjectStack platform (equivalent to Salesforce Setup or ServiceNow System Administration). Rather than scattering setup definitions across `spec` and `objectql`, this plugin provides clear ownership:
+
+- **Spec** → protocol schemas only
+- **ObjectQL** → data engine only
+- **plugin-setup** → owns the Setup App identity, areas, and navigation composition
+
+## Features
+
+- **Four Built-in Areas**: Administration, Platform, System, and AI — shipped as empty skeletons.
+- **Contribution Model**: Any plugin can contribute navigation items to Setup areas via the `setupNav` service.
+- **Area Filtering**: Empty areas are automatically filtered out at finalization.
+- **Custom Areas**: Plugins can contribute to custom area IDs beyond the four built-in ones.
+- **I18n Labels**: All labels use the `I18nLabel` union type for internationalization.
+
+## Usage
+
+### Register the Plugin
+
+```typescript
+import { ObjectKernel } from '@objectstack/core';
+import { SetupPlugin } from '@objectstack/plugin-setup';
+
+const kernel = new ObjectKernel({
+  plugins: [
+    new SetupPlugin(),
+    // ... other plugins
+  ],
+});
+```
+
+### Contribute Navigation from Another Plugin
+
+```typescript
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type { SetupNavService } from '@objectstack/plugin-setup';
+import { SETUP_AREA_IDS } from '@objectstack/plugin-setup';
+
+export class MyPlugin implements Plugin {
+  name = 'com.example.my-plugin';
+
+  async init(ctx: PluginContext) {
+    const setupNav = ctx.getService<SetupNavService>('setupNav');
+
+    setupNav.contribute({
+      areaId: SETUP_AREA_IDS.administration,
+      items: [
+        { id: 'nav_users', type: 'object', label: 'Users', objectName: 'sys_user' },
+        { id: 'nav_roles', type: 'object', label: 'Roles', objectName: 'sys_role' },
+      ],
+    });
+  }
+}
+```
+
+### Exported Components
+
+```typescript
+import {
+  SetupPlugin,
+  type SetupNavService,
+  SETUP_APP_DEFAULTS,
+  type SetupNavContribution,
+  SETUP_AREAS,
+  SETUP_AREA_IDS,
+  type SetupAreaId,
+} from '@objectstack/plugin-setup';
+```
+
+## Built-in Setup Areas
+
+| Area | ID | Icon | Order | Description |
+|:-----|:---|:-----|:-----:|:------------|
+| Administration | `area_administration` | shield | 10 | Users, roles, permissions, security |
+| Platform | `area_platform` | layers | 20 | Objects, fields, layouts, automation |
+| System | `area_system` | settings | 30 | Datasources, integrations, jobs, logs |
+| AI | `area_ai` | brain | 40 | Agents, models, RAG pipelines |
+
+## Architecture
+
+```
+┌──────────────────────────────────────────┐
+│              SetupPlugin                 │
+│                                          │
+│  init():                                 │
+│    → registers 'setupNav' service        │
+│                                          │
+│  start():                                │
+│    → collects contributions              │
+│    → merges into area skeletons          │
+│    → filters empty areas                 │
+│    → registers finalized Setup App       │
+│                                          │
+└──────────────────────────────────────────┘
+         ▲                    ▲
+         │  contribute()      │  contribute()
+    ┌────┴────┐          ┌────┴────┐
+    │ plugin  │          │ plugin  │
+    │  auth   │          │security │
+    └─────────┘          └─────────┘
+```
+
+## License
+
+Apache-2.0 © ObjectStack

packages/plugins/plugin-setup/objectstack.config.ts

@@ -0,0 +1,21 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineStack } from '@objectstack/spec';
+
+/**
+ * ObjectStack Configuration for plugin-setup
+ *
+ * This configuration defines the manifest for the platform Setup plugin.
+ * The Setup App itself is composed at runtime by collecting setupNav
+ * contributions from all registered plugins.
+ */
+export default defineStack({
+  manifest: {
+    id: 'com.objectstack.plugin-setup',
+    namespace: 'setup',
+    version: '3.3.1',
+    type: 'plugin',
+    name: 'Platform Setup Plugin',
+    description: 'Owns and composes the platform Setup App with area-based navigation contributed by other plugins',
+  },
+});

packages/plugins/plugin-setup/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@objectstack/plugin-setup",
+  "version": "3.3.1",
+  "license": "Apache-2.0",
+  "description": "Setup Plugin for ObjectStack — Platform Setup App with area-based navigation composition",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@objectstack/core": "workspace:*",
+    "@objectstack/spec": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

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

@@ -0,0 +1,12 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @objectstack/plugin-setup
+ *
+ * Setup Plugin for ObjectStack — owns and composes the platform Setup App.
+ * Other plugins contribute navigation items via the `setupNav` service.
+ */
+
+export { SetupPlugin, type SetupNavService } from './setup-plugin.js';
+export { SETUP_APP_DEFAULTS, type SetupNavContribution } from './setup-app.js';
+export { SETUP_AREAS, SETUP_AREA_IDS, type SetupAreaId } from './setup-areas.js';