onyx-prebootstrap/notes/future.md

Milestone 1: Action Log and onx init

Action Log Implementation

13. Create oplog binary format (internal/storage/oplog.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)

    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)

    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)

    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)

    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)

    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)

    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.