feat: StackShift CLI with bulk migration orchestration #6
Conversation
## Overview Enterprise-grade CLI tool for orchestrating StackShift across dozens or hundreds of repositories simultaneously. ## What's Included ### StackShift CLI (Go + Charm TUI) - Beautiful terminal interface for bulk repo migration - Auto-discovers repos recursively from ~/git/ or custom path - Multi-select interface with visual progress tracking - Configurable parallel execution (1-10 repos at once) - Resume from failures with state persistence ### Multi-AI Backend Support - Claude Code: For users with Claude Code access - OpenCode + CoPilot: For VSCode/CoPilot users - Automatically selects appropriate backend per user ### 6-Gear Orchestration - Manual mode: Step-by-step control through each gear - Cruise Control: Automated progression through all 6 gears - Handles bulk migrations at enterprise scale ### Configuration Options - Route: greenfield (new stack) | brownfield (existing) - Transmission: manual (controlled) | cruise-control (automated) - Clarification strategy: prompt | defer | skip - Implementation scope: none | p0 | p0_p1 | all - Parallel limit: 1-10 repos - AI backend selection ### Files Added - cli/stackshift-cli/main.go - TUI application with repo selection - cli/stackshift-cli/orchestrator.go - Batch execution engine - cli/stackshift-cli/go.mod - Go dependencies - cli/stackshift-cli/README.md - Full documentation - cli/stackshift-cli/QUICKSTART.md - Quick start guide ### Documentation Added - IMPLEMENTATION_ROADMAP.md - Path to full automation vision - PROMPT_IMPROVEMENTS.md - Recommendations for prompt enhancements ## Use Case Built for enterprise teams migrating large portfolios of applications. Enables systematic transformation of legacy codebases into modern, spec-driven applications at scale. ## Status Initial implementation with core TUI, orchestration, and multi-AI support. Ready for testing and iteration.
Add enterprise-grade bulk migration orchestrator with actual execution capabilities for processing dozens or hundreds of repositories in parallel. Core Features: - Beautiful TUI with repository auto-discovery and selection - Dual AI backend support (Claude Code and VSCode/Copilot) - Parallel batch orchestration with configurable limits - Real-time progress tracking with animated spinner - State management via .stackshift-state.json files - Comprehensive settings for route, transmission, and clarification strategies Implementation Details: - Execution engine creates orchestrator and runs gears in background - Command builders for both Claude Code (via slash commands) and OpenCode (via prompt files) - Message-based architecture for execution updates and progress tracking - Gear-specific icons and status displays - Results validation through state file checking Technical Stack: - Go with Charm libraries (Bubbletea for TUI, Lipgloss for styling) - Concurrent execution with sync primitives - Log aggregation and error handling - Configurable parallel processing limits This enables teams to migrate large application portfolios efficiently with proper tracking, progress monitoring, and result validation.
Reorganize documentation files into logical directories to reduce root-level sprawl and improve discoverability. Changes: - Move planning documents to docs/planning/ - IMPLEMENTATION_ROADMAP.md - FEATURE_GAP_ANALYSIS.md - PROMPT_IMPROVEMENTS.md - Move review documents to docs/reviews/ - All DOCUMENTATION_*.md files - analysis-report.md - test-coverage-analysis.md - Update docs/README.md with complete structure overview - Add planning and review sections - Update file tree diagram - Add links to all document categories This improves navigation and keeps the repository root clean with only essential user-facing documentation.
Add animated loading screen while discovering repositories to provide better user feedback during the initial scan phase. Changes: - Add LoadingMode state with spinner animation - Load repositories asynchronously in background - Display loading message with progress indicator - Transition to SelectMode when repos are loaded - Support quit during loading phase This improves UX by showing immediate feedback instead of appearing frozen while scanning large directory trees for Git repositories.
Create comprehensive specification document for the implemented CLI orchestration tool, detailing all features, requirements, and implementation details. Specification includes: - Functional requirements (FR1-FR9) - Non-functional requirements (performance, usability, reliability) - Technical specifications and architecture - Implementation phases (all complete) - Testing strategy and success criteria - Future enhancement roadmap Update production readiness README to include F007 spec with completed status.
There was a problem hiding this comment.
Pull Request Overview
This PR implements an enterprise-grade CLI tool for bulk repository migration orchestration, enabling teams to migrate multiple applications using StackShift's 6-gear process. The CLI features a beautiful TUI built with Charm libraries (Bubbletea + Lipgloss), repository auto-discovery, parallel orchestration, and support for both Claude Code and VSCode/Copilot backends.
Key Changes
- New CLI Tool: Complete Go implementation with TUI for bulk migration orchestration
- Parallel Execution: Configurable batch processing with real-time progress tracking
- Documentation Organization: Moved planning and review documents to structured directories
- Dual AI Backend Support: Integration for both Claude Code and OpenCode/VSCode
Reviewed Changes
Copilot reviewed 11 out of 20 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| cli/main.go | Main TUI implementation with state management and UI rendering (781 lines) |
| cli/orchestrator.go | Parallel execution engine with command building and validation (451 lines) |
| cli/go.mod, cli/go.sum | Go module configuration with Charm library dependencies |
| cli/README.md, cli/QUICKSTART.md | Comprehensive CLI documentation and usage guides |
| docs/README.md | Updated documentation structure with planning and review sections |
| docs/planning/*.md | Planning documents moved to organized location |
| docs/reviews/*.md | Review documents moved to organized location |
Comments suppressed due to low confidence (2)
cli/orchestrator.go:1
- Temporary files created in os.TempDir() are never cleaned up. The orchestrator creates one temp file per gear per repository, which could accumulate hundreds of files over time. Consider cleaning up temp files after execution completes or using a dedicated temp directory that gets cleaned on program exit.
package main
cli/orchestrator.go:1
- The format string uses repo.Name twice but should use gearName for the second parameter. This means all gears for the same repository will overwrite the same temp file. Should be: fmt.Sprintf('stackshift_%s_%s.md', repo.Name, gearName)
package main
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| // Run command | ||
| startTime := time.Now() | ||
| err = cmd.Run() |
There was a problem hiding this comment.
The error from cmd.Run() is captured but the actual error message from stderr is not included in the returned GearResult. Users will see 'Command failed after X duration: exit status 1' without seeing what actually went wrong. Consider reading from the log file or capturing stderr separately to provide more helpful error messages.
| ) | ||
|
|
||
| // Use claude CLI with the prompt | ||
| return exec.Command("claude", prompt) |
There was a problem hiding this comment.
The prompt variable is constructed from user-controllable inputs (repo.Name, repo.Path, etc.) and passed directly to exec.Command without validation or sanitization. If repository names or paths contain shell metacharacters, this could lead to command injection. Use exec.Command with separate arguments or validate/sanitize the inputs first.
| if _, err := exec.LookPath("code"); err == nil { | ||
| // Use VSCode CLI to open the prompt file and repository | ||
| return exec.Command("code", repo.Path, tmpFile) | ||
| } |
There was a problem hiding this comment.
The exec.Command for VSCode CLI will open the files in the editor but won't actually execute StackShift. The returned command doesn't perform any migration work - it just opens files. This makes the OpenCode backend non-functional. Need to either invoke a script that opens AND runs the migration, or document that this is a manual workflow.
| filepath.Walk(searchPath, func(path string, info os.FileInfo, err error) error { | ||
| if err != nil { | ||
| return nil | ||
| } |
There was a problem hiding this comment.
Errors during directory traversal are silently ignored by returning nil. If there are permission errors or filesystem issues, users won't know why certain repositories weren't discovered. Consider logging errors or collecting them to display after discovery completes.
| func checkProgress(repoPath string) (int, string) { | ||
| // Check for .stackshift-state.json | ||
| stateFile := filepath.Join(repoPath, ".stackshift-state.json") | ||
| if _, err := os.Stat(stateFile); err == nil { | ||
| // Parse state file (simplified) | ||
| // Would actually parse JSON and check completedSteps | ||
| return 0, "not_started" | ||
| } |
There was a problem hiding this comment.
The checkProgress function has a TODO comment but always returns (0, 'not_started') even when a state file exists. This means the CLI won't properly detect which gear a repository is on, causing it to restart from Gear 1 every time. This should parse the JSON and return the actual currentGear and status from the state file.
| func (o *Orchestrator) validateGear1(repo Repository) (bool, string) { | ||
| // Check for analysis-report.md | ||
| reportPath := filepath.Join(repo.Path, "analysis-report.md") | ||
| if _, err := os.Stat(reportPath); os.IsNotExist(err) { | ||
| return false, "analysis-report.md not found" | ||
| } |
There was a problem hiding this comment.
The validateGear1 and validateGear2 functions are defined but never called. The validateGear function only checks the state file but doesn't verify that output files exist. This means a gear could be marked complete in the state file without actually producing its expected outputs. Either use these validation functions or remove them to avoid confusion.
Create comprehensive summary document explaining StackShift's GitHub Spec Kit integration including: - What changed (constitution v1.1.0, directory structure, specs created) - 7 specifications created with complete details - Conversion tools for existing repos - Workflow improvements and benefits - Implementation roadmap with priorities - Quick reference for all new files This document serves as the master reference for understanding how StackShift now fully integrates with and outputs GitHub Spec Kit formatted specifications.
jschulte
changed the title
|
@copilot Please either make a PR to fix all of the issues you identified in this PR, or just make a commit to this branch with the changes if you're able to do that. |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Summary
Implements enterprise-grade CLI tool for bulk repository migration orchestration, enabling teams to efficiently migrate dozens or hundreds of applications using StackShift's 6-gear process.
Features
Core Functionality
User Experience
Configuration
Implementation Details
Architecture
cli/main.go): State management, UI rendering, user input handlingcli/orchestrator.go): Parallel execution engine, command building, validationExecution Flow
AI Backend Integration
Claude Code:
claudeCLIOpenCode/VSCode:
Documentation
Quality Improvements
Documentation Organization
docs/planning/docs/reviews/docs/README.mdwith complete structureBuild System
Testing
Builds successfully with
go build -o stackshift-cliReady for testing with actual repositories.
Enterprise Use Case
This tool enables organizations to:
Next Steps
After merge: