@agent-foundry/studio 1.0.0 → 1.0.2

package/src/bff/types.ts

@@ -0,0 +1,212 @@
+/**
+ * BFF API Types
+ *
+ * Response types from the BFF Studio API endpoints.
+ * These match the Pydantic models in services/bff/app/models/studio.py
+ */
+
+import type {
+  StudioProject,
+  ProjectConfig,
+  ProjectFramework,
+} from '../types/project';
+import type {
+  DeploymentStatus,
+  DeploymentMetadata,
+  AppManifest,
+} from '../types/deployment';
+
+// =============================================================================
+// Project API Types
+// =============================================================================
+
+/**
+ * Request body for creating a project via BFF
+ */
+export interface CreateProjectRequest {
+  name: string;
+  slug: string;
+  description?: string;
+  rootPath: string;
+  framework?: ProjectFramework;
+  config?: ProjectConfig;
+  parentProjectId?: string;
+}
+
+/**
+ * Request body for updating a project via BFF
+ */
+export interface UpdateProjectRequest {
+  name?: string;
+  description?: string;
+  config?: Partial<ProjectConfig>;
+}
+
+/**
+ * Request body for forking a project via BFF
+ */
+export interface ForkProjectRequest {
+  newSlug: string;
+  newRootPath: string;
+  newName?: string;
+}
+
+/**
+ * Project response from BFF API
+ */
+export interface ProjectResponse extends StudioProject {
+  latestDeployment?: DeploymentSummary;
+}
+
+/**
+ * Paginated project list response
+ */
+export interface ProjectListResponse {
+  projects: ProjectResponse[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+// =============================================================================
+// Deployment API Types
+// =============================================================================
+
+/**
+ * Deployment summary (for lists)
+ */
+export interface DeploymentSummary {
+  id: string;
+  version: string;
+  status: DeploymentStatus;
+  ossUrl?: string;
+  bundleSizeBytes?: number;
+  createdAt: string;
+  publishedAt?: string;
+}
+
+/**
+ * Request body for starting a deployment
+ */
+export interface StartDeploymentRequest {
+  projectId: string;
+  version?: string;
+  metadata?: Partial<DeploymentMetadata>;
+}
+
+/**
+ * STS credentials for OSS upload
+ */
+export interface STSCredentials {
+  accessKeyId: string;
+  accessKeySecret: string;
+  securityToken: string;
+  expiration: string;
+}
+
+/**
+ * Response from starting a deployment
+ */
+export interface StartDeploymentResponse {
+  deploymentId: string;
+  credentials: STSCredentials;
+  bucket: string;
+  region: string;
+  keyPrefix: string;
+}
+
+/**
+ * Request body for updating deployment status
+ */
+export interface UpdateDeploymentStatusRequest {
+  status: DeploymentStatus;
+  buildLog?: string;
+  errorMessage?: string;
+  metadata?: Partial<DeploymentMetadata>;
+}
+
+/**
+ * Request body for completing a deployment
+ */
+export interface CompleteDeploymentRequest {
+  bucket: string;
+  keyPrefix: string;
+  ossUrl: string;
+  totalBytes: number;
+  fileCount: number;
+}
+
+/**
+ * Response from completing a deployment
+ */
+export interface CompleteDeploymentResponse {
+  deploymentId: string;
+  ossUrl: string;
+  version: string;
+}
+
+/**
+ * Request body for failing a deployment
+ */
+export interface FailDeploymentRequest {
+  errorMessage: string;
+  buildLog?: string;
+}
+
+/**
+ * Deployment list response
+ */
+export interface DeploymentListResponse {
+  deployments: DeploymentSummary[];
+  total: number;
+}
+
+// =============================================================================
+// Publish API Types
+// =============================================================================
+
+/**
+ * Request body for publishing to Feed
+ */
+export interface PublishRequest {
+  deploymentId?: string;
+  manifest?: AppManifest;
+  status?: 'canary' | 'stable';
+}
+
+/**
+ * Response from publishing to Feed
+ */
+export interface PublishResponse {
+  appId: string;
+  artifactId: string;
+  deploymentId: string;
+  shareUrl: string;
+  entryUrl: string;
+}
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+/**
+ * API error response
+ */
+export interface APIError {
+  detail: string;
+  code?: string;
+}
+
+/**
+ * BFF client configuration
+ */
+export interface BFFClientConfig {
+  /** BFF base URL (e.g., "http://localhost:11001") */
+  baseUrl: string;
+
+  /** Supabase JWT token for authentication */
+  authToken: string;
+
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+}

package/src/db/deployments.ts

@@ -1,7 +1,38 @@
 /**
  * Deployments Repository
  *
- * CRUD operations for studio_deployments table.
+ * Provides access to studio_deployments table via Supabase client.
+ *
+ * ## Important: Hybrid Access Pattern
+ *
+ * Due to RLS (Row Level Security) restrictions, this repository should
+ * primarily be used for **read operations only**.
+ *
+ * **For write operations, use the BFF client or DirectUploader:**
+ *
+ * ```typescript
+ * import { DirectUploader } from '@agent-foundry/studio/oss';
+ *
+ * // DirectUploader handles the complete deployment workflow via BFF
+ * const uploader = new DirectUploader({
+ *   bffBaseUrl: 'http://localhost:11001',
+ *   authToken: 'your-jwt-token',
+ * });
+ *
+ * const result = await uploader.upload({
+ *   projectId: 'project-uuid',
+ *   files: distFiles,
+ * });
+ * ```
+ *
+ * Or use the BFF client directly:
+ *
+ * ```typescript
+ * import { createBFFClient } from '@agent-foundry/studio/bff';
+ *
+ * const bff = createBFFClient({ ... });
+ * const deployment = await bff.deployments.start({ projectId: '...' });
+ * ```
  */
 
 import { SupabaseClient } from '@supabase/supabase-js';
@@ -26,6 +57,7 @@ interface DeploymentRow {
   oss_bucket: string | null;
   oss_key: string | null;
   oss_url: string | null;
+  artifact_id: string | null;
   bundle_size_bytes: number | null;
   build_log: string | null;
   error_message: string | null;
@@ -47,6 +79,7 @@ function rowToDeployment(row: DeploymentRow): Deployment {
     ossBucket: row.oss_bucket ?? undefined,
     ossKey: row.oss_key ?? undefined,
     ossUrl: row.oss_url ?? undefined,
+    artifactId: row.artifact_id ?? undefined,
     bundleSizeBytes: row.bundle_size_bytes ?? undefined,
     buildLog: row.build_log ?? undefined,
     errorMessage: row.error_message ?? undefined,
@@ -79,6 +112,12 @@ export class DeploymentsRepository {
 
   /**
    * Create a new deployment
+   *
+   * @deprecated Use `DirectUploader.upload()` or `createBFFClient().deployments.start()` instead.
+   *
+   * This method may fail with RLS errors. The recommended workflow is:
+   * 1. Use DirectUploader which handles the complete deployment lifecycle
+   * 2. Or use BFF client's deployments.start() to get STS credentials
    */
   async create(input: CreateDeploymentInput): Promise<Deployment> {
     const { data: { user } } = await this.supabase.auth.getUser();
@@ -168,6 +207,10 @@ export class DeploymentsRepository {
 
   /**
    * Update a deployment
+   *
+   * @deprecated Use `createBFFClient().deployments.updateStatus()` instead.
+   *
+   * This method may fail with RLS errors. Use BFF client for write operations.
    */
   async update(id: string, input: UpdateDeploymentInput): Promise<Deployment> {
     const updateData: Record<string, unknown> = {};
@@ -221,6 +264,8 @@ export class DeploymentsRepository {
 
   /**
    * Mark deployment as building
+   *
+   * @deprecated Use `createBFFClient().deployments.updateStatus()` instead.
    */
   async markBuilding(id: string): Promise<Deployment> {
     return this.update(id, { status: 'building' });
@@ -228,6 +273,8 @@ export class DeploymentsRepository {
 
   /**
    * Mark deployment as uploading
+   *
+   * @deprecated Use `createBFFClient().deployments.updateStatus()` instead.
    */
   async markUploading(id: string): Promise<Deployment> {
     return this.update(id, { status: 'uploading' });
@@ -235,6 +282,8 @@ export class DeploymentsRepository {
 
   /**
    * Mark deployment as published
+   *
+   * @deprecated Use `createBFFClient().deployments.complete()` instead.
    */
   async markPublished(
     id: string,
@@ -252,6 +301,8 @@ export class DeploymentsRepository {
 
   /**
    * Mark deployment as failed
+   *
+   * @deprecated Use `createBFFClient().deployments.fail()` instead.
    */
   async markFailed(id: string, errorMessage: string, buildLog?: string): Promise<Deployment> {
     return this.update(id, {
@@ -286,6 +337,9 @@ export class DeploymentsRepository {
 
   /**
    * Delete a deployment
+   *
+   * @deprecated Deployment deletion should be handled server-side.
+   * This method may fail with RLS errors.
    */
   async delete(id: string): Promise<void> {
     const { error } = await this.supabase
@@ -300,6 +354,9 @@ export class DeploymentsRepository {
 
   /**
    * Append to build log
+   *
+   * @deprecated Use `createBFFClient().deployments.updateStatus()` with buildLog field.
+   * This method may fail with RLS errors.
    */
   async appendBuildLog(id: string, logLine: string): Promise<void> {
     const existing = await this.getById(id);
@@ -313,4 +370,45 @@ export class DeploymentsRepository {
 
     await this.update(id, { buildLog: newLog });
   }
+
+  /**
+   * Link deployment to an artifact (called after publishing to Feed)
+   *
+   * @deprecated This is handled automatically by BFF's publish workflow.
+   * Use `createBFFClient().projects.publish()` instead.
+   */
+  async linkToArtifact(id: string, artifactId: string): Promise<Deployment> {
+    const { data, error } = await this.supabase
+      .from(this.TABLE)
+      .update({ artifact_id: artifactId })
+      .eq('id', id)
+      .select()
+      .single();
+
+    if (error) {
+      throw new Error(`Failed to link deployment to artifact: ${error.message}`);
+    }
+
+    return rowToDeployment(data as DeploymentRow);
+  }
+
+  /**
+   * Get deployment by artifact ID
+   */
+  async getByArtifactId(artifactId: string): Promise<Deployment | null> {
+    const { data, error } = await this.supabase
+      .from(this.TABLE)
+      .select()
+      .eq('artifact_id', artifactId)
+      .single();
+
+    if (error) {
+      if (error.code === 'PGRST116') {
+        return null; // Not found
+      }
+      throw new Error(`Failed to get deployment: ${error.message}`);
+    }
+
+    return rowToDeployment(data as DeploymentRow);
+  }
 }

package/src/db/index.ts

@@ -1,5 +1,22 @@
 /**
  * Database module - Supabase client for Studio
+ *
+ * ## Important: Read-Only Usage Recommended
+ *
+ * Due to RLS (Row Level Security), this module should primarily be used
+ * for **read operations only**. For write operations, use the BFF client:
+ *
+ * ```typescript
+ * // Read operations - use this module
+ * import { createStudioClient } from '@agent-foundry/studio/db';
+ * const db = createStudioClient({ supabaseUrl: '...', supabaseKey: '...' });
+ * const projects = await db.projects.list();
+ *
+ * // Write operations - use BFF client
+ * import { createBFFClient } from '@agent-foundry/studio/bff';
+ * const bff = createBFFClient({ baseUrl: '...', authToken: '...' });
+ * const project = await bff.projects.create({ ... });
+ * ```
  */
 
 export { createStudioClient, type StudioClientConfig } from './client';

package/src/db/projects.ts

@@ -1,7 +1,29 @@
 /**
  * Projects Repository
  *
- * CRUD operations for studio_projects table.
+ * Provides access to studio_projects table via Supabase client.
+ *
+ * ## Important: Hybrid Access Pattern
+ *
+ * Due to RLS (Row Level Security) restrictions, this repository should
+ * primarily be used for **read operations only**.
+ *
+ * **For write operations (create, update, delete, fork), use the BFF client:**
+ *
+ * ```typescript
+ * import { createBFFClient } from '@agent-foundry/studio/bff';
+ *
+ * const bff = createBFFClient({
+ *   baseUrl: 'http://localhost:11001',
+ *   authToken: 'your-jwt-token',
+ * });
+ *
+ * // Create project via BFF (recommended)
+ * const project = await bff.projects.create({ ... });
+ * ```
+ *
+ * The BFF uses service_role credentials which bypass RLS, ensuring
+ * consistent and secure write operations.
  */
 
 import { SupabaseClient } from '@supabase/supabase-js';
@@ -22,6 +44,7 @@ interface ProjectRow {
   name: string;
   slug: string;
   description: string | null;
+  app_id: string | null;
   root_path: string;
   framework: string;
   config: ProjectConfig;
@@ -40,6 +63,7 @@ function rowToProject(row: ProjectRow): StudioProject {
     name: row.name,
     slug: row.slug,
     description: row.description ?? undefined,
+    appId: row.app_id ?? undefined,
     rootPath: row.root_path,
     framework: row.framework as StudioProject['framework'],
     config: row.config,
@@ -59,6 +83,11 @@ export class ProjectsRepository {
 
   /**
    * Create a new project
+   *
+   * @deprecated Use BFF client instead: `createBFFClient().projects.create()`
+   *
+   * This method may fail with RLS errors when using anon key.
+   * The BFF client uses service_role credentials which bypass RLS.
    */
   async create(input: CreateProjectInput): Promise<StudioProject> {
     const { data: { user } } = await this.supabase.auth.getUser();
@@ -169,6 +198,11 @@ export class ProjectsRepository {
 
   /**
    * Update a project
+   *
+   * @deprecated Use BFF client instead: `createBFFClient().projects.update()`
+   *
+   * This method may fail with RLS errors when using anon key.
+   * The BFF client uses service_role credentials which bypass RLS.
    */
   async update(id: string, input: UpdateProjectInput): Promise<StudioProject> {
     const updateData: Record<string, unknown> = {};
@@ -204,6 +238,11 @@ export class ProjectsRepository {
 
   /**
    * Delete a project
+   *
+   * @deprecated Use BFF client instead: `createBFFClient().projects.delete()`
+   *
+   * This method may fail with RLS errors when using anon key.
+   * The BFF client uses service_role credentials which bypass RLS.
    */
   async delete(id: string): Promise<void> {
     const { error } = await this.supabase
@@ -218,6 +257,11 @@ export class ProjectsRepository {
 
   /**
    * Fork a project (create a copy)
+   *
+   * @deprecated Use BFF client instead: `createBFFClient().projects.fork()`
+   *
+   * This method may fail with RLS errors when using anon key.
+   * The BFF client uses service_role credentials which bypass RLS.
    */
   async fork(id: string, newSlug: string, newRootPath: string): Promise<StudioProject> {
     const original = await this.getById(id);
@@ -243,4 +287,45 @@ export class ProjectsRepository {
     const existing = await this.getBySlug(slug);
     return existing === null;
   }
+
+  /**
+   * Link project to a registered app (called after publishing to Feed)
+   *
+   * @deprecated This is handled automatically by BFF's publish workflow.
+   * Use `createBFFClient().projects.publish()` instead.
+   */
+  async linkToApp(id: string, appId: string): Promise<StudioProject> {
+    const { data, error } = await this.supabase
+      .from(this.TABLE)
+      .update({ app_id: appId })
+      .eq('id', id)
+      .select()
+      .single();
+
+    if (error) {
+      throw new Error(`Failed to link project to app: ${error.message}`);
+    }
+
+    return rowToProject(data as ProjectRow);
+  }
+
+  /**
+   * Get project by app ID
+   */
+  async getByAppId(appId: string): Promise<StudioProject | null> {
+    const { data, error } = await this.supabase
+      .from(this.TABLE)
+      .select()
+      .eq('app_id', appId)
+      .single();
+
+    if (error) {
+      if (error.code === 'PGRST116') {
+        return null; // Not found
+      }
+      throw new Error(`Failed to get project: ${error.message}`);
+    }
+
+    return rowToProject(data as ProjectRow);
+  }
 }

package/src/db/schema.sql

@@ -1,22 +1,18 @@
 -- =============================================================================
--- Agent Foundry Studio Database Schema
+-- Agent Foundry Studio Database Schema (Reference)
 -- =============================================================================
--- This schema defines tables for managing Studio projects and deployments.
--- Run this migration against your Supabase PostgreSQL database.
+-- This is a REFERENCE file showing the schema design.
+-- Actual migrations are managed via Alembic in services/bff/alembic/versions/
 --
--- Prerequisites:
--- 1. Enable uuid-ossp extension: CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
--- 2. Supabase Auth must be configured (auth.users table exists)
+-- See: 005_add_studio_tables.py for the actual migration
 -- =============================================================================
 
--- Enable UUID extension if not already enabled
-CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-
 -- =============================================================================
 -- Studio Projects
 -- =============================================================================
 -- Represents a React/Vite project created and managed in Build Studio.
 -- Each project belongs to a user and can optionally be forked from another project.
+-- After first publish to Feed, links to an apps entry via app_id.
 
 CREATE TABLE IF NOT EXISTS studio_projects (
     id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
@@ -29,6 +25,9 @@ CREATE TABLE IF NOT EXISTS studio_projects (
     slug VARCHAR(255) NOT NULL,
     description TEXT,
     
+    -- Link to registered app (set after first publish to Feed)
+    app_id VARCHAR(255) REFERENCES apps(id) ON DELETE SET NULL,
+    
     -- Local development
     root_path TEXT NOT NULL,  -- Local filesystem path to project root
     
@@ -44,35 +43,21 @@ CREATE TABLE IF NOT EXISTS studio_projects (
     updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     
     -- Ensure slug is unique per user
-    CONSTRAINT unique_user_slug UNIQUE (user_id, slug)
+    CONSTRAINT uq_studio_projects_user_slug UNIQUE (user_id, slug)
 );
 
--- Index for user's projects
+-- Indexes
 CREATE INDEX IF NOT EXISTS idx_studio_projects_user_id ON studio_projects(user_id);
-
--- Index for finding forks
-CREATE INDEX IF NOT EXISTS idx_studio_projects_parent ON studio_projects(parent_project_id);
-
--- Trigger to auto-update updated_at
-CREATE OR REPLACE FUNCTION update_studio_projects_updated_at()
-RETURNS TRIGGER AS $$
-BEGIN
-    NEW.updated_at = NOW();
-    RETURN NEW;
-END;
-$$ LANGUAGE plpgsql;
-
-DROP TRIGGER IF EXISTS trigger_studio_projects_updated_at ON studio_projects;
-CREATE TRIGGER trigger_studio_projects_updated_at
-    BEFORE UPDATE ON studio_projects
-    FOR EACH ROW
-    EXECUTE FUNCTION update_studio_projects_updated_at();
+CREATE INDEX IF NOT EXISTS idx_studio_projects_app_id ON studio_projects(app_id) WHERE app_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_studio_projects_parent ON studio_projects(parent_project_id) WHERE parent_project_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_studio_projects_created ON studio_projects(created_at DESC);
 
 -- =============================================================================
 -- Studio Deployments
 -- =============================================================================
 -- Represents a build and upload of a project to Alibaba Cloud OSS.
 -- Tracks the full lifecycle: pending -> building -> uploading -> published/failed
+-- When published to Feed, links to an artifact entry via artifact_id.
 
 CREATE TABLE IF NOT EXISTS studio_deployments (
     id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
@@ -93,6 +78,9 @@ CREATE TABLE IF NOT EXISTS studio_deployments (
     oss_key TEXT,
     oss_url TEXT,
     
+    -- Link to artifact (set when publishing to Feed)
+    artifact_id UUID REFERENCES artifacts(id) ON DELETE SET NULL,
+    
     -- Metrics
     bundle_size_bytes BIGINT,
     
@@ -108,49 +96,44 @@ CREATE TABLE IF NOT EXISTS studio_deployments (
     published_at TIMESTAMPTZ
 );
 
--- Index for project's deployments
+-- Indexes
 CREATE INDEX IF NOT EXISTS idx_studio_deployments_project_id ON studio_deployments(project_id);
-
--- Index for user's deployments
 CREATE INDEX IF NOT EXISTS idx_studio_deployments_user_id ON studio_deployments(user_id);
-
--- Index for filtering by status
 CREATE INDEX IF NOT EXISTS idx_studio_deployments_status ON studio_deployments(status);
-
--- Composite index for recent deployments by project
-CREATE INDEX IF NOT EXISTS idx_studio_deployments_project_created 
-    ON studio_deployments(project_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_studio_deployments_artifact ON studio_deployments(artifact_id) WHERE artifact_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_studio_deployments_project_created ON studio_deployments(project_id, created_at DESC);
 
 -- =============================================================================
 -- Row Level Security (RLS) Policies
 -- =============================================================================
--- Enable RLS to ensure users can only access their own data.
 
--- Enable RLS on both tables
 ALTER TABLE studio_projects ENABLE ROW LEVEL SECURITY;
 ALTER TABLE studio_deployments ENABLE ROW LEVEL SECURITY;
 
 -- Projects: Users can only see/modify their own projects
-DROP POLICY IF EXISTS studio_projects_user_policy ON studio_projects;
-CREATE POLICY studio_projects_user_policy ON studio_projects
+CREATE POLICY studio_projects_owner_all ON studio_projects
     FOR ALL
     USING (auth.uid() = user_id)
     WITH CHECK (auth.uid() = user_id);
 
 -- Deployments: Users can only see/modify their own deployments
-DROP POLICY IF EXISTS studio_deployments_user_policy ON studio_deployments;
-CREATE POLICY studio_deployments_user_policy ON studio_deployments
+CREATE POLICY studio_deployments_owner_all ON studio_deployments
     FOR ALL
     USING (auth.uid() = user_id)
     WITH CHECK (auth.uid() = user_id);
 
 -- =============================================================================
--- Comments
+-- Integration with Existing Tables
+-- =============================================================================
+--
+-- When a project is published to Feed:
+-- 1. Create/update entry in `apps` table
+-- 2. Create `app_versions` record
+-- 3. Create `artifacts` record with:
+--    - type = 'bundle'
+--    - bucket = 'external'
+--    - object_path = OSS URL
+-- 4. Link deployment to artifact via artifact_id
+-- 5. Link project to app via app_id
+--
 -- =============================================================================
-
-COMMENT ON TABLE studio_projects IS 'React/Vite projects created in Agent Foundry Build Studio';
-COMMENT ON COLUMN studio_projects.root_path IS 'Local filesystem path - only valid on the machine where project was created';
-COMMENT ON COLUMN studio_projects.config IS 'JSON config: buildCommand, outputDir, envVars, baseUrl, viteConfig';
-
-COMMENT ON TABLE studio_deployments IS 'Build and deployment history to Alibaba Cloud OSS';
-COMMENT ON COLUMN studio_deployments.metadata IS 'JSON metadata: commitHash, branch, buildDurationMs, uploadDurationMs, fileCount';