Overview

The file pkg/cli/remote_workflow.go has grown to 1255 lines, combining five distinct functional domains into a single monolithic file. This makes the code harder to maintain, test, and understand. Splitting this file into smaller, focused modules will improve code organization and maintainability.

Current State

• File: pkg/cli/remote_workflow.go
• Size: 1255 lines
• Functions: 15 public and private functions
• Test Coverage: 1735 lines in remote_workflow_test.go with 60 test cases
• Status: Well-tested but monolithic

Functional Analysis

The file contains five distinct, semi-independent domains:

1. Workflow Source Fetching (lines 36-157): Core public API for fetching workflows

   • FetchWorkflowFromSource() - Main entry point
   • fetchLocalWorkflow() - Local filesystem access
   • fetchRemoteWorkflow() - GitHub API integration
   • Responsibilities: Local/remote workflow resolution, commit SHA tracking

2. Include File Fetching (lines 158-577): Remote includes and frontmatter imports

   • FetchIncludeFromSource() - Include file fetching
   • fetchAndSaveRemoteFrontmatterImports() - Frontmatter import handling
   • fetchFrontmatterImportsRecursive() - Recursive import resolution
   • fetchAndSaveRemoteIncludes() - @include directive processing
   • Responsibilities: Include resolution, recursive import handling, file I/O

3. Dispatch Workflow Processing (lines 628-1078): Dispatch workflow extraction and management

   • extractDispatchWorkflowNames() - Parse workflow names from YAML
   • fetchAndSaveRemoteDispatchWorkflows() - Download and track dispatch workflows
   • fetchAndSaveDispatchWorkflowsFromParsedFile() - Handle dispatch workflows from parsed files
   • Responsibilities: Workflow name extraction, dispatch workflow downloading, conflict detection

4. Resource File Handling (lines 852-1077): Resource file fetching and caching

   • extractResources() - Parse resource paths from workflows
   • fetchAndSaveRemoteResources() - Download and track resource files
   • Responsibilities: Resource extraction, remote resource downloading

5. Helper Utilities (lines 579-627): Shared utility functions

   • getParentDir() - Path manipulation
   • readSourceRepoFromFile() - Source metadata reading
   • sourceRepoLabel() - Label formatting
   • Responsibilities: Path utilities, metadata helpers

Refactoring Strategy

Proposed File Splits

Based on functional domain analysis, split the file into the following modules:

1. fetch.go (Core workflow fetching)

   • Public: FetchWorkflowFromSource(), FetchedWorkflow type
   • Private: fetchLocalWorkflow(), fetchRemoteWorkflow()
   • Estimated LOC: 180-200
   • Responsibility: High-level workflow fetching orchestration

2. includes.go (Include file and frontmatter import handling)

   • Public: FetchIncludeFromSource()
   • Private: fetchAndSaveRemoteFrontmatterImports(), fetchFrontmatterImportsRecursive(), fetchAndSaveRemoteIncludes()
   • Estimated LOC: 350-400
   • Responsibility: Recursive include resolution and import management

3. dispatch.go (Dispatch workflow extraction and processing)

   • Public: None (all functions are internal orchestration)
   • Private: extractDispatchWorkflowNames(), fetchAndSaveRemoteDispatchWorkflows(), fetchAndSaveDispatchWorkflowsFromParsedFile()
   • Estimated LOC: 300-350
   • Responsibility: Dispatch workflow discovery, fetching, and conflict detection

4. resources.go (Resource file handling)

   • Public: None (internal orchestration)
   • Private: extractResources(), fetchAndSaveRemoteResources()
   • Estimated LOC: 200-250
   • Responsibility: Resource extraction and remote file downloading

5. helpers.go (Utility functions shared across modules)

   • Public: None (all are private helpers)
   • Private: getParentDir(), readSourceRepoFromFile(), sourceRepoLabel()
   • Estimated LOC: 50-70
   • Responsibility: Path utilities, metadata helpers, string formatting

Dependencies Between Modules

┌─────────────┐
│  fetch.go   │  (Core API, references helpers)
└──────┬──────┘
       │ (imports)
       ├─────────────────────┬──────────────────┬──────────────┐
       │                     │                  │              │
   helpers.go          includes.go        dispatch.go     resources.go
                       (includes fetch)   (calls fetch)   (calls fetch)

• fetch.go: Low coupling, references helpers only
• includes.go: References fetch (for orchestration), helpers
• dispatch.go: References fetch (public entry point), helpers
• resources.go: References fetch (public entry point), helpers
• helpers.go: No dependencies on other modules

Interface Abstractions

Consider introducing interfaces to reduce coupling between modules:

// In helpers.go or a new interfaces.go
type RemoteFetcher interface {
    Fetch(owner, repo, ref, path string) ([]byte, error)
}

type ResourceHandler interface {
    ExtractResources(content string) ([]string, error)
    SaveResources(content, targetDir string, spec *WorkflowSpec, verbose bool, force bool) error
}

This allows modules to be tested independently with mock implementations.

Implementation Guidelines

1. Preserve Public API: Keep FetchWorkflowFromSource() and FetchedWorkflow in fetch.go for backward compatibility
2. Update Imports: All modules import pkg/console, pkg/logger, pkg/parser, pkg/workflow
3. Shared State: Move FetchedWorkflow type definition to common location (consider helpers.go)
4. Error Handling: Maintain consistent error wrapping with fmt.Errorf() and context messages
5. Logging: Each file has its own logger (e.g., fetchLog, includesLog, dispatchLog)
6. Incremental Changes: Split one module at a time, run tests after each split

Acceptance Criteria

• Original remote_workflow.go is split into 5 focused files (fetch.go, includes.go, dispatch.go, resources.go, helpers.go)
• Each new file is under 400 lines
• All tests pass (make test-unit)
• Test coverage is ≥85% for each new file
• No breaking changes to public API (FetchWorkflowFromSource, FetchdWorkflow)
• Code passes linting (make lint)
• Build succeeds (make build)
• Integration tests verify module boundaries (test cross-file interactions)

# After making changes
make fmt              # Format code
make test-unit        # Run unit tests
make lint             # Check for issues
make build            # Verify build succeeds

make agent-finish     # Complete validation

Priority: Medium
Effort: Large (multiple files, significant test migration)
Expected Impact: Improved code organization, easier to understand and maintain, better test isolation

Generated by Daily File Diet · ◷

• expires on Mar 12, 2026, 1:35 PM UTC