modularize-go-package

name	modularize-go-package
description	Modularize a monolithic Go package into domain-specific sub-packages. Extracts shared utilities, moves domain files, updates imports, renames types, creates registration functions, and validates compilation+tests at every step. Designed for large-scale refactoring of 50-100+ file packages.

Modularize Go Package

Primary Directive

Transform a monolithic Go package into a modular structure with domain-specific sub-packages and a shared utilities package. Every step must maintain compilation and test integrity.

Execution Model

This skill operates in atomic migration batches. Each batch moves one domain to its own sub-package. Between batches, the project must compile and all tests must pass. Never move to the next batch until the current one is verified.

Prerequisites

Before invoking this skill, ensure:

1. Clean git working directory (git status shows no uncommitted changes)
2. All tests pass: go test ./internal/... -count=1
3. All code compiles: go build ./...
4. You have identified the source package and its domain files

Input Parameters

• ${sourcePackage} — The monolithic package to modularize (e.g., internal/tools)
• ${utilPackage} — Name for the shared utilities package (e.g., internal/toolutil)
• ${domains} — Comma-separated list of domains to extract (e.g., branches,commits,issues)

Process

Step 1: Inventory Analysis

Scan the source package and classify every file:

Category	Files	Action
Shared utilities	errors.go, pagination.go, logging.go, markdown.go, text.go, metatool.go, string_or_int.go, fileutils.go, time_helpers.go	Extract to ${utilPackage}
Shared constants	Annotation variables, format constants	Extract to ${utilPackage}
Domain handlers	branches.go, commits.go, etc.	Move to ${sourcePackage}/{domain}/
Domain tests	branches_test.go, commits_test.go, etc.	Move with their domain
Test helpers	helpers_test.go	Extract to ${utilPackage} as testutil
Catalog wiring	action_specs.go, catalog aggregation	Keep runtime surfaces catalog-backed; do not add package-level meta registration as the final path
Package doc	(doc comment in any file)	Create ${sourcePackage}/doc.go

CRITICAL: Dynamic Discovery

The client-go API library (gitlab.com/gitlab-org/api/client-go/v2) is the source of truth for domain organization, structures, and field definitions. Do NOT rely only on the tables in this skill or on user-facing tool documentation.

Before starting migration, run this discovery sequence:

# 1. Discover ALL client-go services (defines the universe of possible domains)
go doc gitlab.com/gitlab-org/api/client-go/v2.Client | rg '\s+\w+\s+\*\w+Service'

# 2. List all non-test handler files in the source package (what we actually implement)
rg --files "${sourcePackage}" -g '*.go' -g '!*_test.go' | rg -v '/(errors|pagination|logging|markdown|text|metatool|string_or_int|fileutils|time_helpers|register|helpers)\.go$'

Compare the result against the domain mapping table in this skill. For any file NOT in the table:

1. Check client-go types first: Run go doc gitlab.com/gitlab-org/api/client-go/v2.{Type} to understand the canonical struct fields and API contracts for that domain
2. Check client.GL().{Service}.* calls in the source file → determines the sub-package name
3. Check action_specs.go and catalog aggregation → determines canonical runtime surface status
4. Check docs/tools/{domain}.md IF it exists → supplementary user-facing context

The sub-package name must align with the client-go service name, not with our file naming.

Step 2: Create Shared Utilities Package

Create ${utilPackage}/ and extract shared code in dependency order:

Order (no circular deps):
1. Pure types with zero internal deps (StringOrInt, time helpers)
2. Types depending only on external libs (PaginationInput, ToolError)
3. Functions depending on types above (wrapErr, paginationFromResponse)
4. Complex utilities (markdown formatters, metatool dispatcher)

For each extracted file:

1. Create new file in ${utilPackage}/

2. Change package tools → package toolutil

3. Export all symbols that are used by domain handlers:

   • Functions: wrapErr → WrapErr
   • Variables: readAnnotations → ReadAnnotations
   • Types remain exported if already exported

4. Keep the old file in ${sourcePackage} temporarily as a forwarding stub:

   // DEPRECATED: forwarding stub — will be removed when all domains are migrated.
   package tools
   
   import "github.com/jmrplens/gitlab-mcp-server/v2/internal/toolutil"
   
   var wrapErr = toolutil.WrapErr
   

5. Verify: go build ./...

Step 3: Migrate Domain (Repeat per Domain)

For each domain in priority order:

3a. Create Sub-Package

mkdir -p ${sourcePackage}/{domain}

3b. Move and Transform Handler File

1. Copy {domain}.go → ${sourcePackage}/{domain}/{domain}.go
2. Change package declaration: package tools → package {domain}
3. Update imports to use ${utilPackage} instead of direct references
4. Rename types — remove domain prefix (the package name provides context):
   • BranchCreateInput → CreateInput
   • BranchOutput → Output
   • BranchListOutput → ListOutput
5. Export handler functions — remove domain prefix, capitalize:
   • branchCreate → Create
   • branchList → List
   • branchGet → Get
6. Replace internal utility calls:
   • wrapErr(...) → toolutil.WrapErr(...)
   • markdownForResult(...) → toolutil.MarkdownForResult(...)
   • logToolCallAll(...) → toolutil.LogToolCallAll(...)
   • readAnnotations → toolutil.ReadAnnotations

3c. Create ActionSpec File

Create ${sourcePackage}/{domain}/action_specs.go:

package {domain}

import (
   gitlabclient "github.com/jmrplens/gitlab-mcp-server/v2/internal/gitlab"
   "github.com/jmrplens/gitlab-mcp-server/v2/internal/toolutil"
)

// ActionSpecs returns canonical specs for {domain} actions.
func ActionSpecs(client *gitlabclient.Client) []toolutil.ActionSpec {
   // ... specs moved from the old registration metadata and wired to handlers
}

Do not create package-local RegisterTools or package-level RegisterMeta functions for ordinary GitLab API domains. The root runtime must use catalog projection from ActionSpecs.

3d. Move and Transform Test File

1. Copy {domain}_test.go → ${sourcePackage}/{domain}/{domain}_test.go
2. Change package: package tools → package {domain} (or package {domain}_test for black-box)
3. Update type references to match renamed types
4. Import test helpers from ${utilPackage} or recreate locally
5. Update handler function references

3e. Update Catalog Aggregation

Add the domain's ActionSpecs(client) builder to the audited catalog aggregation/generation path. Validate that RegisterAll projects individual tools from the catalog rather than calling domain RegisterTools directly.

3f. Remove Old Files

Delete the original files from ${sourcePackage}/:

• {domain}.go
• {domain}_test.go

3g. Verify

go build ./...
golangci-lint run --build-tags e2e ./...
go test ./${sourcePackage}/{domain}/ -count=1 -v
go test ./${sourcePackage}/ -count=1

Step 4: Clean Up Forwarding Stubs

After ALL domains are migrated:

1. Remove forwarding stubs from ${sourcePackage}/

2. Remove old utility files (they now live in ${utilPackage}/)

3. Final verification:

   go build ./...
   golangci-lint run --build-tags e2e ./...
   go test ./internal/... -count=1
   

Step 5: Update Entry Point

Verify cmd/server/main.go still only imports ${sourcePackage}:

import "github.com/jmrplens/gitlab-mcp-server/v2/internal/tools"

// tools.RegisterAll(server, client) — still works, delegates internally

Validation Checklist

After completing all migrations:

• go build ./... — zero errors
• golangci-lint run --build-tags e2e ./... — zero warnings
• go test ./internal/... -count=1 — all pass
• No import cycles: go list ./... or manual review
• cmd/server/main.go unchanged (still imports internal/tools)
• Each sub-package has: handler file, action_specs.go, markdown formatter, and test file
• ${utilPackage} has no imports from domain sub-packages
• Domain sub-packages don't import each other

Multi-File Domain Handling

For domains that span multiple source files, consolidate during migration:

Merge Requests (6 files → 1 sub-package)

merge_requests.go      → mergerequests/merge_requests.go
mr_notes.go            → mergerequests/notes.go
mr_discussions.go      → mergerequests/discussions.go
mr_changes.go          → mergerequests/changes.go
mr_approvals.go        → mergerequests/approvals.go
mr_draft_notes.go      → mergerequests/draft_notes.go

Each file keeps its handler functions; action_specs.go consolidates all MR action metadata and catalog routes.

Packages (4 files → 1 sub-package)

packages.go            → packages/packages.go
packages_chunked.go    → packages/chunked.go
packages_composite.go  → packages/composite.go
packages_stream.go     → packages/stream.go

Error Recovery

Compilation Error After Move

# Most common: unexported symbol
./internal/tools/branches/branches.go:15: undefined: wrapErr
→ Fix: Change to toolutil.WrapErr

# Missing import
./internal/tools/branches/branches.go:3: imported and not used
→ Fix: Remove unused import, add missing one

# Circular import
package gitlab.example.com/.../tools imports gitlab.example.com/.../tools/branches imports gitlab.example.com/.../tools
→ Fix: Extract shared code to toolutil, break the cycle

Test Failure After Move

# Test helper not found
./internal/tools/branches/branches_test.go:10: undefined: newTestClient
→ Fix: Import from toolutil or recreate locally

# Type mismatch
cannot use BranchOutput as tools.BranchOutput
→ Fix: Update test to use new type name (Output instead of BranchOutput)

GitLab API Domain Reference

When modularizing internal/tools/, use this mapping to understand which files belong together and why. Each sub-package should correspond to a coherent GitLab API domain.

Service-to-SubPackage Mapping

The project uses gitlab.com/gitlab-org/api/client-go/v2 v2.42.0. Each client.GL().{Service} call tells you which API domain a handler belongs to:

Sub-Package	client-go Services Used	Source Files
branches/	Branches, ProtectedBranches	branches.go
tags/	Tags	tags.go
commits/	Commits	commits.go
files/	RepositoryFiles	files.go
repository/	Repositories	repository.go
projects/	Projects	repositories.go (misnamed — rename during move)
mergerequests/	MergeRequests, MergeRequestApprovals, Notes, Discussions, DraftNotes	merge_requests.go, mr_notes.go, mr_discussions.go, mr_changes.go, mr_approvals.go, mr_draft_notes.go
issues/	Issues, Notes	issues.go, issue_notes.go
labels/	Labels	labels.go
milestones/	Milestones	milestones.go
members/	ProjectMembers	members.go
groups/	Groups	groups.go
pipelines/	Pipelines	pipelines.go
jobs/	Jobs	jobs.go
releases/	Releases, ReleaseLinks	releases.go, release_links.go
search/	Search	search.go
users/	Users	users.go
packages/	Packages, GenericPackages	packages.go, packages_chunked.go, packages_composite.go, packages_stream.go
uploads/	ProjectMarkdownUploads	uploads.go
wikis/	Wikis	wikis.go
todos/	Todos	todos.go
health/	Version	health.go
environments/	Environments	environments.go
elicitation/	(MCP-only, no GitLab API)	elicitation_tools.go

⚠️ This table may be incomplete. Always scan the source package for files not listed here before starting a migration session. Any unlisted handler file is a new domain to add to the plan.

client-go Import Patterns

After migration, each sub-package will import:

import (
    gl "gitlab.com/gitlab-org/api/client-go/v2"
   gitlabclient "github.com/jmrplens/gitlab-mcp-server/v2/internal/gitlab"
   "github.com/jmrplens/gitlab-mcp-server/v2/internal/toolutil"
)

Preserve these client-go calling patterns exactly:

• CRUD: result, resp, err := client.GL().{Service}.{Method}(args..., gl.WithContext(ctx))
• Delete: _, err := client.GL().{Service}.Delete{Resource}(id, gl.WithContext(ctx))
• Low-level HTTP (packages only): client.GL().NewRequest(...) + client.GL().Do(...)
• Option structs: &gl.List{Resource}Options{...} — these never change, they come from client-go

Naming Fix During Migration

The file repositories.go contains Projects CRUD operations (uses client.GL().Projects.*), NOT repository operations. When moving to the projects/ sub-package, rename it to projects.go. The actual repository operations (tree, compare) are in repository.go and use client.GL().Repositories.*.

Reference Documentation

The client-go API library is the source of truth for domain structure and field definitions. Our source code implements a subset of it. docs/reference/tools is supplementary user-facing documentation, not the canonical field map.

Before migrating each domain:

1. Inspect client-go types: Run go doc gitlab.com/gitlab-org/api/client-go/v2.{Type} for the domain's key types (e.g., gl.Environment, gl.CreateEnvironmentOptions). This defines the canonical fields, types, and API contract.
2. Read the source file(s) in internal/tools/{domain}.go — shows our implementation: which client-go fields we expose, our Input/Output structs, and client.GL().{Service} calls.
3. Check action_specs.go and catalog aggregation for runtime exposure. Files absent from the catalog are in-progress — still migrate them, but note the gap.
4. Read docs/tools/{domain}.md IF it exists — supplementary user-facing context. If no doc exists, the combination of steps 1+2 provides everything needed.
5. Discover new domains by scanning *.go files AND running go doc on the client to find services we haven't wrapped yet.

Never skip a domain just because it lacks documentation. The client-go types have all the information needed.