feat(upload): add --screen-id flag for uploading by screen ID

Support uploading testcases and specs using screen_id as an alternative
to frame-id/file-key. This adds GraphQL queries to resolve frames by
screen_id and validates that --screen-id is mutually exclusive with
--frame-id and --file-key.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ducnv-1960

cmd/upload_specs.go

@@ -26,6 +26,7 @@ var (
 	specFrameID         string
 	specFileKey         string
 	specFrameName       string
+	specScreenID        string
 )
 
 // CSV columns are mapped to spec fields:
@@ -51,6 +52,8 @@ Two frame ID formats are supported:
 
 When using a Figma frame ID, the Figma file key is inferred from the path
 convention .momorph/specs/{file_key}/... or supplied via --file-key.
+
+Alternatively, use --screen-id to upload by screen ID instead of frame ID.
 `,
 	Example: `  # Upload using MoMorph integer frame ID in filename
   momorph upload specs 7323-iOS-Home.csv
@@ -64,6 +67,9 @@ convention .momorph/specs/{file_key}/... or supplied via --file-key.
   # Upload with explicit Figma frame ID and file key
   momorph upload specs ~/data/my-specs.csv --frame-id=70:1214 --file-key=Dhz3zTL0vjaOTDGUIHugQe
 
+  # Upload using screen ID
+  momorph upload specs ~/data/my-specs.csv --screen-id=42
+
   # Upload all CSV files in a directory recursively
   momorph upload specs --dir ./specs/ -r
 
@@ -80,6 +86,7 @@ func init() {
 	uploadSpecsCmd.Flags().StringVar(&specFrameID, "frame-id", "", "Frame ID: MoMorph integer (e.g. 7323) or Figma frame ID (e.g. 70:1214). Required when not encoded in the filename.")
 	uploadSpecsCmd.Flags().StringVar(&specFileKey, "file-key", "", "Figma file key (required with --frame-id when using a Figma frame ID outside .momorph/ path)")
 	uploadSpecsCmd.Flags().StringVar(&specFrameName, "frame-name", "", "Frame name for display (optional, used with --frame-id)")
+	uploadSpecsCmd.Flags().StringVar(&specScreenID, "screen-id", "", "Screen ID (MoMorph integer, alternative to --frame-id)")
 	uploadCmd.AddCommand(uploadSpecsCmd)
 }
 
@@ -112,9 +119,20 @@ func runUploadSpecs(cmd *cobra.Command, args []string) error {
 		fmt.Println("⚠ Could not get user email for revision tracking")
 	}
 
+	// Validate conflicting flags
+	if specScreenID != "" && (specFrameID != "" || specFileKey != "") {
+		return fmt.Errorf("--screen-id cannot be used together with --frame-id or --file-key")
+	}
+
 	// Parse --frame-id flag when provided
 	var flagsMeta *upload.MoMorphFrameMeta
-	if specFrameID != "" {
+	if specScreenID != "" {
+		// Screen ID mode takes precedence
+		flagsMeta = &upload.MoMorphFrameMeta{
+			ScreenID:  specScreenID,
+			FrameName: specFrameName,
+		}
+	} else if specFrameID != "" {
 		parsedID, err := strconv.Atoi(specFrameID)
 		if err == nil && parsedID > 0 {
 			// MoMorph integer frame ID
@@ -143,7 +161,7 @@ func runUploadSpecs(cmd *cobra.Command, args []string) error {
 	if len(files) == 0 {
 		fmt.Println("No CSV files found to upload")
 		fmt.Println("\nProvide CSV file paths directly or use --dir to scan a directory.")
-		fmt.Println("The frame ID must be in the filename (e.g. 42-MyScreen.csv) or supplied via --frame-id.")
+		fmt.Println("The frame ID must be in the filename (e.g. 42-MyScreen.csv) or supplied via --frame-id or --screen-id.")
 		return nil
 	}
 
@@ -181,7 +199,9 @@ func runUploadSpecs(cmd *cobra.Command, args []string) error {
 			}
 			specs, _ := upload.ParseSpecsCSV(f)
 			fmt.Printf("  - %s\n", filepath.Base(f))
-			if meta.FigmaFrameID != "" {
+			if meta.ScreenID != "" {
+				fmt.Printf("    Screen ID:  %s\n", meta.ScreenID)
+			} else if meta.FigmaFrameID != "" {
 				fmt.Printf("    Figma Frame ID: %s\n", meta.FigmaFrameID)
 				fmt.Printf("    File Key:       %s\n", meta.FileKey)
 			} else {
@@ -306,9 +326,20 @@ func uploadSingleSpecFile(ctx context.Context, client *graphql.Client, filePath
 
 	logger.Debug("Parsed %d specs from %s", len(specs), fileName)
 
-	// Fetch frame — by MoMorph integer ID or by Figma frame ID
+	// Fetch frame — by screen ID, MoMorph integer ID, or Figma frame ID
 	var frame *graphql.Frame
-	if meta.FigmaFrameID != "" {
+	if meta.ScreenID != "" {
+		frame, err = client.GetFrameByScreenID(ctx, meta.ScreenID)
+		if err != nil {
+			return upload.UploadResult{
+				FilePath: filePath,
+				FileName: fileName,
+				Status:   upload.StatusFailed,
+				Error:    err,
+				Message:  fmt.Sprintf("Frame not found (screen_id=%s): %v", meta.ScreenID, err),
+			}
+		}
+	} else if meta.FigmaFrameID != "" {
 		if meta.FileKey == "" {
 			return upload.UploadResult{
 				FilePath: filePath,

cmd/upload_testcases.go

@@ -23,6 +23,7 @@ var (
 	tcFileKey         string
 	tcFrameID         string
 	tcFrameName       string
+	tcScreenID        string
 )
 
 // CSV columns are mapped to test case fields:
@@ -43,13 +44,18 @@ By default, files must follow the path pattern:
 
 Alternatively, use --file-key (and optionally --frame-id, --frame-name) to
 upload CSV files from any location without following the path convention.
+
+You can also use --screen-id to upload by screen ID instead of frame ID.
 `,
 	Example: `  # Upload using path convention
   momorph upload testcases .momorph/testcases/xxx/9276:19907-TOP_Channel.csv
 
   # Upload from any location with explicit metadata
   momorph upload testcases ~/data/tc.csv --file-key=xxx --frame-id=9276:19907
 
+  # Upload using screen ID
+  momorph upload testcases ~/data/tc.csv --screen-id=42
+
   # Upload all testcases in a directory recursively
   momorph upload testcases --dir .momorph/testcases/ -r
 
@@ -66,6 +72,7 @@ func init() {
 	uploadTestcasesCmd.Flags().StringVar(&tcFileKey, "file-key", "", "Figma file key (required when CSV is not in .momorph/ path)")
 	uploadTestcasesCmd.Flags().StringVar(&tcFrameID, "frame-id", "", "Figma frame ID (optional, used with --file-key)")
 	uploadTestcasesCmd.Flags().StringVar(&tcFrameName, "frame-name", "", "Frame name (optional, used with --file-key)")
+	uploadTestcasesCmd.Flags().StringVar(&tcScreenID, "screen-id", "", "Screen ID (MoMorph integer, alternative to --frame-id)")
 	uploadCmd.AddCommand(uploadTestcasesCmd)
 }
 
@@ -91,8 +98,13 @@ func runUploadTestcases(cmd *cobra.Command, args []string) error {
 		return nil
 	}
 
-	// Determine if using flags mode (--file-key provided)
-	useFlags := tcFileKey != ""
+	// Validate conflicting flags
+	if tcScreenID != "" && (tcFileKey != "" || tcFrameID != "") {
+		return fmt.Errorf("--screen-id cannot be used together with --file-key or --frame-id")
+	}
+
+	// Determine if using flags mode (--file-key or --screen-id provided)
+	useFlags := tcFileKey != "" || tcScreenID != ""
 
 	// Build parsed metadata from flags when in flags mode
 	var flagsParsed *upload.ParsedFilePath
@@ -116,8 +128,9 @@ func runUploadTestcases(cmd *cobra.Command, args []string) error {
 		if !useFlags {
 			fmt.Println("\nMake sure files are in the correct path format:")
 			fmt.Println("  .momorph/testcases/{file_key}/{frame_id}-{frame_name}.csv")
-			fmt.Println("\nOr use --file-key to upload from any location:")
+			fmt.Println("\nOr use --file-key or --screen-id to upload from any location:")
 			fmt.Println("  momorph upload testcases myfile.csv --file-key=<figma_file_key>")
+			fmt.Println("  momorph upload testcases myfile.csv --screen-id=<screen_id>")
 		}
 		return nil
 	}
@@ -147,8 +160,12 @@ func runUploadTestcases(cmd *cobra.Command, args []string) error {
 				parsed, _ = upload.ParseFilePath(f)
 			}
 			fmt.Printf("  - %s\n", filepath.Base(f))
-			fmt.Printf("    File Key: %s\n", parsed.FileKey)
-			fmt.Printf("    Frame ID: %s\n", parsed.FrameID)
+			if tcScreenID != "" {
+				fmt.Printf("    Screen ID: %s\n", tcScreenID)
+			} else {
+				fmt.Printf("    File Key: %s\n", parsed.FileKey)
+				fmt.Printf("    Frame ID: %s\n", parsed.FrameID)
+			}
 			fmt.Printf("    Frame Name: %s\n", parsed.FrameName)
 		}
 		return nil
@@ -163,7 +180,7 @@ func runUploadTestcases(cmd *cobra.Command, args []string) error {
 
 	// Upload files
 	fmt.Printf("\nUploading %d test case file(s)...\n", len(validFiles))
-	results := uploadTestcaseFiles(ctx, client, validFiles, flagsParsed, tcUploadContinue)
+	results := uploadTestcaseFiles(ctx, client, validFiles, flagsParsed, tcScreenID, tcUploadContinue)
 
 	// Combine with skipped files
 	allResults := append(skipped, results...)
@@ -174,7 +191,7 @@ func runUploadTestcases(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
-func uploadTestcaseFiles(ctx context.Context, client *graphql.Client, files []string, flagsParsed *upload.ParsedFilePath, continueOnError bool) []upload.UploadResult {
+func uploadTestcaseFiles(ctx context.Context, client *graphql.Client, files []string, flagsParsed *upload.ParsedFilePath, screenID string, continueOnError bool) []upload.UploadResult {
 	var results []upload.UploadResult
 
 	for i, file := range files {
@@ -188,7 +205,7 @@ func uploadTestcaseFiles(ctx context.Context, client *graphql.Client, files []st
 		fileName := filepath.Base(file)
 		fmt.Printf("  [%d/%d] %s ", i+1, len(files), fileName)
 
-		result := uploadSingleTestcaseFile(ctx, client, file, flagsParsed)
+		result := uploadSingleTestcaseFile(ctx, client, file, flagsParsed, screenID)
 		results = append(results, result)
 
 		switch result.Status {
@@ -211,9 +228,92 @@ func uploadTestcaseFiles(ctx context.Context, client *graphql.Client, files []st
 
 // uploadSingleTestcaseFile uploads a single testcase CSV file. When flagsParsed
 // is non-nil it is used as metadata instead of parsing from the file path.
-func uploadSingleTestcaseFile(ctx context.Context, client *graphql.Client, filePath string, flagsParsed *upload.ParsedFilePath) upload.UploadResult {
+// When screenID != "", the frame is resolved by screen_id instead of file-key + frame-id.
+func uploadSingleTestcaseFile(ctx context.Context, client *graphql.Client, filePath string, flagsParsed *upload.ParsedFilePath, screenID string) upload.UploadResult {
 	fileName := filepath.Base(filePath)
 
+	// Screen ID mode: resolve frame by screen_id directly
+	if screenID != "" {
+		// Parse CSV file
+		frameName := ""
+		if flagsParsed != nil {
+			frameName = flagsParsed.FrameName
+		}
+		content, err := upload.ParseTestcasesCSV(filePath, frameName)
+		if err != nil {
+			return upload.UploadResult{
+				FilePath: filePath,
+				FileName: fileName,
+				Status:   upload.StatusFailed,
+				Error:    err,
+				Message:  fmt.Sprintf("Failed to parse CSV: %v", err),
+			}
+		}
+
+		if len(content.TestCases) == 0 {
+			return upload.UploadResult{
+				FilePath: filePath,
+				FileName: fileName,
+				Status:   upload.StatusSkipped,
+				Message:  "CSV file contains no test cases",
+			}
+		}
+
+		logger.Debug("Parsed %d test cases from %s", len(content.TestCases), fileName)
+
+		// Check if test cases already exist for this screen
+		existingTestCases, err := client.GetFrameTestCasesByScreenID(ctx, screenID)
+		if err != nil {
+			logger.Debug("No existing test cases found: %v", err)
+		}
+
+		if len(existingTestCases) > 0 {
+			logger.Debug("Updating existing test case ID: %d", existingTestCases[0].ID)
+			_, err = client.UpdateFrameTestcase(ctx, existingTestCases[0].ID, content)
+			if err != nil {
+				return upload.UploadResult{
+					FilePath: filePath,
+					FileName: fileName,
+					Status:   upload.StatusFailed,
+					Error:    err,
+					Message:  fmt.Sprintf("Failed to update test case: %v", err),
+				}
+			}
+		} else {
+			// Get frame by screen_id to get internal ID
+			frame, err := client.GetFrameByScreenID(ctx, screenID)
+			if err != nil {
+				return upload.UploadResult{
+					FilePath: filePath,
+					FileName: fileName,
+					Status:   upload.StatusFailed,
+					Error:    err,
+					Message:  fmt.Sprintf("Frame not found for screen_id=%s: %v", screenID, err),
+				}
+			}
+
+			logger.Debug("Creating new test case for frame ID: %d (screen_id=%s)", frame.ID, screenID)
+
+			_, err = client.InsertFrameTestcase(ctx, frame.ID, content)
+			if err != nil {
+				return upload.UploadResult{
+					FilePath: filePath,
+					FileName: fileName,
+					Status:   upload.StatusFailed,
+					Error:    err,
+					Message:  fmt.Sprintf("Failed to insert test case: %v", err),
+				}
+			}
+		}
+
+		return upload.UploadResult{
+			FilePath: filePath,
+			FileName: fileName,
+			Status:   upload.StatusSuccess,
+			Message:  fmt.Sprintf("Uploaded %d test cases", len(content.TestCases)),
+		}
+	}
+
 	// Resolve metadata: use flags or parse from path
 	var parsed *upload.ParsedFilePath
 	if flagsParsed != nil {
@@ -261,7 +361,7 @@ func uploadSingleTestcaseFile(ctx context.Context, client *graphql.Client, fileP
 			FilePath: filePath,
 			FileName: fileName,
 			Status:   upload.StatusFailed,
-			Message:  "frame-id is required for uploading test cases (use --frame-id flag)",
+			Message:  "frame-id is required for uploading test cases (use --frame-id or --screen-id flag)",
 		}
 	}
 

internal/graphql/operations.go

@@ -13,6 +13,7 @@ type Frame struct {
 	FileID      int    `json:"file_id"`
 	Name        string `json:"name"`
 	Status      string `json:"status"`
+	ScreenID    string `json:"screen_id"`
 }
 
 // FrameTestCase represents a test case for a frame
@@ -167,6 +168,39 @@ query GetFrameByID($id: bigint!) {
     status
   }
 }
+`
+
+	// GetFrameByScreenID query - fetch a MoMorph frame by its screen_id
+	queryGetFrameByScreenID = `
+query GetFrameByScreenID($screenId: String!) {
+  frames(where: {screen_id: {_eq: $screenId}}, limit: 1) {
+    id
+    frame_link_id
+    file_id
+    name
+    status
+    screen_id
+  }
+}
+`
+
+	// GetFrameTestCasesByScreenID query - fetch test cases by screen_id
+	queryGetFrameTestCasesByScreenID = `
+query GetFrameTestCasesByScreenID($screenId: String!) {
+  frame_testcases(
+    where: {
+      frame: {screen_id: {_eq: $screenId}}
+    }
+  ) {
+    id
+    testcasable_id
+    content
+    base_structure
+    status
+    created_at
+    updated_at
+  }
+}
 `
 
 	// ListDesignItemsByFrameIDAndNodeLinkIds query - fetch design items by frame ID and node link IDs
@@ -500,6 +534,44 @@ func (c *Client) GetFrameByID(ctx context.Context, id int) (*Frame, error) {
 	return &result.Frames[0], nil
 }
 
+// GetFrameByScreenID fetches a MoMorph frame by its screen_id
+func (c *Client) GetFrameByScreenID(ctx context.Context, screenID string) (*Frame, error) {
+	variables := map[string]interface{}{
+		"screenId": screenID,
+	}
+
+	var result struct {
+		Frames []Frame `json:"frames"`
+	}
+
+	if err := c.ExecuteWithResult(ctx, queryGetFrameByScreenID, variables, &result); err != nil {
+		return nil, err
+	}
+
+	if len(result.Frames) == 0 {
+		return nil, fmt.Errorf("frame not found: screen_id=%s", screenID)
+	}
+
+	return &result.Frames[0], nil
+}
+
+// GetFrameTestCasesByScreenID fetches test cases for a frame by screen_id
+func (c *Client) GetFrameTestCasesByScreenID(ctx context.Context, screenID string) ([]FrameTestCase, error) {
+	variables := map[string]interface{}{
+		"screenId": screenID,
+	}
+
+	var result struct {
+		FrameTestcases []FrameTestCase `json:"frame_testcases"`
+	}
+
+	if err := c.ExecuteWithResult(ctx, queryGetFrameTestCasesByScreenID, variables, &result); err != nil {
+		return nil, err
+	}
+
+	return result.FrameTestcases, nil
+}
+
 // ListDesignItemsByFrameID fetches design items by MoMorph frame ID.
 // When nodeLinkIds is non-empty only items matching those IDs are returned;
 // otherwise all design items for the frame are returned.