feat(datasource): read-only introspection routes for Studio sync

Expose the external-datasource introspection service over REST so Studio can
list a datasource's remote tables and preview the object definition they would
become:

- GET  /api/v1/datasources/:name/remote-tables  → listRemoteTables()
- POST /api/v1/datasources/:name/object-draft    → generateObjectDraft(table)

Both are read-only (introspect + type-map; no persistence) — the caller creates
the object through the normal metadata channel. Degrade to 503 when the
external-datasource service isn't wired; 400 when the table is missing.

Verified live against a seeded SQLite datasource (customers/orders →
remote-tables lists both; object-draft yields a typed object definition).
Tests: remote-tables list + object-draft (200 + 400-without-table).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

packages/services/service-datasource/src/__tests__/admin-routes.test.ts

@@ -54,6 +54,28 @@ describe('registerDatasourceAdminRoutes (real HonoHttpServer)', () => {
     expect(sqlite!.configSchema?.properties?.filename?.type).toBe('string');
   });
 
+  it('GET /api/v1/datasources/:name/remote-tables lists remote tables', async () => {
+    const listRemoteTables = vi.fn().mockResolvedValue([{ name: 'customers', columnCount: 4 }]);
+    const app = mount({ listRemoteTables });
+    const res = await app.fetch(json('/api/v1/datasources/demo_ext/remote-tables'));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ tables: [{ name: 'customers', columnCount: 4 }] });
+    expect(listRemoteTables).toHaveBeenCalledWith('demo_ext');
+  });
+
+  it('POST /api/v1/datasources/:name/object-draft generates a draft (400 without table)', async () => {
+    const generateObjectDraft = vi.fn().mockResolvedValue({ name: 'customers', definition: { fields: { id: {} } } });
+    const app = mount({ generateObjectDraft });
+
+    const missing = await app.fetch(json('/api/v1/datasources/demo_ext/object-draft', { method: 'POST', body: JSON.stringify({}) }));
+    expect(missing.status).toBe(400);
+
+    const ok = await app.fetch(json('/api/v1/datasources/demo_ext/object-draft', { method: 'POST', body: JSON.stringify({ table: 'customers' }) }));
+    expect(ok.status).toBe(200);
+    expect((await ok.json()).draft.name).toBe('customers');
+    expect(generateObjectDraft).toHaveBeenCalledWith('demo_ext', 'customers', {});
+  });
+
   it('POST /api/v1/datasources/test splits the inline secret out of the draft', async () => {
     const testConnection = vi.fn().mockResolvedValue({ ok: true });
     const app = mount({ testConnection });

packages/services/service-datasource/src/admin-routes.ts

@@ -37,6 +37,14 @@ export function registerDatasourceAdminRoutes(
     }
   };
 
+  const externalService = (): any => {
+    try {
+      return ctx.getService<any>('external-datasource');
+    } catch {
+      return undefined;
+    }
+  };
+
   const unavailable = (res: any) =>
     res.status(503).json({ error: 'datasource_admin_unavailable' });
 
@@ -71,6 +79,35 @@ export function registerDatasourceAdminRoutes(
     res.json({ drivers: DRIVER_CATALOG });
   });
 
+  // Read-only schema introspection for the Studio "sync objects" flow.
+  // `GET /datasources/:name/remote-tables` lists the datasource's remote tables;
+  // `POST /datasources/:name/object-draft` generates an ObjectStack object
+  // definition draft for one table (introspect + type-map, no persistence —
+  // the caller creates the object through the normal metadata channel).
+  server.get(`${root}/:name/remote-tables`, async (req: any, res: any) => {
+    const svc = externalService();
+    if (!svc?.listRemoteTables) return unavailable(res);
+    try {
+      const tables = await svc.listRemoteTables(req.params.name);
+      res.json({ tables });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+
+  server.post(`${root}/:name/object-draft`, async (req: any, res: any) => {
+    const svc = externalService();
+    if (!svc?.generateObjectDraft) return unavailable(res);
+    const { table, ...opts } = (req.body as Record<string, unknown>) ?? {};
+    if (!table) return badRequest(res, new Error('Body field "table" is required.'));
+    try {
+      const draft = await svc.generateObjectDraft(req.params.name, String(table), opts);
+      res.json({ draft });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+
   // Probe a connection without persisting anything. Registered before the
   // `:name` routes so the literal `test` segment is never captured as a name.
   server.post(`${root}/test`, async (req: any, res: any) => {