go-safe-move-refactor

name	go-safe-move-refactor
description	Safely move Go source files between packages with zero compilation downtime. Handles package declarations, import updates, symbol exports, type renames, test migration, and forwarding stubs. Validates compilation after every atomic step.

Go Safe Move Refactor

Primary Directive

Move one or more Go source files from one package to another while maintaining compilation at every intermediate step. This skill implements the "bridge pattern" — keep old code working via forwarding stubs while new code is established, then remove bridges after verification.

When to Use

• Moving a .go file from one package to another
• Extracting a set of functions/types into a new package
• Consolidating multiple files into a single sub-package
• Splitting a large package into smaller ones

Core Principle: Never Break Compilation

Every change must be an atomic step that leaves go build ./... passing. The sequence is:

1. Create destination → 2. Copy & transform → 3. Add forwarding stubs → 4. Verify → 5. Update consumers → 6. Remove stubs → 7. Verify

Process

Step 1: Pre-Flight Check

go build ./...    # Must pass
golangci-lint run --build-tags e2e ./... # Must pass
go test ./...     # Record baseline (should pass)

Record:

• Source file path: ${srcFile} (e.g., internal/tools/branches.go)
• Source package: ${srcPkg} (e.g., tools)
• Destination directory: ${dstDir} (e.g., internal/tools/branches/)
• Destination package: ${dstPkg} (e.g., branches)

Discovery check (before any move): The client-go API defines the canonical domain structure. Verify you have the complete picture:

1. Inspect client-go types: Run go doc gitlab.com/gitlab-org/api/client-go/v2.{Type} for the domain's key types to understand the canonical fields and API contract
2. List all non-test handler files in the source package to find everything that exists
3. Check action_specs.go and catalog aggregation for the domain's canonical runtime exposure
4. Look for related files (e.g., a domain might span {domain}.go + {domain}_extra.go)
5. If docs/tools/{domain}.md exists, read it for supplementary user-facing context — but do NOT skip the move if no doc exists

Step 2: Analyze Dependencies

Before moving, catalog ALL symbols in the source file:

Symbol	Type	Visibility	Used By
BranchCreateInput	struct	exported	action_specs.go, branches_test.go
BranchOutput	struct	exported	action_specs.go, branches_test.go, markdown.go
branchCreate	func	unexported	action_specs.go
branchList	func	unexported	action_specs.go

Use grep and go doc to find all references:

grep -rn "BranchCreateInput\|BranchOutput\|branchCreate\|branchList" internal/

Step 3: Create Destination Package

mkdir -p ${dstDir}

Create minimal doc.go if this is a new package:

// Package branches implements MCP tool handlers for GitLab branch operations.
package branches

Verify: go build ./... (empty package is fine)

Step 4: Copy and Transform Source File

1. Copy (don't move yet) ${srcFile} → ${dstDir}/${filename}
2. Change package declaration: package ${srcPkg} → package ${dstPkg}
3. Update imports:
   • Remove self-package imports (they're now local)
   • Add imports for shared utilities: "module/path/internal/toolutil"
   • Add imports for GitLab client, MCP SDK as needed
4. Export functions that need to be called externally:
   • branchCreate → Create (exported, package provides namespace)
   • branchList → List
5. Rename types to remove domain prefix:
   • BranchCreateInput → CreateInput
   • BranchOutput → Output
6. Update internal references to use toolutil. prefix for shared utilities

Step 5: Create Forwarding Stubs (Bridge)

In the original package, replace the moved code with forwarding stubs:

// branches.go — forwarding stubs (temporary, remove after all consumers updated)
package tools

import "module/path/internal/tools/branches"

// Type aliases for backward compatibility during migration.
type BranchCreateInput = branches.CreateInput
type BranchOutput = branches.Output
type BranchListOutput = branches.ListOutput

// Function forwarding for backward compatibility during migration.
var branchCreate = branches.Create
var branchList = branches.List
var branchGet = branches.Get

CRITICAL: This step ensures all existing code that references tools.BranchCreateInput or calls branchCreate() still compiles.

Verify: go build ./... — MUST pass before continuing.

Step 6: Update Direct Consumers

Find all files that reference the moved symbols:

rg -n "branchCreate|BranchCreateInput|BranchOutput" internal/ --glob "*.go" --glob "!*_test.go" --glob "!internal/tools/branches/**"

Update each consumer to import from the new package:

Before:

package tools

func registerBranchTools(server *mcp.Server, client *gitlabclient.Client) {
    // ... uses branchCreate, BranchCreateInput directly
}

After:

package tools

import "module/path/internal/tools/branches"

func registerBranchTools(server *mcp.Server, client *gitlabclient.Client) {
    // ... uses branches.Create, branches.CreateInput
}

Or better — move registration into the sub-package itself (see Step 7).

Verify after each consumer update: go build ./...

Step 7: Move Catalog Metadata

Create or update ${dstDir}/action_specs.go with canonical ActionSpecs() metadata:

package branches

import (
    gitlabclient "module/path/internal/gitlab"
    "module/path/internal/toolutil"
)

func ActionSpecs(client *gitlabclient.Client) []toolutil.ActionSpec {
  return []toolutil.ActionSpec{
    toolutil.NewActionSpec("create", toolutil.RouteAction(client, Create), toolutil.ActionSpecOptions{
      OwnerPackage:   "branches",
      IndividualTool: toolutil.IndividualToolSpec{Name: "gitlab_branch_create", Title: toolutil.TitleFromName("gitlab_branch_create")},
    }),
  }
}

Update the audited catalog aggregation/generation path if this is a new domain. Root runtime registration must remain catalog-backed; do not add new package-level RegisterMeta calls for ordinary GitLab actions.

Verify: go build ./...

Step 8: Move Tests

1. Copy ${srcFile}_test.go → ${dstDir}/${filename}_test.go

2. Change package: package tools → package branches

3. Update type references: BranchOutput → Output

4. Update function references: branchCreate(...) → Create(...)

5. Import test helpers (from toolutil or recreate locally):

   import "module/path/internal/toolutil/testutil"
   

6. If test helpers use newTestClient, either:

   • Import from a shared test utilities package
   • Or copy the helper into the test file (since it's small)

Verify:

go test ./${dstDir}/ -count=1 -v

Step 9: Remove Forwarding Stubs

Once ALL consumers are updated and ALL tests pass:

1. Delete the forwarding stub file from ${srcPkg}/
2. Delete the original test file from ${srcPkg}/

Verify:

go build ./...
go test ./internal/... -count=1

Step 10: Final Validation

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

Handling Complex Cases

Circular Import Prevention

If moving file A to package B would create a circular import:

tools → branches → tools (CIRCULAR!)

Solution: Extract the shared dependency to toolutil/:

tools → branches → toolutil (OK)
tools → toolutil (OK)

Shared Types Used Across Domains

If BranchOutput is used in another domain (e.g., merge_requests.go references branches):

1. Keep the type in the domain that owns it (branches.Output)
2. Have the other domain import it: import "module/path/internal/tools/branches"
3. OR if the type is truly cross-cutting, extract to toolutil/

Format Functions in markdown.go

markdown.go contains format* functions for EVERY domain. Options:

Option A (Recommended): Keep format functions in toolutil/markdown.go as a centralized formatter Option B: Move domain-specific formatters to their domain package Option C: Use an interface — each domain implements Formatter

Choose Option A for this project because format functions are simple and don't warrant an interface.

Test Helpers

The helpers_test.go file is shared by ALL domain tests. Options:

Option A: Extract to toolutil/testhelpers_test.go (only available in toolutil tests) Option B (Recommended): Create internal/testutil/ package with exported helpers Option C: Copy helpers into each domain test file (duplicated but simple)

Choose Option B for this project. Create:

package testutil

// NewTestClient creates a GitLab client pointed at a test HTTP server.
func NewTestClient(t *testing.T, handler http.Handler) *gitlabclient.Client { ... }

// RespondJSON writes a JSON response with the given status code and body.
func RespondJSON(w http.ResponseWriter, status int, body string) { ... }

// RespondJSONWithPagination writes a JSON response with GitLab pagination headers.
func RespondJSONWithPagination(w http.ResponseWriter, status int, body string, p PaginationHeaders) { ... }

Batch Processing Template

For moving multiple domains efficiently:

Batch 1: Extract shared utilities → toolutil/
  ├── Verify: go build && go test
  └── Commit: "refactor: extract shared utilities to internal/toolutil"

Batch 2: Move simple domains (health, users, tags, labels, milestones)
  ├── For each domain: create, move, stub, verify
  ├── Verify: go build && go test
  └── Commit: "refactor: modularize health/users/tags/labels/milestones"

Batch 3: Move medium domains (branches, commits, files, groups, pipelines)
  ├── Same pattern
  └── Commit: "refactor: modularize branches/commits/files/groups/pipelines"

Batch 4: Move complex multi-file domains (mergerequests, packages)
  ├── Consolidate files first, then move
  └── Commit: "refactor: modularize mergerequests and packages"

Batch 5: Clean up stubs, update docs
  └── Commit: "refactor: remove forwarding stubs, update documentation"

Rollback Strategy

If a migration batch goes wrong:

1. git stash or git checkout -- . to revert current changes
2. Review what broke (usually import paths or missing exports)
3. Fix the specific issue
4. Re-attempt the migration

Since each batch is committed separately, you can always git revert a single batch without affecting others.

GitLab client-go Awareness

When moving tool handlers that call the GitLab API, preserve these patterns exactly:

client-go Service Access

Every handler accesses the API via client.GL().{Service}.{Method}(). The client parameter is *gitlabclient.Client (alias for internal/gitlab.Client). This pattern does NOT change during migration — the client is passed as a parameter, not imported.

Import Requirements for Moved Files

After moving a tool handler to a sub-package, ensure these imports:

import (
    gl "gitlab.com/gitlab-org/api/client-go/v2"                        // For gl.*Options, gl.Ptr(), gl.WithContext()
    gitlabclient "github.com/jmrplens/gitlab-mcp-server/v2/internal/gitlab"  // For client type
    "github.com/jmrplens/gitlab-mcp-server/v2/internal/toolutil"             // For shared utilities
    "github.com/modelcontextprotocol/go-sdk/mcp"                          // For tool registration
)

Files With Low-Level HTTP Access

Some files (packages_stream.go, packages_chunked.go, uploads.go) use client.GL().NewRequest() and client.GL().Do() for direct HTTP calls. These also use client.GL().BaseURL() for URL construction. Ensure all three patterns work after the move.

Naming Inconsistency Fix

When moving repositories.go → projects/projects.go, this is a rename AND move. The file uses client.GL().Projects.* (not Repositories). Update the package doc comment to reflect that this is the Projects domain.

Domain Reference Hierarchy

The client-go API library (gitlab.com/gitlab-org/api/client-go/v2) is the source of truth for domain organization, type structures, and field definitions.

Before moving any domain:

1. Inspect client-go types first: Run go doc gitlab.com/gitlab-org/api/client-go/v2.{Type} for the domain's key types (e.g., gl.Branch, gl.CreateBranchOptions). This defines the canonical fields and API contract — use it to validate that type renames and field mappings are correct after the move.
2. Read the source file(s) (internal/tools/{domain}.go) to understand our implementation: handler functions, client.GL().{Service}.* calls, and our Input/Output struct subset.
3. If docs/tools/{domain}.md exists, read it for supplementary user-facing context. If no doc exists, go doc + source code provide everything needed.
4. Check catalog exposure: verify the domain appears in ActionSpecs and catalog aggregation. Uncataloged files are in-progress features — still move them, but note the gap.