423 lines
12 KiB
Markdown
423 lines
12 KiB
Markdown
## Milestone 1: Action Log and onx init
|
|
|
|
### Action Log Implementation
|
|
|
|
13. **Create oplog binary format** (`internal/storage/oplog.go`)
|
|
```go
|
|
type OplogEntry struct {
|
|
ID uint64
|
|
ParentID uint64
|
|
Timestamp int64
|
|
Command string
|
|
StateBefore map[string]string
|
|
StateAfter map[string]string
|
|
}
|
|
```
|
|
|
|
14. **Implement oplog writer** (`internal/storage/oplog_writer.go`)
|
|
- `OpenOplog(path string) (*OplogWriter, error)`
|
|
- `AppendEntry(entry *OplogEntry) error`
|
|
- Use binary encoding (gob or protobuf)
|
|
- Implement file locking for concurrent access
|
|
|
|
15. **Implement oplog reader** (`internal/storage/oplog_reader.go`)
|
|
- `ReadLastEntry() (*OplogEntry, error)`
|
|
- `ReadEntry(id uint64) (*OplogEntry, error)`
|
|
- `GetUndoStack() ([]*OplogEntry, error)`
|
|
|
|
16. **Create transactional wrapper** (`internal/core/transaction.go`)
|
|
```go
|
|
func ExecuteWithTransaction(repo *Repository, cmd string,
|
|
fn func() error) error {
|
|
// 1. Capture state_before
|
|
// 2. Create oplog entry
|
|
// 3. Execute fn()
|
|
// 4. Capture state_after
|
|
// 5. Finalize oplog entry
|
|
// 6. Handle rollback on error
|
|
}
|
|
```
|
|
|
|
### onx init Command
|
|
|
|
17. **Implement init command** (`internal/commands/init.go`)
|
|
- Create .git directory (via go-git)
|
|
- Create .onx directory structure
|
|
- Initialize empty oplog file
|
|
- Create default workstreams.json
|
|
- Create workspace pointer file
|
|
- Add .onx to .gitignore
|
|
|
|
18. **Create CLI structure** (`cmd/onx/main.go`)
|
|
```go
|
|
func main() {
|
|
rootCmd := &cobra.Command{
|
|
Use: "onx",
|
|
Short: "The iPhone of Version Control",
|
|
}
|
|
rootCmd.AddCommand(commands.InitCmd())
|
|
rootCmd.Execute()
|
|
}
|
|
```
|
|
|
|
### onx undo Command
|
|
|
|
19. **Implement undo logic** (`internal/commands/undo.go`)
|
|
- Read last oplog entry
|
|
- Restore all refs from state_before
|
|
- Update workspace pointer
|
|
- Mark entry as undone in oplog
|
|
- Perform git checkout to restore working directory
|
|
|
|
20. **Add undo tests** (`internal/commands/undo_test.go`)
|
|
- Test undo after init
|
|
- Test sequential undos
|
|
- Test undo with nothing to undo
|
|
|
|
## Milestone 2: Transparent Versioning and onx save
|
|
|
|
### Filesystem Daemon Implementation
|
|
|
|
21. **Create daemon structure** (`internal/daemon/daemon.go`)
|
|
```go
|
|
type Daemon struct {
|
|
repo *Repository
|
|
watcher *fsnotify.Watcher
|
|
ticker *time.Ticker
|
|
debounce time.Duration
|
|
shutdown chan bool
|
|
}
|
|
```
|
|
|
|
22. **Implement filesystem watching** (`internal/daemon/watcher.go`)
|
|
- Initialize fsnotify watcher
|
|
- Add repository root to watch list
|
|
- Recursively watch subdirectories
|
|
- Filter out .git and .onx directories
|
|
- Implement debouncing (500ms)
|
|
|
|
23. **Implement snapshot algorithm** (`internal/daemon/snapshot.go`)
|
|
```go
|
|
func (d *Daemon) CreateSnapshot() error {
|
|
// 1. Read current workspace pointer
|
|
// 2. Create tree from working directory
|
|
// 3. Create ephemeral commit
|
|
// 4. Update refs/onyx/workspaces/current
|
|
// 5. Update .onx/workspace pointer
|
|
}
|
|
```
|
|
|
|
24. **Create daemon entry point** (`cmd/onxd/main.go`)
|
|
- Parse command line flags (repo path, interval)
|
|
- Initialize daemon
|
|
- Set up signal handlers (SIGTERM, SIGINT)
|
|
- Run main loop
|
|
|
|
25. **Implement daemon control** (`internal/commands/daemon.go`)
|
|
- `onx daemon start` - Start background daemon
|
|
- `onx daemon stop` - Stop daemon gracefully
|
|
- `onx daemon status` - Check daemon status
|
|
- Use PID file in .onx/daemon.pid
|
|
|
|
### onx save Command
|
|
|
|
26. **Implement save command** (`internal/commands/save.go`)
|
|
```go
|
|
func Save(repo *Repository, message string) error {
|
|
// 1. Read current ephemeral commit
|
|
// 2. Create new commit with user message
|
|
// 3. Determine next branch number
|
|
// 4. Create branch ref
|
|
// 5. Update workstreams.json
|
|
// 6. Log to oplog
|
|
}
|
|
```
|
|
|
|
27. **Add message validation**
|
|
- Require non-empty message
|
|
- Validate message length (max 72 chars for title)
|
|
- Support multi-line messages with -m flag
|
|
|
|
## Milestone 3: Workstreams
|
|
|
|
### Workstream Data Model
|
|
|
|
28. **Implement workstream storage** (`internal/storage/workstreams.go`)
|
|
```go
|
|
type WorkstreamsFile struct {
|
|
CurrentWorkstream string
|
|
Workstreams map[string]*Workstream
|
|
}
|
|
|
|
func LoadWorkstreams(path string) (*WorkstreamsFile, error)
|
|
func (w *WorkstreamsFile) Save(path string) error
|
|
```
|
|
|
|
29. **Create workstream manager** (`internal/core/workstream_manager.go`)
|
|
- `CreateWorkstream(name string, base string) error`
|
|
- `GetCurrentWorkstream() (*Workstream, error)`
|
|
- `SwitchWorkstream(name string) error`
|
|
- `ListWorkstreams() ([]*Workstream, error)`
|
|
- `AddCommitToWorkstream(sha, message string) error`
|
|
|
|
### Workstream Commands
|
|
|
|
30. **Implement onx new** (`internal/commands/new.go`)
|
|
```go
|
|
func New(repo *Repository, name string) error {
|
|
// 1. Fetch latest from origin/main
|
|
// 2. Create workstream entry
|
|
// 3. Set as current workstream
|
|
// 4. Update workspace to base commit
|
|
// 5. Log to oplog
|
|
}
|
|
```
|
|
|
|
31. **Implement onx list** (`internal/commands/list.go`)
|
|
- Read workstreams.json
|
|
- Format output with current indicator (*)
|
|
- Show commit count per workstream
|
|
- Color code output for better readability
|
|
|
|
32. **Implement onx switch** (`internal/commands/switch.go`)
|
|
```go
|
|
func Switch(repo *Repository, name string) error {
|
|
// 1. Save current ephemeral state
|
|
// 2. Load target workstream
|
|
// 3. Checkout latest commit in workstream
|
|
// 4. Update current_workstream
|
|
// 5. Restore workspace state
|
|
// 6. Log to oplog
|
|
}
|
|
```
|
|
|
|
33. **Add workstream validation**
|
|
- Validate workstream names (no special chars)
|
|
- Check for uncommitted changes before switch
|
|
- Prevent duplicate workstream names
|
|
|
|
## Milestone 4: Synchronization and Remote Interaction
|
|
|
|
### Rebase Engine
|
|
|
|
34. **Implement stacked rebase** (`internal/git/rebase.go`)
|
|
```go
|
|
func RebaseStack(repo *Repository, stack []string,
|
|
onto string) error {
|
|
// 1. Rebase first commit onto target
|
|
// 2. For each subsequent commit:
|
|
// - Rebase onto previous
|
|
// - Handle conflicts
|
|
// 3. Update all branch refs
|
|
}
|
|
```
|
|
|
|
35. **Integrate rerere** (`internal/git/rerere.go`)
|
|
- Configure rerere cache location (.onx/rerere_cache)
|
|
- Enable rerere for rebase operations
|
|
- Implement conflict detection
|
|
- Apply recorded resolutions automatically
|
|
|
|
36. **Create conflict resolution UI** (`internal/git/conflicts.go`)
|
|
- Detect merge conflicts
|
|
- Present clear conflict markers
|
|
- Guide user through resolution
|
|
- Record resolution for rerere
|
|
|
|
### Sync and Push Commands
|
|
|
|
37. **Implement onx sync** (`internal/commands/sync.go`)
|
|
```go
|
|
func Sync(repo *Repository) error {
|
|
// 1. Begin oplog transaction
|
|
// 2. Fetch from origin
|
|
// 3. Get workstream stack
|
|
// 4. Sequential rebase with rerere
|
|
// 5. Handle conflicts
|
|
// 6. Update workstreams.json
|
|
// 7. Finalize oplog transaction
|
|
}
|
|
```
|
|
|
|
38. **Implement onx push** (`internal/commands/push.go`)
|
|
- Get all branches in current workstream
|
|
- Push each branch to remote
|
|
- Handle authentication (SSH/HTTPS)
|
|
- Report progress for each branch
|
|
|
|
39. **Add remote configuration**
|
|
- Read git remote configuration
|
|
- Support multiple remotes
|
|
- Default to "origin"
|
|
- Validate remote existence
|
|
|
|
## Testing Infrastructure
|
|
|
|
40. **Create test utilities** (`internal/testutil/`)
|
|
- `CreateTestRepo() (*Repository, cleanup func())`
|
|
- `CreateTestCommit(repo, message string) string`
|
|
- `AssertFileContents(t, path, expected string)`
|
|
- Mock filesystem for daemon tests
|
|
|
|
41. **Write unit tests for each component**
|
|
- Core: repository_test.go, transaction_test.go
|
|
- Storage: oplog_test.go, workstreams_test.go
|
|
- Git: objects_test.go, rebase_test.go
|
|
- Commands: One test file per command
|
|
- Minimum 80% code coverage
|
|
|
|
42. **Create integration tests** (`test/integration/`)
|
|
- Full workflow test (init → new → save → sync → push)
|
|
- Conflict resolution scenarios
|
|
- Undo/redo sequences
|
|
- Daemon snapshot creation
|
|
- Workstream switching with changes
|
|
|
|
43. **Add benchmark tests** (`test/benchmarks/`)
|
|
- Oplog append performance
|
|
- Snapshot creation speed
|
|
- Large repository handling
|
|
- Rebase performance with many commits
|
|
|
|
## Error Handling & Logging
|
|
|
|
44. **Implement structured logging** (`internal/utils/logger.go`)
|
|
- Use structured logging library (zap or logrus)
|
|
- Log levels: Debug, Info, Warn, Error
|
|
- Log to .onx/logs/onx.log
|
|
- Rotate logs daily
|
|
|
|
45. **Create error types** (`internal/errors/errors.go`)
|
|
```go
|
|
type OnyxError struct {
|
|
Code string
|
|
Message string
|
|
Cause error
|
|
Hint string
|
|
}
|
|
```
|
|
|
|
46. **Add recovery mechanisms**
|
|
- Panic recovery in daemon
|
|
- Graceful degradation on partial failures
|
|
- Clear error messages with recovery hints
|
|
|
|
## Documentation
|
|
|
|
47. **Write user documentation** (`docs/user-guide.md`)
|
|
- Getting started guide
|
|
- Command reference with examples
|
|
- Workflow tutorials
|
|
- Migration guide from Git
|
|
|
|
48. **Create developer documentation** (`docs/developer-guide.md`)
|
|
- Architecture overview
|
|
- API documentation
|
|
- Contributing guidelines
|
|
- Testing procedures
|
|
|
|
49. **Add inline code documentation**
|
|
- Package-level documentation
|
|
- Public API documentation
|
|
- Complex algorithm explanations
|
|
- Generate with `godoc`
|
|
|
|
## Build & Deployment
|
|
|
|
50. **Create build scripts** (`scripts/build.sh`)
|
|
```bash
|
|
#!/bin/bash
|
|
# Build for multiple platforms
|
|
GOOS=darwin GOARCH=amd64 go build -o bin/onx-darwin-amd64
|
|
GOOS=linux GOARCH=amd64 go build -o bin/onx-linux-amd64
|
|
GOOS=windows GOARCH=amd64 go build -o bin/onx-windows-amd64.exe
|
|
```
|
|
|
|
51. **Set up CI/CD** (`.github/workflows/ci.yml`)
|
|
- Run tests on push
|
|
- Check code formatting
|
|
- Run linters
|
|
- Build binaries
|
|
- Upload artifacts
|
|
|
|
52. **Create installation scripts**
|
|
- Homebrew formula for macOS
|
|
- .deb package for Ubuntu/Debian
|
|
- .rpm package for Fedora/RHEL
|
|
- Windows installer (.msi)
|
|
|
|
53. **Implement version management**
|
|
- Embed version in binary
|
|
- `onx version` command
|
|
- Semantic versioning
|
|
- Git tag for releases
|
|
|
|
## Performance Optimization
|
|
|
|
54. **Profile critical paths**
|
|
- Use pprof for CPU profiling
|
|
- Identify bottlenecks in snapshot creation
|
|
- Optimize oplog serialization
|
|
- Cache frequently accessed data
|
|
|
|
55. **Implement caching layers**
|
|
- Cache Git objects in memory
|
|
- Cache workstream metadata
|
|
- Implement LRU eviction
|
|
- Monitor cache hit rates
|
|
|
|
## Final Integration & Polish
|
|
|
|
56. **Implement help system**
|
|
- Rich help text for all commands
|
|
- Examples for common workflows
|
|
- Interactive prompts for missing arguments
|
|
- Suggest next commands
|
|
|
|
57. **Add shell completions**
|
|
- Bash completion script
|
|
- Zsh completion script
|
|
- Fish completion script
|
|
- PowerShell completion
|
|
|
|
58. **Create demo repository**
|
|
- Sample project with history
|
|
- Multiple workstreams
|
|
- Demonstrate all features
|
|
- Include in documentation
|
|
|
|
59. **Perform security audit**
|
|
- Review file permissions
|
|
- Validate input sanitization
|
|
- Check for race conditions
|
|
- Audit dependency vulnerabilities
|
|
|
|
60. **Final testing and bug fixes**
|
|
- User acceptance testing
|
|
- Performance testing with large repos
|
|
- Cross-platform compatibility testing
|
|
- Fix all critical and high-priority bugs
|
|
|
|
## Deployment Checklist
|
|
|
|
✅ All unit tests passing
|
|
✅ Integration tests passing
|
|
✅ Documentation complete
|
|
✅ Binaries built for all platforms
|
|
✅ Installation scripts tested
|
|
✅ Demo repository prepared
|
|
✅ Security audit complete
|
|
✅ Performance benchmarks acceptable
|
|
✅ Version tagged in Git
|
|
✅ Release notes written
|
|
|
|
## Success Metrics
|
|
|
|
- **Functionality**: All Phase 1 commands working as specified
|
|
- **Performance**: Snapshot creation < 100ms for typical repos
|
|
- **Reliability**: Zero data loss, robust undo/redo
|
|
- **Compatibility**: Works with all Git 2.x clients
|
|
- **Quality**: >80% test coverage, <5 bugs per KLOC
|
|
|
|
This implementation plan provides a complete, unambiguous roadmap for building Onyx Phase 1. Each step builds upon the previous ones, ensuring a logical progression from foundation to finished product.
|