Daily RefactorResearch and Plan

[github-actions[bot]]

Executive Summary

This research identifies systematic refactoring opportunities across the KSail Go codebase (742 Go files, ~149K LOC) to improve maintainability, readability, and structure. The analysis follows a top-down approach (Module → File → Function) and prioritizes incremental improvements that preserve all existing behavior.

Key Finding: The codebase is exceptionally well-structured with strong package organization (12 top-level packages), excellent test coverage (235 test files), and zero code duplication detected. However, several large files and complex functions could benefit from incremental refactoring to improve maintainability.

Codebase Overview

Package Structure

The codebase follows a flat, well-organized package structure:

• pkg/apis/ - API types and schemas (v1alpha1 cluster specs, enums)
• pkg/cli/ - CLI commands, UI components, and lifecycle orchestration
• pkg/client/ - Embedded tool clients (kubectl, helm, flux, docker, etc.)
• pkg/svc/ - Core services (providers, provisioners, installers, detectors)
• pkg/di/ - Dependency injection
• pkg/fsutil/ - Filesystem utilities and config managers
• pkg/k8s/ - Kubernetes helpers and templates
• pkg/notify/ - CLI notifications and progress display
• pkg/runner/ - Cobra command execution helpers
• pkg/timer/ - Command timing and performance tracking
• pkg/toolgen/ - AI tool generation utilities
• pkg/envvar/ - Environment variable utilities

Key Metrics

• Total Files: 742 Go files (741 in pkg/, 1 in internal/)
• Lines of Code: ~149,000 total lines
• Test Files: 235 test files
• Code Duplication: 0% (excellent!)
• Interfaces: 24 files define interfaces
• Large Files: 15 non-test files exceed 600 lines
• Complex Files: 9 files have 30+ functions

Refactoring Opportunities (Prioritized)

Priority 1: Large File Decomposition

1.1 pkg/client/kubectl/client.go (682 lines, 46 functions)

Issue: Single file wraps 46 kubectl commands with repetitive factory/config setup patterns.

Refactoring Strategy:

• Extract command factory setup into a separate factory.go helper
• Group related commands (CRUD operations, diagnostic commands, etc.) into logical subpackages
• Create a builder pattern for common command customization
• Reduce file to ~200-300 lines

Impact: Improved discoverability, easier testing, reduced cognitive load

---

1.2 pkg/apis/cluster/v1alpha1/enums.go (773 lines, 62 functions)

Issue: Single file contains all enum types and their validation/conversion methods, making it difficult to navigate.

Refactoring Strategy:

• Split into separate files by enum domain:
  • distribution.go - Distribution enum and methods
  • provider.go - Provider enum and methods
  • cni.go - CNI enum and methods
  • gitops.go - GitOps enum and methods
  • load_balancer.go - LoadBalancer enum and methods
  • storage.go - Storage enum and methods
  • enums.go - EnumValuer interface and shared utilities
• Maintain current API compatibility
• Each file ~100-150 lines

Impact: Better code organization, easier navigation, clearer domain boundaries

---

1.3 pkg/client/helm/client.go (754 lines, 32 functions)

Issue: Large file with complex Helm client operations mixing configuration, installation, and utility methods.

Refactoring Strategy:

• Extract configuration logic into config.go
• Extract repository operations into repo.go
• Extract chart operations into chart.go
• Keep core client in client.go (~200 lines)

Impact: Clearer separation of concerns, easier testing

---

1.4 pkg/svc/provider/hetzner/provider.go (844 lines, 34 functions)

Issue: Largest non-test file with multiple responsibilities (server lifecycle, network management, SSH key management).

Refactoring Strategy:

• Extract server lifecycle operations into server.go
• Extract network operations into network.go
• Extract SSH key operations into ssh.go
• Extract firewall operations into firewall.go
• Keep provider interface implementation in provider.go (~150 lines)

Impact: Better modularity, easier to test individual concerns

Priority 2: Function-Level Improvements

2.1 Long Functions (>100 lines)

Several files contain functions exceeding 100 lines, particularly in:

• pkg/cli/ui/chat/keyhandlers.go - Complex key handling logic
• pkg/cli/cmd/cluster/backup.go (722 lines, 20 functions)
• pkg/cli/cmd/cluster/restore.go (670 lines, 17 functions)
• pkg/cli/setup/post_cni.go (681 lines, 20 functions)

Refactoring Strategy:

• Extract sub-operations into helper functions
• Apply guard clauses to reduce nesting
• Use early returns for error conditions
• Extract validation logic into separate functions

Impact: Improved testability, reduced cyclomatic complexity

2.2 Complex Command Handlers

Files like pkg/cli/cmd/workload/gen/helm_release.go (754 lines) mix command setup, validation, and business logic.

Refactoring Strategy:

• Separate command setup from business logic
• Extract validation into dedicated validator functions
• Move generation logic to service layer
• Keep command handlers thin (~50-100 lines)

Impact: Better separation of concerns, easier testing

Priority 3: Code Quality Improvements

3.1 Error Handling Consistency

Observation: Mix of error wrapping styles across the codebase.

Refactoring Strategy:

• Standardize error wrapping using fmt.Errorf with %w
• Ensure all custom errors have clear, actionable messages
• Document error types and their usage

Impact: Better error diagnostics, consistent error handling

3.2 Interface Usage

Observation: 24 files define interfaces; some may be over-engineered or defined far from their usage.

Refactoring Strategy:

• Review each interface for necessity
• Move interfaces closer to their consumers (accept interfaces, return concrete types)
• Ensure interfaces have 1-3 methods (interface segregation)

Impact: Reduced coupling, clearer dependencies

3.3 Naming Consistency

Observation: Generally good naming, but some inconsistencies in method naming patterns.

Refactoring Strategy:

• Standardize method naming conventions
• Use verb-noun patterns consistently
• Ensure boolean methods start with Is, Has, Should

Impact: Improved code readability

Priority 4: Module-Level Improvements

4.1 Package Dependencies

Observation: Some packages have many imports, particularly pkg/cli/cmd/cluster/.

Refactoring Strategy:

• Review and minimize cross-package dependencies
• Consider facade patterns for complex subsystems
• Ensure clear dependency direction (e.g., CLI → Services → Client)

Impact: Reduced coupling, easier testing

4.2 Test Organization

Observation: 235 test files indicate good test coverage, but some test files are very large (e.g., pkg/client/docker/mocks.go - 10,489 lines).

Refactoring Strategy:

• Split large mock files by domain
• Use table-driven tests where applicable
• Extract test helpers into dedicated packages

Impact: Better test maintainability

Implementation Plan

The refactoring work will be executed incrementally over multiple workflow runs, with each run producing a small, focused pull request:

Phase 1: File Decomposition (Runs 1-4)

1. Run 1: Split pkg/apis/cluster/v1alpha1/enums.go into domain-specific files
2. Run 2: Decompose pkg/client/kubectl/client.go into logical groups
3. Run 3: Split pkg/client/helm/client.go into concern-based files
4. Run 4: Decompose pkg/svc/provider/hetzner/provider.go into operation-based files

Phase 2: Function Simplification (Runs 5-8)

5. Run 5: Refactor long functions in pkg/cli/ui/chat/keyhandlers.go
6. Run 6: Simplify command handlers in pkg/cli/cmd/cluster/backup.go
7. Run 7: Simplify command handlers in pkg/cli/cmd/cluster/restore.go
8. Run 8: Refactor pkg/cli/setup/post_cni.go into smaller functions

Phase 3: Code Quality (Runs 9-12)

9. Run 9: Standardize error handling patterns
10. Run 10: Review and simplify interface definitions
11. Run 11: Apply consistent naming conventions
12. Run 12: Optimize package dependencies

Phase 4: Test Organization (Runs 13-15)

13. Run 13: Split large mock files
14. Run 14: Consolidate test helpers
15. Run 15: Apply table-driven test patterns

Validation Strategy

Each refactoring run will include:

1. Build Validation: go build ./... must succeed
2. Test Validation: go test ./... must pass with no new failures
3. Lint Validation: golangci-lint run --timeout 5m must produce no new issues
4. Duplication Check: jscpd --config .jscpd.json must show 0% duplication (maintain current state)
5. Functional Validation: Key CLI commands must work correctly

Success Metrics

• Reduce average file size from current ~200 lines to ~150 lines
• Reduce maximum file size from 844 lines to <400 lines (non-test)
• Reduce maximum function length from >100 lines to <50 lines
• Maintain 0% code duplication
• Maintain or improve test coverage
• No new linting issues
• All existing tests pass

Risks and Mitigations

Risk	Impact	Mitigation
Breaking existing functionality	High	Comprehensive test suite, incremental changes, validation at each step
Merge conflicts with concurrent work	Medium	Small PRs, frequent integration, clear communication
Over-engineering	Medium	Stick to identified issues, avoid premature abstraction
Loss of code context	Low	Maintain clear file/package documentation

How to Control this Workflow

You can interact with this workflow using the following commands:

# Disable the workflow (stops scheduled runs)
gh aw disable daily-refactor --repo devantler-tech/ksail

# Enable the workflow (resumes scheduled runs)
gh aw enable daily-refactor --repo devantler-tech/ksail

# Run the workflow manually (optionally repeat multiple times)
gh aw run daily-refactor --repo devantler-tech/ksail --repeat 5

# View workflow logs
gh aw logs daily-refactor --repo devantler-tech/ksail

You can also add comments to this discussion to provide feedback or adjustments to the plan. The next workflow run will read your comments and adjust the approach accordingly.

What Happens Next

The next time this workflow runs, Phase 2 will be performed, which will:

1. Analyze existing CI files, build scripts, and documentation to determine validated build, test, lint, and formatting commands
2. Create .github/actions/daily-refactor/build-steps/action.yml with validated build steps
3. Create 1-3 refactoring guides in .github/instructions/ covering relevant refactoring patterns for this Go codebase
4. Create a pull request with these configuration files for maintainer review
5. Exit and wait for human review

After Phase 2 completes and the PR is merged, Phase 3 will begin on subsequent runs to implement actual refactoring improvements according to this plan.

If running in "repeat" mode, the workflow will automatically run again to proceed to the next phase without waiting for human intervention.

AI generated by Daily Refactor

• expires on Mar 9, 2026, 4:32 PM UTC

[github-actions[bot]]

Phase 3 Progress Update

Successfully completed Phase 1, Run 1 of the refactoring plan: Split pkg/apis/cluster/v1alpha1/enums.go into domain-specific files.

Work Completed

Refactored the 773-line enums.go file into 11 smaller, focused files:

• Largest file now 193 lines (Distribution) vs 773 originally
• Average file size reduced from 773 to 70 lines
• All tests pass ✅
• No new lint issues ✅
• 100% API compatibility maintained ✅

Pull Request

Draft PR created with detailed description of changes, validation results, and impact analysis.

Next Steps: Continue with Phase 1, Run 2 (decompose kubectl/client.go) after this PR is reviewed.

Generated by Daily Refactor