docs
This commit is contained in:
commit
3ef7c601bd
293
implementation.md
Normal file
293
implementation.md
Normal file
@ -0,0 +1,293 @@
|
||||
# Git Flow — Detailed Development Plan
|
||||
|
||||
## Overview
|
||||
|
||||
**Git Flow** is a Go CLI tool that discovers Git repositories under a user-specified parent directory, periodically scans their status, and presents findings with AI-driven suggestions for next actions (e.g., "commit pending changes", "push branch X", "pull latest from main").
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Project Scaffolding & Tooling
|
||||
|
||||
| Task | Details | Deliverable |
|
||||
|---|---|---|
|
||||
| **Module init** | `go mod init github.com/<user>/gitflow` | `go.mod` |
|
||||
| **Directory layout** | Flat-to-modular structure appropriate for a CLI (see layout below) | Dir tree |
|
||||
| **Tooling** | Add `golangci-lint` config, `Makefile`, `.gitignore` | Dev tooling |
|
||||
| **CI skeleton** | GitHub Actions: lint + test on push | `.github/workflows/ci.yml` |
|
||||
|
||||
### Recommended Directory Layout
|
||||
|
||||
```
|
||||
gitflow/
|
||||
├── cmd/gitflow/ # main entry point
|
||||
├── internal/
|
||||
│ ├── scanner/ # repo discovery + git status scanning
|
||||
│ ├── presenter/ # output formatting (table, JSON, TUI)
|
||||
│ ├── scheduler/ # periodic scan loop
|
||||
│ ├── ai/ # AI agent integration
|
||||
│ ├── config/ # CLI flags, env vars, config file parsing
|
||||
│ └── git/ # thin wrappers around git commands
|
||||
├── pkg/ # shared types (RepoInfo, Status, etc.)
|
||||
├── go.mod / go.sum
|
||||
├── Makefile
|
||||
├── .golangci.yml
|
||||
└── readme.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Core — Repo Discovery & Status Scanning
|
||||
|
||||
This is the foundational layer. Everything else depends on it.
|
||||
|
||||
### 1.1 Define the Domain Types (`pkg/types.go` or `internal/scanner/types.go`)
|
||||
|
||||
```go
|
||||
type RepoStatus int
|
||||
const (
|
||||
StatusUnknown RepoStatus = iota
|
||||
StatusClean
|
||||
StatusModified
|
||||
StatusAhead
|
||||
StatusBehind
|
||||
StatusDiverged
|
||||
StatusDetached
|
||||
StatusBare
|
||||
StatusError
|
||||
)
|
||||
|
||||
type RepoInfo struct {
|
||||
Path string
|
||||
RemoteURL string
|
||||
Branch string
|
||||
Status RepoStatus
|
||||
ModifiedFiles []string
|
||||
StagedFiles []string
|
||||
UntrackedFiles []string
|
||||
AheadBy int
|
||||
BehindBy int
|
||||
StashCount int
|
||||
LastFetch time.Time
|
||||
Error string
|
||||
}
|
||||
|
||||
type ScanResult struct {
|
||||
ScannedAt time.Time
|
||||
ParentDir string
|
||||
Repos []RepoInfo
|
||||
TotalCount int
|
||||
ErrorCount int
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 Repo Discovery (`internal/scanner/discover.go`)
|
||||
|
||||
- Walk the directory tree starting from the parent directory
|
||||
- Detect `.git` directories (including bare repos, submodules, worktrees)
|
||||
- Respect `.gitignore`-style exclusion patterns via a `--exclude` flag
|
||||
- Respect depth limits via a `--depth` / `--max-depth` flag
|
||||
- Use `filepath.WalkDir` for efficient traversal (no `os.FileInfo` allocations)
|
||||
|
||||
**Pattern**: Single-responsibility — the discoverer only finds repos; status scanning is a separate step.
|
||||
|
||||
### 1.3 Status Scanner (`internal/scanner/status.go`)
|
||||
|
||||
- For each discovered repo, run `git` porcelain commands:
|
||||
- `git status --porcelain -b` for branch, ahead/behind, modified/staged/untracked
|
||||
- `git remote -v` for remote URL
|
||||
- `git stash list` for stash count
|
||||
- Parse output into `RepoInfo`
|
||||
- **Resilience patterns** from Go skill:
|
||||
- Timeout each `git` command (e.g., 10s via `context.WithTimeout`)
|
||||
- Handle repos with errors gracefully — mark as `StatusError`, don't crash
|
||||
- Run scans concurrently with a bounded worker pool (`errgroup` + semaphore)
|
||||
|
||||
### 1.4 Git Command Wrapper (`internal/git/`)
|
||||
|
||||
- Thin wrapper: `func Status(ctx context.Context, repoPath string) (RepoInfo, error)`
|
||||
- Uses `os/exec` with context for cancellation/timeout
|
||||
- No external git library dependency — `os/exec` is sufficient for porcelain commands
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: CLI & Configuration
|
||||
|
||||
### 2.1 CLI Framework
|
||||
|
||||
Use **Cobra** + **Viper** (standard Go CLI stack):
|
||||
|
||||
| Flag | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `--dir` / `-d` | string | `.` (cwd) | Parent directory to scan |
|
||||
| `--interval` / `-i` | duration | `0` (run once) | Rescan interval (e.g., `5m`, `30s`) |
|
||||
| `--format` / `-f` | string | `table` | Output format: `table`, `json`, `compact` |
|
||||
| `--exclude` | []string | `[]` | Glob patterns to exclude |
|
||||
| `--max-depth` | int | `0` (unlimited) | Max traversal depth |
|
||||
| `--ai` | bool | `false` | Enable AI suggestions |
|
||||
| `--ai-provider` | string | `openai` | AI backend |
|
||||
| `--ai-model` | string | `gpt-4o` | AI model |
|
||||
| `--watch` / `-w` | bool | `false` | Watch mode (alias for interval) |
|
||||
|
||||
### 2.2 Configuration File
|
||||
|
||||
Support `~/.gitflow.yaml` for defaults:
|
||||
|
||||
```yaml
|
||||
ai:
|
||||
provider: openai
|
||||
api_key_env: OPENAI_API_KEY
|
||||
model: gpt-4o
|
||||
defaults:
|
||||
interval: 5m
|
||||
format: table
|
||||
exclude:
|
||||
- "node_modules"
|
||||
- "vendor"
|
||||
```
|
||||
|
||||
### 2.3 Commands
|
||||
|
||||
```
|
||||
gitflow scan # one-shot scan
|
||||
gitflow watch # periodic scan (uses --interval)
|
||||
gitflow config # show/edit config
|
||||
gitflow version # version info
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Presentation Layer
|
||||
|
||||
### 3.1 Table Output (default)
|
||||
|
||||
Rich terminal table using `bubbletea` / `lipgloss` (or simpler: `tablewriter`):
|
||||
|
||||
```
|
||||
REPOSITORY BRANCH STATUS AHEAD/BEHIND CHANGES
|
||||
~/projects/api main ✓ clean 0 / 0 -
|
||||
~/projects/web feat/login ✗ modified 3 / 0 2M, 1U
|
||||
~/projects/lib main ⚠ behind 0 / 5 -
|
||||
~/projects/legacy (detached) ⚠ detached - -
|
||||
|
||||
4 repos scanned | 1 clean | 2 need attention | 2 errors
|
||||
```
|
||||
|
||||
### 3.2 JSON Output
|
||||
|
||||
For scripting / piping:
|
||||
|
||||
```json
|
||||
{
|
||||
"scanned_at": "2026-01-01T12:00:00Z",
|
||||
"parent_dir": "/home/user/projects",
|
||||
"repos": [...],
|
||||
"summary": {"total": 4, "clean": 1, "attention": 2, "errors": 1}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Compact Output
|
||||
|
||||
One line per repo with color-coded status symbols.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Periodic Scanner (Scheduler)
|
||||
|
||||
### 4.1 Watch Mode (`internal/scheduler/scheduler.go`)
|
||||
|
||||
- Runs scan on a `time.Ticker` at the configured interval
|
||||
- Clears terminal and re-renders (or uses TUI refresh)
|
||||
- Handles SIGINT/SIGTERM for graceful shutdown
|
||||
- Shows time until next scan in footer
|
||||
|
||||
**Pattern**: Use `signal.NotifyContext` for graceful shutdown. Defer cleanup immediately after resource acquisition.
|
||||
|
||||
### 4.2 Change Detection
|
||||
|
||||
- Between scans, compare current vs previous `ScanResult`
|
||||
- Highlight repos that changed state
|
||||
- Optionally trigger desktop notifications (via `beeep` or `notify-send`)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: AI Agent Integration
|
||||
|
||||
### 5.1 AI Module (`internal/ai/`)
|
||||
|
||||
**Interface-first design** (for testability and provider flexibility):
|
||||
|
||||
```go
|
||||
type Provider interface {
|
||||
Suggest(ctx context.Context, repos []RepoInfo) ([]Suggestion, error)
|
||||
}
|
||||
|
||||
type Suggestion struct {
|
||||
RepoPath string
|
||||
Action string // "commit", "push", "pull", "stash", "pr", "cleanup"
|
||||
Message string // Human-readable suggestion
|
||||
Command string // Suggested git command to run
|
||||
Priority int // 0=low, 1=medium, 2=high
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 Providers
|
||||
|
||||
1. **OpenAI** (default): GPT-4o with structured output (JSON Schema) for reliable parsing
|
||||
2. **Ollama** (local/offline): Support for local models
|
||||
3. **Anthropic Claude**: Alternative cloud provider
|
||||
|
||||
### 5.3 Prompt Design
|
||||
|
||||
Construct a prompt that includes:
|
||||
- A summary table of all repos and their statuses
|
||||
- The top 3-5 repos needing attention
|
||||
- Instructions to output structured JSON with specific action types
|
||||
|
||||
### 5.4 AI Output Display
|
||||
|
||||
- Show suggestions in a separate section below the status table
|
||||
- Color-coded by priority
|
||||
- Optional: `--ai-execute` flag to auto-run suggested commands (with confirmation)
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Polish & Advanced Features
|
||||
|
||||
| Feature | Description |
|
||||
|---|---|
|
||||
| **Color themes** | Light/dark terminal themes via `lipgloss` |
|
||||
| **TUI mode** | Full interactive TUI with `bubbletea` — navigate repos, expand details, trigger AI suggestions |
|
||||
| **Custom actions** | User-defined rules: "if behind > 10 commits, mark as critical" |
|
||||
| **Webhook/notifications** | Send alerts to Slack/Discord when repos need attention |
|
||||
| **Multi-platform** | Test on Linux, macOS, Windows (WSL) |
|
||||
| **Completion** | Shell completions for bash, zsh, fish via Cobra |
|
||||
|
||||
---
|
||||
|
||||
## Technology Choices Summary
|
||||
|
||||
| Concern | Choice | Rationale |
|
||||
|---|---|---|
|
||||
| CLI framework | Cobra + Viper | Industry standard, completions, env binding |
|
||||
| Git interaction | `os/exec` (porcelain) | No dependency needed; porcelain output is stable |
|
||||
| TUI (optional) | Bubble Tea + Lip Gloss | Best Go TUI ecosystem |
|
||||
| AI integration | HTTP client + JSON Schema | Provider-agnostic, no heavy SDK required |
|
||||
| Concurrency | `errgroup` + semaphore | Bounded parallelism, error propagation |
|
||||
| Testing | `testing` + `testify` | Standard + assertions |
|
||||
| Linting | `golangci-lint` | Comprehensive Go linting |
|
||||
|
||||
---
|
||||
|
||||
## Milestone Schedule
|
||||
|
||||
| Milestone | Scope | Estimated Effort |
|
||||
|---|---|---|
|
||||
| **M1 — Skeleton** | Phase 0: module, layout, Makefile, CI | 0.5 day |
|
||||
| **M2 — Discovery** | Phase 1: repo walker + git status parser | 1–2 days |
|
||||
| **M3 — CLI** | Phase 2: Cobra commands, flags, config | 1 day |
|
||||
| **M4 — Display** | Phase 3: table + JSON + compact output | 1 day |
|
||||
| **M5 — Watch** | Phase 4: scheduler, auto-refresh, signals | 1 day |
|
||||
| **M6 — AI** | Phase 5: provider interface, OpenAI, suggestions | 1–2 days |
|
||||
| **M7 — Polish** | Phase 6: TUI, themes, completions, docs | 2–3 days |
|
||||
|
||||
**Total estimated effort**: ~7–10 days for a solid v1.0
|
||||
8
readme.md
Normal file
8
readme.md
Normal file
@ -0,0 +1,8 @@
|
||||
# git flow is CLI app writen go.
|
||||
|
||||
App will explore [] all git repos leaving on our machine.
|
||||
it will ask for parent directory.
|
||||
will scan status of our repos
|
||||
and present it to the user.
|
||||
app will scan repos in set interval [and present findings, integrated ai agent
|
||||
will suggest next steps/actions]
|
||||
Loading…
Reference in New Issue
Block a user