feat: add receive file download preview contract

2026-07-11 00:31:33 +08:00
parent 6164703a9a
commit 57db83d36c
6 changed files with 314 additions and 22 deletions
--- a/internal/tools/isphere_files_test.go
+++ b/internal/tools/isphere_files_test.go
@@ -148,10 +148,139 @@ func TestISphereReceiveFilesToolValidatesContractArgs(t *testing.T) {
 	}

 	downloadResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
-		Name:      ToolNameReceiveFiles,
-		Arguments: map[string]any{"mode": "download", "file_id": "msg-file-1:redacted-report.docx"},
+		Name: ToolNameReceiveFiles,
+		Arguments: map[string]any{
+			"mode":    "download",
+			"preview": true,
+			"file_id": "msg-file-1:redacted-report.docx",
+		},
 	})
-	if err == nil && !downloadResult.IsError {
-		t.Fatalf("download mode was accepted before cache mapping exists")
+	if err != nil {
+		t.Fatalf("download preview returned transport error: %v", err)
+	}
+	if downloadResult.IsError {
+		t.Fatalf("download preview should return structured blocked content: %+v", downloadResult.Content)
+	}
+	var downloadPayload map[string]any
+	downloadEncoded, _ := json.Marshal(downloadResult.StructuredContent)
+	if err := json.Unmarshal(downloadEncoded, &downloadPayload); err != nil {
+		t.Fatalf("decode download structured content %s: %v", downloadEncoded, err)
+	}
+	if downloadPayload["ok"] != false || downloadPayload["download_status"] != "blocked" || downloadPayload["blocked_reason_code"] != "file_cache_mapping_missing" {
+		t.Fatalf("unexpected download preview block: %s", downloadEncoded)
+	}
+}
+
+func TestISphereReceiveFilesDownloadPreviewBlockedWithoutMapping(t *testing.T) {
+	fake := &fakeReceiveMessagesSource{}
+	session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
+		RegisterISphereFileTools(server, fake)
+	})
+	defer cleanup()
+
+	callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
+		Name: ToolNameReceiveFiles,
+		Arguments: map[string]any{
+			"mode":       "download",
+			"preview":    true,
+			"file_ref":   "msg-file-1:redacted-report.docx",
+			"output_dir": "C:\\tmp\\isphere-downloads",
+		},
+	})
+	if err != nil {
+		t.Fatalf("download preview call returned transport error: %v", err)
+	}
+	if callResult.IsError {
+		t.Fatalf("download preview should return structured blocked content, got error: %+v", callResult)
+	}
+
+	var decoded struct {
+		OK                bool   `json:"ok"`
+		Mode              string `json:"mode"`
+		DownloadStatus    string `json:"download_status"`
+		BlockedReasonCode string `json:"blocked_reason_code"`
+		FileContentsRead  bool   `json:"file_contents_read"`
+		FileCopied        bool   `json:"file_copied"`
+		RealDownload      bool   `json:"real_download_attempted"`
+	}
+	payload, err := json.Marshal(callResult.StructuredContent)
+	if err != nil {
+		t.Fatalf("marshal structured content: %v", err)
+	}
+	if err := json.Unmarshal(payload, &decoded); err != nil {
+		t.Fatalf("decode structured content %s: %v", payload, err)
+	}
+	if decoded.OK || decoded.Mode != "download" || decoded.DownloadStatus != "blocked" {
+		t.Fatalf("unexpected blocked response: %+v payload=%s", decoded, payload)
+	}
+	if decoded.BlockedReasonCode != "file_cache_mapping_missing" {
+		t.Fatalf("blocked reason = %q", decoded.BlockedReasonCode)
+	}
+	if decoded.FileContentsRead || decoded.FileCopied || decoded.RealDownload {
+		t.Fatalf("download side effects must be false: %+v", decoded)
+	}
+}
+
+func TestISphereReceiveFilesDownloadPreviewPlannedWithFixtureMapping(t *testing.T) {
+	resolver := receiveFileDownloadResolverFunc(func(ctx context.Context, query ReceiveFileDownloadQuery) (ReceiveFileDownloadResolution, error) {
+		if query.FileRef != "msg-file-1:redacted-report.docx" {
+			t.Fatalf("resolver file_ref = %q", query.FileRef)
+		}
+		if query.OutputDir != "C:\\tmp\\isphere-downloads" {
+			t.Fatalf("resolver output_dir = %q", query.OutputDir)
+		}
+		return ReceiveFileDownloadResolution{
+			Found:        true,
+			Source:       "fixture-cache-mapping",
+			MatchedScore: 100,
+		}, nil
+	})
+	session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
+		RegisterISphereFileToolsWithDownloadResolver(server, nil, resolver)
+	})
+	defer cleanup()
+
+	callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
+		Name: ToolNameReceiveFiles,
+		Arguments: map[string]any{
+			"mode":       "download",
+			"preview":    true,
+			"file_ref":   "msg-file-1:redacted-report.docx",
+			"output_dir": "C:\\tmp\\isphere-downloads",
+		},
+	})
+	if err != nil {
+		t.Fatalf("download preview call returned transport error: %v", err)
+	}
+	if callResult.IsError {
+		t.Fatalf("download preview should return planned content, got error: %+v", callResult)
+	}
+
+	var decoded struct {
+		OK               bool   `json:"ok"`
+		Mode             string `json:"mode"`
+		DownloadStatus   string `json:"download_status"`
+		FileRef          string `json:"file_ref"`
+		MappingSource    string `json:"mapping_source"`
+		MatchedScore     int    `json:"matched_score"`
+		FileContentsRead bool   `json:"file_contents_read"`
+		FileCopied       bool   `json:"file_copied"`
+		RealDownload     bool   `json:"real_download_attempted"`
+	}
+	payload, err := json.Marshal(callResult.StructuredContent)
+	if err != nil {
+		t.Fatalf("marshal structured content: %v", err)
+	}
+	if err := json.Unmarshal(payload, &decoded); err != nil {
+		t.Fatalf("decode structured content %s: %v", payload, err)
+	}
+	if !decoded.OK || decoded.Mode != "download" || decoded.DownloadStatus != "planned" {
+		t.Fatalf("unexpected planned response: %+v payload=%s", decoded, payload)
+	}
+	if decoded.FileRef != "msg-file-1:redacted-report.docx" || decoded.MappingSource != "fixture-cache-mapping" || decoded.MatchedScore != 100 {
+		t.Fatalf("unexpected mapping metadata: %+v", decoded)
+	}
+	if decoded.FileContentsRead || decoded.FileCopied || decoded.RealDownload {
+		t.Fatalf("preview side effects must be false: %+v", decoded)
 	}
 }