feat(api-console): add per-project API Console with scoped discovery and endpoint execution

Author: hotlong

apps/studio/src/components/ApiConsolePage.tsx

@@ -63,9 +63,9 @@ interface RequestHistoryEntry {
 
 let nextParamId = 1;
 
-export function ApiConsolePage() {
+export function ApiConsolePage({ projectId }: { projectId?: string } = {}) {
   const client = useClient();
-  const { groups, loading: discovering, refresh } = useApiDiscovery();
+  const { groups, loading: discovering, refresh } = useApiDiscovery(projectId);
 
   const [searchQuery, setSearchQuery] = useState('');
   const [expandedGroups, setExpandedGroups] = useState<Set<string>>(new Set());

apps/studio/src/components/app-sidebar.tsx

@@ -528,8 +528,15 @@ export function AppSidebar({
               <SidebarMenuItem>
                 <SidebarMenuButton
                   tooltip="API Console"
-                  isActive={location.pathname === '/api-console'}
-                  onClick={() => navigate({ to: '/api-console' })}
+                  isActive={location.pathname.endsWith('/api-console')}
+                  onClick={() => {
+                    const projectId = params.projectId as string | undefined;
+                    if (projectId) {
+                      navigate({ to: '/projects/$projectId/api-console', params: { projectId } });
+                    } else {
+                      navigate({ to: '/api-console' });
+                    }
+                  }}
                 >
                   <Globe className="h-4 w-4" />
                   <span>API Console</span>
@@ -541,8 +548,8 @@ export function AppSidebar({
                   isActive={location.pathname.endsWith('/packages')}
                   onClick={() => {
                     const projectId = params.projectId as string | undefined;
-                    if (envId) {
-                      navigate({ to: '/projects/$projectId/packages', params: { projectId: envId } });
+                    if (projectId) {
+                      navigate({ to: '/projects/$projectId/packages', params: { projectId } });
                     } else {
                       navigate({ to: '/projects' });
                     }

apps/studio/src/components/new-project-dialog.tsx

@@ -14,7 +14,31 @@
  */
 
 import { useEffect, useState } from 'react';
-import type { Project } from '@objectstack/spec/cloud';
+/**
+ * Canonical project row shape returned by the HTTP API.
+ *
+ * The dispatcher returns raw ObjectQL rows (snake_case column names) — no
+ * camelCase translation layer. See `packages/runtime/src/http-dispatcher.ts`
+ * `cleanProjectRow()`.
+ */
+type ProjectRow = {
+  id: string;
+  organization_id: string;
+  display_name: string;
+  is_default?: boolean;
+  is_system?: boolean;
+  status?: string;
+  plan?: string;
+  created_by?: string;
+  created_at?: string;
+  updated_at?: string;
+  database_url?: string;
+  database_driver?: string;
+  storage_limit_mb?: number;
+  provisioned_at?: string;
+  hostname?: string;
+  metadata?: Record<string, unknown>;
+};
 import {
   Dialog,
   DialogContent,
@@ -40,7 +64,7 @@ import { useActiveOrganizationId, useSession } from '@/hooks/useSession';
 export interface NewProjectDialogProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
-  onCreated?: (env: Project) => void;
+  onCreated?: (env: ProjectRow) => void;
 }
 
 export function NewProjectDialog({
@@ -84,15 +108,15 @@ export function NewProjectDialog({
     }
     try {
       const res = await provision({
-        organizationId: activeOrgId,
-        createdBy: user?.id ?? '__session__',
-        displayName: displayName.trim(),
+        organization_id: activeOrgId,
+        created_by: user?.id ?? '__session__',
+        display_name: displayName.trim(),
         driver: driver || undefined,
       } as any);
-      const project = (res?.project ?? res) as Project;
+      const project = (res?.project ?? res) as ProjectRow;
       toast({
         title: 'Project provisioned',
-        description: `${project.displayName} is ready.`,
+        description: `${project.display_name} is ready.`,
       });
       reset();
       onOpenChange(false);

apps/studio/src/components/production-guard.tsx

@@ -65,17 +65,17 @@ export interface GuardOptions {
   /** Visual variant of the confirm button. Defaults to "destructive". */
   confirmVariant?: 'default' | 'destructive';
   /**
-   * If true, the user must type the project's displayName (or slug) to
+   * If true, the user must type the project's display_name (or slug) to
    * enable the confirm button. Use for the most destructive operations.
    */
   requireTypedConfirmation?: boolean;
-  /** The displayName/slug the user must type when requireTypedConfirmation. */
+  /** The display_name/slug the user must type when requireTypedConfirmation. */
   typedConfirmationValue?: string;
 }
 
 interface ActiveProjectSnapshot {
   projectType: ProjectType | undefined;
-  displayName?: string;
+  display_name?: string;
 }
 
 interface ProductionGuardContextValue {
@@ -135,7 +135,7 @@ export function ProductionGuardProvider({ children }: { children: ReactNode }) {
   );
 
   const expectedPhrase =
-    opts?.typedConfirmationValue ?? active.displayName ?? '';
+    opts?.typedConfirmationValue ?? active.display_name ?? '';
   const typedOk =
     !opts?.requireTypedConfirmation || typed.trim() === expectedPhrase.trim();
 
@@ -163,7 +163,7 @@ export function ProductionGuardProvider({ children }: { children: ReactNode }) {
           <div className="my-2 flex items-center gap-2 rounded-md border border-red-500/30 bg-red-500/5 p-3 text-sm">
             <ProjectBadge projectType="production" />
             <span className="font-medium">
-              {active.displayName ?? 'Production project'}
+              {active.display_name ?? 'Production project'}
             </span>
           </div>
 

apps/studio/src/components/project-switcher.tsx

@@ -52,7 +52,7 @@ export function ProjectSwitcher() {
     if (!q) return projects;
     return projects.filter(
       (e) =>
-        e.displayName.toLowerCase().includes(q) ||
+        e.display_name.toLowerCase().includes(q) ||
         e.id.toLowerCase().includes(q),
     );
   }, [projects, search]);
@@ -77,7 +77,7 @@ export function ProjectSwitcher() {
           >
             {active ? (
               <span className="max-w-[160px] truncate">
-                {active.displayName}
+                {active.display_name}
               </span>
             ) : (
               <span className="text-muted-foreground">
@@ -123,9 +123,9 @@ export function ProjectSwitcher() {
                 <div className="flex-1 min-w-0">
                   <div className="flex items-center gap-2">
                     <span className="truncate font-medium">
-                      {env.displayName}
+                      {env.display_name}
                     </span>
-                    {env.isDefault && (
+                    {env.is_default && (
                       <Badge
                         variant="outline"
                         className="h-4 px-1 text-[9px]"

apps/studio/src/hooks/use-api-discovery.ts

@@ -2,6 +2,7 @@
 
 import { useState, useEffect, useCallback } from 'react';
 import { useClient } from '@objectstack/client-react';
+import { useScopedClient } from './useObjectStackClient';
 
 // ─── Types ──────────────────────────────────────────────────────────
 
@@ -35,13 +36,6 @@ interface ServiceEndpointEntry {
 /** Metadata types that should be excluded from the endpoint tree */
 const EXCLUDED_META_TYPES = ['plugin', 'plugins', 'kind', 'package'];
 
-const SYSTEM_ENDPOINTS: EndpointDef[] = [
-  { method: 'GET', path: '/api/v1/discovery', desc: 'API Discovery', group: 'System' },
-  { method: 'GET', path: '/api/v1/meta/types', desc: 'List metadata types', group: 'Metadata' },
-  { method: 'GET', path: '/api/v1/packages', desc: 'List packages', group: 'System' },
-  { method: 'GET', path: '/api/v1/health', desc: 'Health check', group: 'System' },
-];
-
 /** Build auth endpoints from the discovered auth base path. */
 function buildAuthEndpoints(authBase: string): EndpointDef[] {
   return [
@@ -194,25 +188,41 @@ export function buildServiceEndpoints(serviceName: string, routePrefix: string):
 
 // ─── Hook ───────────────────────────────────────────────────────────
 
-export function useApiDiscovery() {
-  const client = useClient();
+export function useApiDiscovery(projectId?: string) {
+  const unscopedClient = useClient();
+  const scopedClient = useScopedClient(projectId);
+  const client: any = projectId ? scopedClient : unscopedClient;
   const [groups, setGroups] = useState<EndpointGroup[]>([]);
   const [allEndpoints, setAllEndpoints] = useState<EndpointDef[]>([]);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
 
   const discover = useCallback(async () => {
+    // When projectId is provided but the scoped client hasn't resolved yet,
+    // defer until the next render.
+    if (projectId && !scopedClient) return;
+
     setLoading(true);
     setError(null);
 
+    // Scope prefix for system endpoints; discovery already handles its own routes.
+    const scopePrefix = projectId ? `/api/v1/projects/${projectId}` : '/api/v1';
+    const discoveryUrl = `${scopePrefix}/discovery`;
+    const systemEndpoints: EndpointDef[] = [
+      { method: 'GET', path: discoveryUrl, desc: 'API Discovery', group: 'System' },
+      { method: 'GET', path: `${scopePrefix}/meta/types`, desc: 'List metadata types', group: 'Metadata' },
+      { method: 'GET', path: `${scopePrefix}/packages`, desc: 'List packages', group: 'System' },
+      { method: 'GET', path: '/api/v1/health', desc: 'Health check', group: 'System' },
+    ];
+
     try {
       // 1. Fetch discovery response — the source of truth for available services
       let authBase = '/api/v1/auth';
       let discoveredServices: Record<string, { enabled: boolean; route?: string }> = {};
       let discoveredRoutes: Record<string, string> = {};
 
       try {
-        const discRes = await fetch('/api/v1/discovery');
+        const discRes = await fetch(discoveryUrl);
         if (discRes.ok) {
           const discData = await discRes.json();
           const data = discData?.data ?? discData;
@@ -238,10 +248,15 @@ export function useApiDiscovery() {
         const hasHandler = serviceInfo?.handlerReady
           ?? (serviceInfo?.status === 'available' || serviceInfo?.status === 'degraded');
 
-        // Use route from discovery services, discovery routes map, or catalog default
-        const routePrefix = serviceInfo?.route
+        // Use route from discovery services, discovery routes map, or catalog default.
+        // When in a project scope, rewrite unscoped catalog defaults so they include
+        // the /projects/:projectId segment.
+        const rawRoute = serviceInfo?.route
           ?? discoveredRoutes[serviceName]
           ?? catalog.defaultRoute;
+        const routePrefix = projectId && rawRoute.startsWith('/api/v1/') && !rawRoute.includes('/projects/')
+          ? rawRoute.replace('/api/v1/', `/api/v1/projects/${projectId}/`)
+          : rawRoute;
 
         if (isEnabled && hasHandler) {
           serviceEndpoints.push(...buildServiceEndpoints(serviceName, routePrefix));
@@ -279,34 +294,34 @@ export function useApiDiscovery() {
 
       // 5. Build dynamic data endpoints for each object
       const dataEndpoints: EndpointDef[] = objectNames.flatMap(name => [
-        { method: 'GET' as HttpMethod, path: `/api/v1/data/${name}`, desc: `List ${name}`, group: `Data: ${name}` },
-        { method: 'POST' as HttpMethod, path: `/api/v1/data/${name}`, desc: `Create ${name}`, group: `Data: ${name}`, bodyTemplate: { name: 'example' } },
-        { method: 'GET' as HttpMethod, path: `/api/v1/data/${name}/:id`, desc: `Get ${name} by ID`, group: `Data: ${name}` },
-        { method: 'PATCH' as HttpMethod, path: `/api/v1/data/${name}/:id`, desc: `Update ${name}`, group: `Data: ${name}`, bodyTemplate: { name: 'updated' } },
-        { method: 'DELETE' as HttpMethod, path: `/api/v1/data/${name}/:id`, desc: `Delete ${name}`, group: `Data: ${name}` },
+        { method: 'GET' as HttpMethod, path: `${scopePrefix}/data/${name}`, desc: `List ${name}`, group: `Data: ${name}` },
+        { method: 'POST' as HttpMethod, path: `${scopePrefix}/data/${name}`, desc: `Create ${name}`, group: `Data: ${name}`, bodyTemplate: { name: 'example' } },
+        { method: 'GET' as HttpMethod, path: `${scopePrefix}/data/${name}/:id`, desc: `Get ${name} by ID`, group: `Data: ${name}` },
+        { method: 'PATCH' as HttpMethod, path: `${scopePrefix}/data/${name}/:id`, desc: `Update ${name}`, group: `Data: ${name}`, bodyTemplate: { name: 'updated' } },
+        { method: 'DELETE' as HttpMethod, path: `${scopePrefix}/data/${name}/:id`, desc: `Delete ${name}`, group: `Data: ${name}` },
       ]);
 
       // 6. Build metadata endpoints for each type
       const metaEndpoints: EndpointDef[] = metaTypes
         .filter(t => !EXCLUDED_META_TYPES.includes(t))
         .map(type => ({
           method: 'GET' as HttpMethod,
-          path: `/api/v1/meta/${type}`,
+          path: `${scopePrefix}/meta/${type}`,
           desc: `List ${type} metadata`,
           group: 'Metadata',
         }));
 
       // 7. Build per-object schema endpoints
       const schemaEndpoints: EndpointDef[] = objectNames.map(name => ({
         method: 'GET' as HttpMethod,
-        path: `/api/v1/meta/object/${name}`,
+        path: `${scopePrefix}/meta/object/${name}`,
         desc: `${name} schema`,
         group: 'Metadata',
       }));
 
       // 8. Combine all endpoints
       const all = [
-        ...SYSTEM_ENDPOINTS,
+        ...systemEndpoints,
         ...buildAuthEndpoints(authBase),
         ...serviceEndpoints,
         ...metaEndpoints,
@@ -346,7 +361,7 @@ export function useApiDiscovery() {
     } finally {
       setLoading(false);
     }
-  }, [client]);
+  }, [client, projectId, scopedClient]);
 
   useEffect(() => { discover(); }, [discover]);
 

apps/studio/src/hooks/useProjects.ts

@@ -12,13 +12,56 @@
 
 import { useCallback, useEffect, useState } from 'react';
 import { useClient } from '@objectstack/client-react';
-import type { Project, ProjectDatabase, ProjectMember } from '@objectstack/spec/cloud';
 import { useActiveOrganizationId } from '@/hooks/useSession';
 
+/**
+ * Snake_case database metadata as returned by the HTTP dispatcher under
+ * `GET /cloud/projects/:id`. See `http-dispatcher.ts` (the `database` block
+ * it builds alongside the project row).
+ */
+export interface ProjectDatabaseRow {
+  driver?: string;
+  database_name?: string;
+  database_url?: string;
+  storage_limit_mb?: number;
+  provisioned_at?: string;
+}
+
+export interface ProjectMembershipRow {
+  role?: string;
+  user_id?: string;
+  project_id?: string;
+}
+
+/**
+ * Canonical project row shape returned by the HTTP API (snake_case).
+ *
+ * The dispatcher returns raw ObjectQL rows; Studio consumes them verbatim
+ * with no camelCase translation.
+ */
+export interface ProjectRow {
+  id: string;
+  organization_id: string;
+  display_name: string;
+  is_default?: boolean;
+  is_system?: boolean;
+  status?: string;
+  plan?: string;
+  created_by?: string;
+  created_at?: string;
+  updated_at?: string;
+  database_url?: string;
+  database_driver?: string;
+  storage_limit_mb?: number;
+  provisioned_at?: string;
+  hostname?: string;
+  metadata?: Record<string, unknown>;
+}
+
 export interface ProjectDetail {
-  project: Project;
-  database?: ProjectDatabase;
-  membership?: ProjectMember;
+  project: ProjectRow;
+  database?: ProjectDatabaseRow;
+  membership?: ProjectMembershipRow;
   credential?: { id: string; status: string; activatedAt?: string };
   organization?: { id: string; name: string; displayName?: string };
 }
@@ -50,7 +93,7 @@ export function recallActiveProject(): string | null {
 export function useProjects() {
   const client = useClient() as any;
   const activeOrgId = useActiveOrganizationId();
-  const [projects, setProjects] = useState<Project[]>([]);
+  const [projects, setProjects] = useState<ProjectRow[]>([]);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -63,8 +106,8 @@ export function useProjects() {
     setLoading(true);
     setError(null);
     try {
-      const result = await client.projects.list({ organizationId: activeOrgId });
-      setProjects((result?.projects as Project[]) ?? []);
+      const result = await client.projects.list({ organization_id: activeOrgId });
+      setProjects((result?.projects as ProjectRow[]) ?? []);
     } catch (err) {
       setError(err as Error);
       setProjects([]);