refactor(workspace): type workspace responses

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

Author: tae2089

internal/mcp/handler_workspace.go

@@ -1,3 +1,4 @@
+// @index MCP handlers for namespace workspace uploads, listing, and deletion.
 package mcp
 
 import (
@@ -15,33 +16,41 @@ import (
 	wsvc "github.com/tae2089/code-context-graph/internal/workspace"
 )
 
+// workspaceFileResult summarizes one uploaded workspace file.
+// @intent preserve a stable per-file DTO for workspace upload responses.
 type workspaceFileResult struct {
 	Namespace string `json:"namespace"`
 	Workspace string `json:"workspace"`
 	FilePath  string `json:"file_path"`
 	Size      int    `json:"size,omitempty"`
 }
 
+// workspaceUploadResponse is the typed wire payload for uploadFile and uploadFiles.
+// @intent preserve a stable confirmation envelope for single and bulk workspace uploads.
 type workspaceUploadResponse struct {
-	Status    string              `json:"status"`
-	Namespace string              `json:"namespace,omitempty"`
-	Workspace string              `json:"workspace,omitempty"`
-	FilePath  string              `json:"file_path,omitempty"`
-	Size      int                 `json:"size,omitempty"`
-	Uploaded  int                 `json:"uploaded,omitempty"`
+	Status    string                `json:"status"`
+	Namespace string                `json:"namespace,omitempty"`
+	Workspace string                `json:"workspace,omitempty"`
+	FilePath  string                `json:"file_path,omitempty"`
+	Size      int                   `json:"size,omitempty"`
+	Uploaded  int                   `json:"uploaded,omitempty"`
 	Files     []workspaceFileResult `json:"files,omitempty"`
 }
 
+// workspaceDeleteResponse is the typed wire payload for deleteFile and deleteWorkspace.
+// @intent preserve a stable confirmation envelope for workspace deletion operations.
 type workspaceDeleteResponse struct {
 	Status    string `json:"status"`
 	Namespace string `json:"namespace"`
 	Workspace string `json:"workspace"`
 	FilePath  string `json:"file_path,omitempty"`
 }
 
+// workspaceListResponse is the typed wire payload for listWorkspaces and listFiles.
+// @intent preserve a stable paged list envelope while omitting irrelevant legacy fields.
 type workspaceListResponse struct {
-	Namespaces []string    `json:"namespaces"`
-	Files      []string    `json:"files"`
+	Namespaces []string    `json:"namespaces,omitempty"`
+	Files      []string    `json:"files,omitempty"`
 	Items      []string    `json:"items"`
 	Count      int         `json:"count"`
 	Pagination paging.Page `json:"pagination"`

internal/mcp/handler_workspace_test.go

@@ -213,9 +213,17 @@ func TestListWorkspaces_Empty(t *testing.T) {
 	if err := json.Unmarshal([]byte(text), &resp); err != nil {
 		t.Fatalf("failed to parse response: %v", err)
 	}
-	workspaces := resp["namespaces"].([]any)
-	if len(workspaces) != 0 {
-		t.Errorf("expected empty list, got %v", workspaces)
+	if _, ok := resp["files"]; ok {
+		t.Fatalf("expected files field to be omitted, got %v", resp["files"])
+	}
+	if items := resp["items"].([]any); len(items) != 0 {
+		t.Errorf("expected empty items list, got %v", items)
+	}
+	if count := resp["count"].(float64); count != 0 {
+		t.Errorf("expected count 0, got %v", count)
+	}
+	if _, ok := resp["pagination"].(map[string]any); !ok {
+		t.Fatal("expected pagination object")
 	}
 }
 
@@ -293,6 +301,9 @@ func TestListFiles_Basic(t *testing.T) {
 	if err := json.Unmarshal([]byte(text), &resp); err != nil {
 		t.Fatalf("failed to parse response: %v", err)
 	}
+	if _, ok := resp["namespaces"]; ok {
+		t.Fatalf("expected namespaces field to be omitted, got %v", resp["namespaces"])
+	}
 	files := resp["files"].([]any)
 	if len(files) != 2 {
 		t.Errorf("expected 2 files, got %d: %v", len(files), files)
@@ -335,10 +346,10 @@ func TestListFiles_Pagination(t *testing.T) {
 func TestListWorkspaceAndFiles_InvalidPagination(t *testing.T) {
 	h, _ := workspaceHandlers(t)
 	for name, req := range map[string]mcp.CallToolRequest{
-		"workspaces limit": makeCallToolRequest(t, map[string]any{"limit": 0}),
+		"workspaces limit":  makeCallToolRequest(t, map[string]any{"limit": 0}),
 		"workspaces offset": makeCallToolRequest(t, map[string]any{"offset": -1}),
-		"files limit":      makeCallToolRequest(t, map[string]any{"workspace": "svc", "limit": 0}),
-		"files offset":     makeCallToolRequest(t, map[string]any{"workspace": "svc", "offset": -1}),
+		"files limit":       makeCallToolRequest(t, map[string]any{"workspace": "svc", "limit": 0}),
+		"files offset":      makeCallToolRequest(t, map[string]any{"workspace": "svc", "offset": -1}),
 	} {
 		t.Run(name, func(t *testing.T) {
 			var result *mcp.CallToolResult

internal/workspace/workspace.go

@@ -206,6 +206,8 @@ type ValidationError struct {
 }
 
 // Error returns the validation message.
+// @intent expose the caller-fixable validation message without wrapping it in transport-specific formatting.
+// @return returns the original validation message stored on the error.
 func (e *ValidationError) Error() string { return e.msg }
 
 // IsValidationError reports whether err is a ValidationError.
@@ -215,6 +217,8 @@ func IsValidationError(err error) bool {
 	return errors.As(err, &v)
 }
 
+// newValidationError constructs a ValidationError for caller-fixable workspace input issues.
+// @intent centralize creation of typed validation failures so handlers can recognize them consistently.
 func newValidationError(msg string) *ValidationError { return &ValidationError{msg: msg} }
 
 // UploadFile validates, decodes, and atomically writes a single workspace file.
@@ -232,12 +236,19 @@ func (s *Service) UploadFile(req UploadRequest) (*UploadResult, error) {
 	return &UploadResult{Namespace: req.Namespace, FilePath: req.FilePath, Size: len(prepared.decoded)}, nil
 }
 
+// preparedUpload holds validated upload data before it is written to disk.
+// @intent split validation/decoding from filesystem mutation so bulk uploads can validate before committing files.
 type preparedUpload struct {
 	req     UploadRequest
 	decoded []byte
 	target  string
 }
 
+// prepareUpload validates one upload request, decodes its content, and resolves its destination path.
+// @intent prepare a single upload for later commit while enforcing per-file and aggregate decoded-size limits.
+// @param alreadyDecoded tracks the total decoded bytes accepted earlier in the same bulk request.
+// @return returns a preparedUpload ready for commit when validation succeeds.
+// @domainRule rejects missing fields, invalid paths, invalid base64, oversized files, and oversized aggregate payloads.
 func (s *Service) prepareUpload(req UploadRequest, alreadyDecoded int) (*preparedUpload, error) {
 	limits := s.limitsOrDefault()
 	if req.Namespace == "" || req.FilePath == "" || req.ContentBase64 == "" {
@@ -263,6 +274,9 @@ func (s *Service) prepareUpload(req UploadRequest, alreadyDecoded int) (*prepare
 	return &preparedUpload{req: req, decoded: decoded, target: target}, nil
 }
 
+// commitPrepared creates parent directories, revalidates the path, and atomically writes one prepared upload.
+// @intent separate filesystem mutation from validation so bulk uploads can fail fast before writing any file.
+// @sideEffect creates directories and writes the target file atomically.
 func (s *Service) commitPrepared(p *preparedUpload) error {
 	if err := os.MkdirAll(filepath.Dir(p.target), 0o755); err != nil {
 		return fmt.Errorf("create directory: %w", err)
@@ -276,6 +290,9 @@ func (s *Service) commitPrepared(p *preparedUpload) error {
 	return nil
 }
 
+// limitsOrDefault returns the configured limits with zero values replaced by workspace defaults.
+// @intent ensure upload validation always runs with concrete byte ceilings even when callers omit custom limits.
+// @return returns a Limits value whose file, request, and aggregate byte caps are all populated.
 func (s *Service) limitsOrDefault() Limits {
 	l := s.Limits
 	if l.MaxFileBytes == 0 {
@@ -306,7 +323,14 @@ type BulkEntryError struct {
 	Err   error
 }
 
+// Error formats the failing bulk entry index with the underlying error text.
+// @intent preserve a user-facing error string that points callers to the exact bad entry.
+// @return returns an error string prefixed with the failing entry index.
 func (e *BulkEntryError) Error() string { return fmt.Sprintf("entry %d: %v", e.Index, e.Err) }
+
+// Unwrap returns the underlying entry error.
+// @intent allow callers to inspect the original validation or filesystem failure that broke a bulk upload.
+// @return returns the underlying entry error for errors.Is and errors.As checks.
 func (e *BulkEntryError) Unwrap() error { return e.Err }
 
 // UploadFiles parses a bulk upload JSON payload, validates every entry, and writes them sequentially.