How mubbie/stacksmith works
Project type and purpose
• This is a Go-based CLI application (with a fallback Bash script) for managing “stacked” Git branches and PRs. It provides both a simple menu UI and a richer TUI (terminal UI) built on Bubble Tea and Lip Gloss.
Top-level architecture and file structure analysis
• cmd/ → command definitions and entry points
• internal/ → core logic (git operations, caching, error handling), configuration, logging, rendering, UI implementations
• pkg/plugins/ → plugin interface and loading
• scripts/ → standalone Bash version (stacksmith-lite.sh)
• build/ → completion scripts, installer definitions
• assets/ → static ANSI art and UI tapes
• docs/ → planning and roadmap
• main.go → root of the Go edition CLI
• Makefile, goreleaser.yaml → build and release automation
Main components
a. CLI Entrypoint
• main.go → invokes cmd/root.go (cobra or custom parser)
• cmd/\*.go → individual commands: stack, sync, push, fixpr, graph, tui, completion
b. Core Service Layer (internal/core)
• git.go: wraps vanilla Git operations (rebase, push, branch stacking)
• cache.go, stack.go, errors.go: business logic for managing stacks
c. Configuration & Logging
• internal/config/config.go: loads user config (flags, env vars, config files)
• internal/logger/logger.go: structured logging backend
d. Rendering & UI
• internal/render/printer.go: plain-text output for non-interactive commands
• internal/ui/simplemenu: lightweight menu prompts for menu-based flows
• internal/ui/fulltui: Bubble Tea models, views, status bars, DAG renderer
• internal/ui/styles: shared styling definitions
e. Plugin System
• pkg/plugins/plugins.go: plugin registration and hook points
f. Bash fallback
• scripts/stacksmith-lite.sh: zero-dependency script for minimal environments
g. Build & Release
• build/completions: auto-generated shell completions
• build/installer: Windows installer scripts (InnoSetup)
• goreleaser.yaml & Makefile: cross-platform build, release, packaging
Relationships and data flows
• User runs stacksmith <command> → main.go → cmd/<command>.Run
• Command layer invokes internal/config to load settings → internal/logger to initialize logs
• Business logic in internal/core performs Git operations (executes git under the hood)
• Results flow to either internal/render for stdout printing or to internal/ui for interactive flows
• internal/ui produces terminal UI frames and handles user events → may call back into core for further operations
• pkg/plugins can inject or extend commands or hooks into core workflows
• build pipeline reads cmd/ and internal/ to compile Go binaries, then generates completions and installers
Architectural patterns & design principles
• Layered architecture (entrypoint → config → core → render/UI → external Git)
• Modular commands (each subcommand isolated under cmd/)
• Separation of concerns: core logic vs. UI vs. config vs. logging
• Plugin extensibility via pkg/plugins
• Build automation via Makefile and GoReleaser