Changes before error encountered

Copilot · hotlong · web-flow · commit 7e3bf607db93 · 2026-03-27T02:34:31.000Z
Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/3f488b6a-3c5e-42a1-bc4c-25061d45d6d5 Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
diff --git a/packages/adapters/express/src/index.ts b/packages/adapters/express/src/index.ts
@@ -78,7 +78,7 @@ export function createExpressRouter(options: ExpressAdapterOptions): Router {
   // ─── Explicit routes (framework-specific handling required) ────────────────
 
   // --- Discovery ---
-  router.get('/', async (_req: Request, res: Response) => {
+  router.get('/discovery', async (_req: Request, res: Response) => {
     res.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
   });
 
diff --git a/packages/adapters/fastify/src/index.ts b/packages/adapters/fastify/src/index.ts
@@ -76,13 +76,13 @@ export async function objectStackPlugin(fastify: FastifyInstance, options: Fasti
   // ─── Explicit routes (framework-specific handling required) ────────────────
 
   // --- Discovery ---
-  fastify.get(`${prefix}`, async (_request: FastifyRequest, reply: FastifyReply) => {
+  fastify.get(`${prefix}/discovery`, async (_request: FastifyRequest, reply: FastifyReply) => {
     return reply.send({ data: await dispatcher.getDiscoveryInfo(prefix) });
   });
 
   // --- .well-known ---
   fastify.get('/.well-known/objectstack', async (_request: FastifyRequest, reply: FastifyReply) => {
-    return reply.redirect(prefix);
+    return reply.redirect(`${prefix}/discovery`);
   });
 
   // --- Auth (needs auth service integration) ---
diff --git a/packages/adapters/hono/src/index.ts b/packages/adapters/hono/src/index.ts
@@ -81,13 +81,13 @@ export function createHonoApp(options: ObjectStackHonoOptions): Hono {
   // ─── Explicit routes (framework-specific handling required) ────────────────
 
   // --- Discovery ---
-  app.get(`${prefix}`, async (c) => {
+  app.get(`${prefix}/discovery`, async (c) => {
     return c.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
   });
 
   // --- .well-known ---
   app.get('/.well-known/objectstack', (c) => {
-    return c.redirect(prefix);
+    return c.redirect(`${prefix}/discovery`);
   });
 
   // --- Auth (needs auth service integration) ---
diff --git a/packages/adapters/nestjs/src/index.ts b/packages/adapters/nestjs/src/index.ts
@@ -94,7 +94,7 @@ export class ObjectStackController {
   }
 
   // --- Discovery Endpoint ---
-  @Get()
+  @Get('discovery')
   async discovery() {
     return { data: await this.service.dispatcher.getDiscoveryInfo('/api') };
   }
@@ -241,7 +241,7 @@ export class ObjectStackController {
 export class DiscoveryController {
   @Get('objectstack')
   discover(@Res() res: any) {
-    return res.redirect('/api');
+    return res.redirect('/api/discovery');
   }
 }
 
diff --git a/packages/adapters/nestjs/src/nestjs.test.ts b/packages/adapters/nestjs/src/nestjs.test.ts
@@ -442,12 +442,12 @@ describe('ObjectStackController', () => {
 });
 
 describe('DiscoveryController', () => {
-  it('redirects to /api', () => {
+  it('redirects to /api/discovery', () => {
     const controller = new DiscoveryController();
     const res = createMockRes();
 
     controller.discover(res);
 
-    expect(res._redirectUrl).toBe('/api');
+    expect(res._redirectUrl).toBe('/api/discovery');
   });
 });
diff --git a/packages/adapters/nextjs/src/index.ts b/packages/adapters/nextjs/src/index.ts
@@ -62,7 +62,7 @@ export function createRouteHandler(options: NextAdapterOptions) {
     const method = req.method;
     
     // --- 0. Discovery Endpoint ---
-    if (segments.length === 0 && method === 'GET') {
+    if (segments.length === 1 && segments[0] === 'discovery' && method === 'GET') {
       return NextResponse.json({ data: await dispatcher.getDiscoveryInfo(options.prefix || '/api') });
     }
 
@@ -152,7 +152,7 @@ export function createDiscoveryHandler(options: NextAdapterOptions) {
   return async function discoveryHandler(req: NextRequest) {
       const apiPath = options.prefix || '/api';
       const url = new URL(req.url);
-      const targetUrl = new URL(apiPath, url.origin);
+      const targetUrl = new URL(`${apiPath}/discovery`, url.origin);
       return NextResponse.redirect(targetUrl);
   }
 }
diff --git a/packages/adapters/nuxt/src/index.ts b/packages/adapters/nuxt/src/index.ts
@@ -89,7 +89,7 @@ export function createH3Router(options: NuxtAdapterOptions): Router {
 
   // --- Discovery ---
   router.get(
-    `${prefix}`,
+    `${prefix}/discovery`,
     defineEventHandler(async () => {
       return { data: await dispatcher.getDiscoveryInfo(prefix) };
     }),
@@ -99,7 +99,7 @@ export function createH3Router(options: NuxtAdapterOptions): Router {
   router.get(
     '/.well-known/objectstack',
     defineEventHandler((event) => {
-      return sendRedirect(event, prefix);
+      return sendRedirect(event, `${prefix}/discovery`);
     }),
   );
 
diff --git a/packages/adapters/sveltekit/src/index.ts b/packages/adapters/sveltekit/src/index.ts
@@ -99,7 +99,7 @@ export function createRequestHandler(options: SvelteKitAdapterOptions) {
     const segments = path.split('/').filter(Boolean);
 
     // --- Discovery ---
-    if (segments.length === 0 && method === 'GET') {
+    if (segments.length === 1 && segments[0] === 'discovery' && method === 'GET') {
       return new Response(JSON.stringify({ data: await dispatcher.getDiscoveryInfo(prefix) }), {
         status: 200,
         headers: { 'Content-Type': 'application/json' },
diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
@@ -238,10 +238,10 @@ export class ObjectStackClient {
         this.logger.debug('Standard discovery probe failed', { error: (e as Error).message });
       }
 
-      // 2. Fallback to Legacy/Direct Path /api/v1
+      // 2. Fallback to Protocol-standard Discovery Path /api/v1/discovery
       if (!data) {
-        const fallbackUrl = `${this.baseUrl}/api/v1`;
-        this.logger.debug('Falling back to legacy discovery', { url: fallbackUrl });
+        const fallbackUrl = `${this.baseUrl}/api/v1/discovery`;
+        this.logger.debug('Falling back to standard discovery endpoint', { url: fallbackUrl });
         const res = await this.fetchImpl(fallbackUrl);
         if (!res.ok) {
            throw new Error(`Failed to connect to ${fallbackUrl}: ${res.statusText}`);
@@ -1700,7 +1700,7 @@ export class ObjectStackClient {
       notifications: '/api/v1/notifications',
       ai: '/api/v1/ai',
       i18n: '/api/v1/i18n',
-      feed: '/api/v1/data',
+      feed: '/api/v1/feed',
     };
     
     return routeMap[type] || `/api/v1/${type}`;
diff --git a/packages/plugins/plugin-hono-server/src/hono-plugin.ts b/packages/plugins/plugin-hono-server/src/hono-plugin.ts
@@ -276,8 +276,8 @@ export class HonoServerPlugin implements Plugin {
         };
 
         // Discovery endpoints
-        rawApp.get('/.well-known/objectstack', (c: any) => c.json({ data: discovery }));
-        rawApp.get(prefix, (c: any) => c.json({ data: discovery }));
+        rawApp.get('/.well-known/objectstack', (c: any) => c.redirect(`${prefix}/discovery`));
+        rawApp.get(`${prefix}/discovery`, (c: any) => c.json({ data: discovery }));
 
         ctx.logger.info('Registered discovery endpoints', { prefix });
 
diff --git a/packages/runtime/src/http-dispatcher.root.test.ts b/packages/runtime/src/http-dispatcher.root.test.ts
@@ -46,6 +46,21 @@ describe('HttpDispatcher Root Handling', () => {
         expect(data.routes.metadata).toBe('/meta');
     });
 
+    it('should handle GET /discovery (protocol-standard route)', async () => {
+        const context = { request: {} };
+        const result = await dispatcher.dispatch('GET', '/discovery', undefined, {}, context);
+
+        expect(result.handled).toBe(true);
+        expect(result.response).toBeDefined();
+        expect(result.response?.status).toBe(200);
+        
+        const data = result.response?.body?.data;
+        expect(data).toBeDefined();
+        expect(data.name).toBe('ObjectOS');
+        expect(data.version).toBe('1.0.0');
+        expect(data.routes).toBeDefined();
+    });
+
     it('should NOT handle POST request to root path ("")', async () => {
         const context = { request: {} };
         const method = 'POST';
diff --git a/packages/runtime/src/http-dispatcher.ts b/packages/runtime/src/http-dispatcher.ts
@@ -1154,9 +1154,10 @@ export class HttpDispatcher {
     async dispatch(method: string, path: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
         const cleanPath = path.replace(/\/$/, ''); // Remove trailing slash if present, but strict on clean paths
 
-        // 0. Root Discovery Endpoint (GET /)
-        // Handles request to base URL (e.g. /api/v1) which MSW strips to empty string
-        if (cleanPath === '' && method === 'GET') {
+        // 0. Discovery Endpoint (GET /discovery or GET /)
+        // Standard route: /discovery (protocol-compliant)
+        // Legacy route: / (empty path, for backward compatibility — MSW strips base URL)
+        if ((cleanPath === '/discovery' || cleanPath === '') && method === 'GET') {
              // We use '' as prefix since we are internal dispatcher
              const info = await this.getDiscoveryInfo('');
              return { 
diff --git a/packages/spec/src/api/discovery.test.ts b/packages/spec/src/api/discovery.test.ts
@@ -29,10 +29,14 @@ describe('ApiRoutesSchema', () => {
       actions: '/api/v1/p',
       storage: '/api/v1/storage',
       graphql: '/api/v1/graphql',
+      feed: '/api/v1/feed',
+      discovery: '/api/v1/discovery',
     });
 
     expect(routes.data).toBe('/api/v1/data');
     expect(routes.graphql).toBe('/api/v1/graphql');
+    expect(routes.feed).toBe('/api/v1/feed');
+    expect(routes.discovery).toBe('/api/v1/discovery');
   });
 
   it('should accept custom route paths', () => {
diff --git a/packages/spec/src/api/discovery.zod.ts b/packages/spec/src/api/discovery.zod.ts
@@ -42,6 +42,9 @@ export const ApiRoutesSchema = z.object({
   /** Base URL for Schema Definitions (Metadata Protocol) */
   metadata: z.string().describe('e.g. /api/v1/meta'),
 
+  /** Base URL for API Discovery endpoint */
+  discovery: z.string().optional().describe('e.g. /api/v1/discovery'),
+
   /** Base URL for UI Configurations (Views, Menus) */
   ui: z.string().optional().describe('e.g. /api/v1/ui'),
   
@@ -77,6 +80,9 @@ export const ApiRoutesSchema = z.object({
 
   /** Base URL for Internationalization */
   i18n: z.string().optional().describe('e.g. /api/v1/i18n'),
+
+  /** Base URL for Feed / Chatter API */
+  feed: z.string().optional().describe('e.g. /api/v1/feed'),
 });
 
 /**
diff --git a/packages/spec/src/api/dispatcher.test.ts b/packages/spec/src/api/dispatcher.test.ts
@@ -120,7 +120,7 @@ describe('DispatcherConfigSchema', () => {
 
 describe('DEFAULT_DISPATCHER_ROUTES', () => {
   it('should have routes for all protocol namespaces', () => {
-    expect(DEFAULT_DISPATCHER_ROUTES.length).toBeGreaterThanOrEqual(13);
+    expect(DEFAULT_DISPATCHER_ROUTES.length).toBeGreaterThanOrEqual(15);
   });
 
   it('should include required services', () => {
@@ -130,6 +130,15 @@ describe('DEFAULT_DISPATCHER_ROUTES', () => {
     expect(services).toContain('auth');
   });
 
+  it('should include storage and feed services', () => {
+    const services = DEFAULT_DISPATCHER_ROUTES.map(r => r.service);
+    expect(services).toContain('file-storage');
+    // feed route maps to the data service
+    const feedRoute = DEFAULT_DISPATCHER_ROUTES.find(r => r.prefix.includes('feed'));
+    expect(feedRoute).toBeDefined();
+    expect(feedRoute!.service).toBe('data');
+  });
+
   it('should include optional services', () => {
     const services = DEFAULT_DISPATCHER_ROUTES.map(r => r.service);
     expect(services).toContain('ai');
diff --git a/packages/spec/src/api/dispatcher.zod.ts b/packages/spec/src/api/dispatcher.zod.ts
@@ -153,6 +153,8 @@ export const DEFAULT_DISPATCHER_ROUTES: DispatcherRouteInput[] = [
   { prefix: '/api/v1/workflow',      service: 'workflow' },
   { prefix: '/api/v1/analytics',     service: 'analytics' },
   { prefix: '/api/v1/automation',    service: 'automation' },
+  { prefix: '/api/v1/storage',       service: 'file-storage' },
+  { prefix: '/api/v1/feed',          service: 'data' },
   { prefix: '/api/v1/i18n',          service: 'i18n' },
   { prefix: '/api/v1/notifications', service: 'notification' },
   { prefix: '/api/v1/realtime',      service: 'realtime' },
diff --git a/packages/spec/src/api/protocol.test.ts b/packages/spec/src/api/protocol.test.ts
@@ -327,24 +327,21 @@ describe('ObjectStack Protocol', () => {
 import { GetDiscoveryResponseSchema } from './protocol.zod';
 
 describe('GetDiscoveryResponseSchema (capabilities)', () => {
-  it('should accept response with well-known capabilities', () => {
+  it('should accept response with hierarchical capabilities', () => {
     const result = GetDiscoveryResponseSchema.safeParse({
       version: 'v1',
-      apiName: 'ObjectStack API',
+      name: 'ObjectStack API',
       capabilities: {
-        feed: true,
-        comments: true,
-        automation: false,
-        cron: false,
-        search: true,
-        export: false,
-        chunkedUpload: true,
+        feed: { enabled: true },
+        comments: { enabled: true, features: { threaded: true } },
+        automation: { enabled: false },
+        search: { enabled: true, description: 'Full-text search' },
       },
     });
     expect(result.success).toBe(true);
     if (result.success) {
-      expect(result.data.capabilities?.feed).toBe(true);
-      expect(result.data.capabilities?.automation).toBe(false);
+      expect(result.data.capabilities?.feed?.enabled).toBe(true);
+      expect(result.data.capabilities?.automation?.enabled).toBe(false);
     }
   });
 
@@ -359,13 +356,33 @@ describe('GetDiscoveryResponseSchema (capabilities)', () => {
     }
   });
 
-  it('should reject capabilities with missing fields', () => {
+  it('should accept response with apiName for backward compatibility', () => {
     const result = GetDiscoveryResponseSchema.safeParse({
       version: 'v1',
       apiName: 'ObjectStack API',
-      capabilities: { feed: true },
     });
-    expect(result.success).toBe(false);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.apiName).toBe('ObjectStack API');
+    }
+  });
+
+  it('should accept full DiscoverySchema-compatible response', () => {
+    const result = GetDiscoveryResponseSchema.safeParse({
+      name: 'ObjectOS',
+      version: '1.0.0',
+      environment: 'development',
+      routes: { data: '/api/v1/data', metadata: '/api/v1/meta' },
+      locale: { default: 'en', supported: ['en'], timezone: 'UTC' },
+      services: {
+        data: { enabled: true, status: 'available', route: '/api/v1/data', provider: 'kernel' },
+      },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.name).toBe('ObjectOS');
+      expect(result.data.environment).toBe('development');
+    }
   });
 });
 
diff --git a/packages/spec/src/api/protocol.zod.ts b/packages/spec/src/api/protocol.zod.ts
@@ -2,7 +2,7 @@
 
 import { z } from 'zod';
 import { ViewSchema } from '../ui/view.zod';
-import { ApiRoutesSchema, ServiceInfoSchema, WellKnownCapabilitiesSchema } from './discovery.zod';
+import { DiscoverySchema } from './discovery.zod';
 import { BatchUpdateRequestSchema, BatchUpdateResponseSchema, BatchOptionsSchema } from './batch.zod';
 import { MetadataCacheRequestSchema, MetadataCacheResponseSchema } from './http-cache.zod';
 import { QuerySchema } from '../data/query.zod';
@@ -118,19 +118,24 @@ export const GetDiscoveryRequestSchema = z.object({});
 
 /**
  * Get API Discovery Response
- * Returns API version information and service availability.
+ * Derived from DiscoverySchema (single source of truth) for protocol-level use.
+ * 
+ * All fields from DiscoverySchema are available but made optional (except `version`)
+ * to support progressive disclosure and backward compatibility with existing clients.
  * 
  * - `routes` provides a flat endpoint map for client routing.
  * - `services` is the single source of truth for service availability.
- * - `capabilities` was removed — derive from `services[x].enabled`.
+ * - `apiName` is kept as an optional alias for `name` for backward compatibility.
+ * 
+ * @see DiscoverySchema in ./discovery.zod.ts — the canonical definition.
  */
-export const GetDiscoveryResponseSchema = z.object({
-  version: z.string().describe('API version (e.g., "v1", "2024-01")'),
-  apiName: z.string().describe('API name'),
-  routes: ApiRoutesSchema.optional().describe('Available endpoint paths'),
-  services: z.record(z.string(), ServiceInfoSchema).optional().describe('Per-service availability map'),
-  capabilities: WellKnownCapabilitiesSchema.optional().describe('Well-known capability flags for frontend adaptation'),
-});
+export const GetDiscoveryResponseSchema = DiscoverySchema
+  .partial()
+  .required({ version: true })
+  .extend({
+    /** @deprecated Use `name` instead. Kept for backward compatibility. */
+    apiName: z.string().optional().describe('API name (deprecated — use name)'),
+  });
 
 /**
  * Get Metadata Types Request

Original file line number	Diff line number	Diff line change
`@@ -94,7 +94,7 @@ export class ObjectStackController {`
`94`	`94`	`}`
`95`	`95`
`96`	`96`	`// --- Discovery Endpoint ---`
`97`		`- @Get()`
	`97`	`+ @Get('discovery')`
`98`	`98`	`async discovery() {`
`99`	`99`	`return { data: await this.service.dispatcher.getDiscoveryInfo('/api') };`
`100`	`100`	`}`
`@@ -241,7 +241,7 @@ export class ObjectStackController {`
`241`	`241`	`export class DiscoveryController {`
`242`	`242`	`@Get('objectstack')`
`243`	`243`	`discover(@Res() res: any) {`
`244`		`- return res.redirect('/api');`
	`244`	`+ return res.redirect('/api/discovery');`
`245`	`245`	`}`
`246`	`246`	`}`
`247`	`247`
Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ export function createRouteHandler(options: NextAdapterOptions) {`
`62`	`62`	`const method = req.method;`
`63`	`63`
`64`	`64`	`// --- 0. Discovery Endpoint ---`
`65`		`- if (segments.length === 0 && method === 'GET') {`
	`65`	`+ if (segments.length === 1 && segments[0] === 'discovery' && method === 'GET') {`
`66`	`66`	`return NextResponse.json({ data: await dispatcher.getDiscoveryInfo(options.prefix \|\| '/api') });`
`67`	`67`	`}`
`68`	`68`
`@@ -152,7 +152,7 @@ export function createDiscoveryHandler(options: NextAdapterOptions) {`
`152`	`152`	`return async function discoveryHandler(req: NextRequest) {`
`153`	`153`	`const apiPath = options.prefix \|\| '/api';`
`154`	`154`	`const url = new URL(req.url);`
`155`		`- const targetUrl = new URL(apiPath, url.origin);`
	`155`	+ const targetUrl = new URL(`${apiPath}/discovery`, url.origin);
`156`	`156`	`return NextResponse.redirect(targetUrl);`
`157`	`157`	`}`
`158`	`158`	`}`