Add starter notes
This commit is contained in:
422
notes/future.md
Normal file
422
notes/future.md
Normal file
@ -0,0 +1,422 @@
|
||||
## 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.
|
||||
Reference in New Issue
Block a user