refactor: encapsulation - reduce common/ exported surface and fix test helper inconsistency

[aliwatters]

Summary

Reduce the exported API surface of the common/ package by unexporting symbols that are only used internally, and clean up minor inconsistencies across packages: the docs MakeDocsRequest test helper duplicates common.CreateMCPRequest, and GetServiceWithDeps/TestableFunc are exported but only used within handler_deps.go.

Location

Unexport candidates:

• internal/common/handler_deps.go:25 — GetServiceWithDeps (only called by ResolveServiceOrError on L87 of same file)
• internal/common/handler_deps.go:106 — TestableFunc type (only used by WrapHandler on L110 of same file)

Duplicate test helper:

• internal/docs/docs_test_helpers.go:54 — MakeDocsRequest() duplicates common.CreateMCPRequest()
• Compare with internal/calendar/calendar_tools_test.go:16 which correctly aliases var CreateMCPRequest = common.CreateMCPRequest

Verbose design notes:

• internal/tasks/tasks_tools_testable.go:173-185 — 13-line comment block discussing design decisions; could be condensed to 2-3 lines

Category

Type: Feature Envy / Poor Encapsulation

Severity: Low

Evidence

GetServiceWithDeps is exported but only has one caller:

// handler_deps.go:87
func ResolveServiceOrError[S any](...) {
    srv, err := GetServiceWithDeps(ctx, request, deps)
    ...
}

MakeDocsRequest duplicates existing utility:

// docs_test_helpers.go:54
func MakeDocsRequest(args map[string]any) mcp.CallToolRequest { ... }
// common/types.go:25
func CreateMCPRequest(args map[string]any) mcp.CallToolRequest { ... }

Suggested Refactoring

1. Rename GetServiceWithDeps → getServiceWithDeps (unexport)
2. Rename TestableFunc → testableFunc (unexport)
3. Replace MakeDocsRequest in docs tests with common.CreateMCPRequest (matching calendar's pattern)
4. Condense design notes in tasks_tools_testable.go

Effort Estimate

• Size: Small (< 1 hour)
• Risk: Low (internal changes only, no external consumers)
• Tests Required: Yes (existing tests must pass)

Acceptance Criteria

• GetServiceWithDeps unexported
• TestableFunc unexported
• MakeDocsRequest replaced with common.CreateMCPRequest
• Design notes condensed
• go build ./... and go test ./... pass

[aliwatters]

Claimed by AI Agent

Workspace: gsuite-mcp
Claimed at: 2026-02-10T08:53:58-06:00

This issue is now being worked on by an AI agent in workspace gsuite-mcp.

[aliwatters]

🔗 Batch Work: Working on this issue together with , in a single PR.

Branch: refactor/issue-15-dry-helpers-batch