onyx-prebootstrap/notes/future.md

Milestone 3: Workstreams

Workstream Data Model

28. Implement workstream storage (internal/storage/workstreams.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)

    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)

    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)

    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)

    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)

    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)

    #!/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.