DWS/onyx-prebootstrap
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

temp for tree extraction

Browse Source
This commit is contained in:
Tanishq Dubey
2025-10-15 19:13:35 -04:00
commit 89fb7a30f7
50 changed files with 8769 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

358
notes/architecture.md Normal file
View File

@ -0,0 +1,358 @@
# **Onyx: An Architectural Blueprint and Phase 1 Implementation Plan**
## **Executive Summary**
This document provides a concrete, actionable engineering plan for building Onyx, a next-generation version control system (VCS). The core value proposition of Onyx is not to replace Git, but to provide a compatible, superior user experience layer designed to enhance developer velocity, safety, and ergonomics. It achieves this by directly addressing the fundamental flaws in Git's user-facing model, which is a significant and persistent source of developer frustration and cognitive overhead.1
The architecture is founded on a hybrid storage model, utilizing a standard .git directory for universal data compatibility and a parallel .onx directory for Onyx-specific metadata. This approach ensures seamless interoperability with the existing Git ecosystem while enabling a suite of advanced, user-centric features. The recommended technical stack is centered on the Go programming language and the go-git library for core Git interaction, chosen for their alignment with Onyx's principles of performance, simplicity, and robust concurrency.6
The implementation plan is phased, with Phase 1 focused on delivering the most critical 80% of developer workflows: initializing a repository, saving work, creating and switching between tasks, and synchronizing with remote repositories \[User Query\]. This blueprint translates the high-level concepts of Transparent Versioning, Workstreams, and the Action Log into a detailed technical specification, serving as the primary guiding document for the engineering team tasked with building Onyx.
## **Section 1: Foundational Architecture: A New Porcelain on Git's Plumbing**
This section establishes the non-negotiable architectural principles that govern Onyx's design. These principles are engineered to ensure that Onyx can deliver its innovative user experience without sacrificing compatibility with the vast and deeply entrenched Git ecosystem.
### **1.1. The Strategic Imperative: 100% Git Data Model Compatibility**
Any analysis of the version control market must begin with the acknowledgment of Git's hegemonic status, with a market share exceeding 90%.1 This dominance is not merely a function of its technical merits but is the result of a powerful, self-reinforcing network effect driven by the vast ecosystem of code hosting platforms (GitHub, GitLab), DevOps tooling, and developer mindshare built around it.2 The history of technically compelling or user-friendly alternative version control systems, such as Mercurial, Pijul, and Darcs, provides a crucial lesson: technical or user experience superiority alone is insufficient to overcome the immense inertia of this ecosystem.2 Attempting to replace Git's underlying data model is, therefore, a strategic dead end.
This market reality establishes the single most important architectural mandate for Onyx: it must be designed as a new "porcelain"—a layer of user-facing tools and workflows—that operates directly on Git's existing "plumbing," its foundational data model.1 This principle of unyielding compatibility dictates that all core repository data—blobs (file content), trees (directory structures), and commits (historical snapshots)—must be standard Git objects, addressable by their SHA-1 hashes and stored within a standard .git/objects directory.1 This ensures that any standard Git client can clone, inspect, build, and interact with an Onyx-managed repository without issue, even without Onyx installed.1
The implications of this decision are profound. It allows Onyx to be positioned not as a risky, all-or-nothing "Git replacement," but as a "power-up" or a progressive enhancement for professional developers.2 This strategy dramatically lowers the barrier to adoption for individuals and teams, as a single developer can adopt Onyx for its superior local workflow without disrupting the tooling or workflows of their collaborators who continue to use standard Git.
### **1.2. The Hybrid Storage Model: .git for Shared Truth, .onx for Local State**
To power its advanced features—such as the Action Log for universal undo, Workstreams for native stacked-diff management, and the Ephemeral Workspace for transparent versioning—Onyx requires its own persistent metadata store within the repository.1 The architecture for this storage is a co-located directory model, which creates a clear and deliberate separation of concerns.
A standard .git directory will serve as the immutable, shared source of truth. It contains the Git object database and the refs that are understood by the global Git ecosystem. In parallel, Onyx will create and maintain a .onx directory at the root of the repository. This directory will house all Onyx-specific metadata, effectively serving as the user's local, high-fidelity workspace and state machine.2
This hybrid model was chosen over an alternative approach of storing metadata within a dedicated Git namespace (e.g., refs/meta/onyx/).1 While using Git refs would make the metadata automatically portable via standard git fetch and git push operations, it is fundamentally unsuitable for the complex, high-frequency, and often private data Onyx will generate. The Action Log, for instance, is an append-only log of every user operation; representing this as a chain of thousands of Git refs would be highly inefficient, pollute the ref database, and could severely degrade the performance of standard Git operations like garbage collection.
The .onx directory model provides the necessary isolation and allows for the use of more efficient and appropriate data structures, such as a binary log file for the Action Log or a local SQLite database for indexing commit metadata. This design creates a deliberate "portability boundary" that reinforces Onyx's core conceptual model. The user query specifies the creation of the "iPhone of VCS," a system that abstracts away underlying complexity. By separating local state from shared state, Onyx presents the user with a simplified world of "Workstreams" and "Actions," not a confusing soup of underlying implementation details. The .git directory contains the shared, canonical history that all collaborators agree upon. The .onx directory contains the user's private, powerful "scratchpad"—their undo history, their fluid work-in-progress, and their local workflow configuration. This means that sharing an Onyx-enhanced workflow requires both users to have Onyx, which is a feature, not a limitation. It encourages adoption while ensuring the shared truth in .git remains clean and universally compatible. The act of executing onx review becomes the explicit, managed process of translating the rich local state from .onx into the simpler, shared state of standard Git branches and pull requests.
## **Section 2: Data Models and On-Disk Structures**
This section provides a detailed specification for the contents of the .onx directory and the in-memory data structures that represent Onyx's core concepts. This on-disk layout is the physical manifestation of the architectural principles established in the previous section.
### **2.1. The .onx Directory Layout**
An Onyx-managed repository will contain the following structure at its root, alongside the standard .git directory. This layout provides a clear, organized, and extensible foundation for Onyx's metadata.
* .onx/
* oplog: An append-only binary file containing the Action Log.
* workstreams.json: A human-readable file defining the logical Workstreams.
* workspace: A plain-text file acting as a pointer to the current ephemeral commit.
* rerere\_cache/: A directory to store Git's rerere data for automated conflict resolution.
* index.db: (Reserved for future use) A SQLite database for indexing commit metadata to power the Temporal Explorer.
### **2.2. The Action Log (oplog) Schema**
The Action Log is the cornerstone of Onyx's safety model, providing the data necessary for a true, universal undo/redo capability.1 To ensure performance and immutability, it will be implemented as an append-only binary log file. Each entry in the log represents a single, state-changing transaction.
The structure of each serialized transaction object within the oplog will be as follows:
* **id (u64):** A unique, monotonically increasing identifier for the operation.
* **parent\_id (u64):** The ID of the previous operation, forming a traversable chain for sequential undo/redo operations.
* **timestamp (u64):** A high-precision Unix timestamp (nanoseconds) marking the start of the operation.
* **command (String):** The user-facing command that triggered the action, including its arguments (e.g., onx sync, onx save \-m "Initial implementation").
* **state\_before (Map\<String, String\>):** A snapshot of all Onyx-managed Git refs *before* the operation was executed. The map keys are the full ref names (e.g., refs/heads/onyx/feature-auth/1), and the values are the corresponding Git commit SHA-1 hashes.
* **state\_after (Map\<String, String\>):** The corresponding snapshot of the same refs *after* the operation completed successfully.
This structure is the key to enabling the onx undo command. An undo operation is a simple, deterministic process: it reads the state\_before map from the latest log entry and programmatically force-updates all managed refs to match the stored SHA-1 hashes, effectively rolling back the repository's meta-state to the point just before the last command was run.1
### **2.3. Workstream Representation**
Onyx's Workstreams are a high-level abstraction designed to make the powerful but complex "stacked diffs" workflow simple and native.1 The on-disk representation explicitly decouples the user's logical concept of a "Workstream" from the underlying Git implementation, which consists of a chain of hidden branches. This state will be stored in .onx/workstreams.json.
A sample structure for this JSON file is:
JSON
{
"current\_workstream": "feature-auth",
"workstreams": {
"feature-auth": {
"base\_commit": "a1b2c3d4...",
"commits": \[
{
"sha": "f1e2d3c4...",
"branch\_ref": "refs/heads/onyx/feature-auth/1",
"description": "Add database schema for users"
},
{
"sha": "b4c3d2e1...",
"branch\_ref": "refs/heads/onyx/feature-auth/2",
"description": "Implement backend authentication API"
}
\]
},
"bugfix/login-flow": {
"base\_commit": "e5f6a7b8...",
"commits": \[
{
"sha": "c9d8e7f6...",
"branch\_ref": "refs/heads/onyx/bugfix/login-flow/1",
"description": "Fix incorrect password validation"
}
\]
}
}
}
The onx CLI will read and write to this file to manage the state of Workstreams, while the backend logic will perform the more complex task of creating, rebasing, and pushing the underlying Git branches specified in the branch\_ref fields.
### **2.4. Ephemeral Workspace State (workspace file)**
The Ephemeral Workspace is the core of the Transparent Versioning system, replacing Git's confusing staging area with a model where the working directory is always represented as a commit.1 The state of this system is managed by a single pointer stored in the .onx/workspace file.
This file will contain a single line, following the format of Git's own symbolic-ref files:
ref: refs/onyx/workspaces/current
A background daemon will be responsible for continuously creating new, "ephemeral" Git commits that reflect the state of the user's files and updating the refs/onyx/workspaces/current ref to point to the latest one. User-facing commands like onx save will then "pin" this ephemeral commit by giving it a permanent branch and adding it to a Workstream. This mechanism provides the safety of continuous backup while keeping the user's primary workflow focused on creating meaningful, durable checkpoints.
### **2.5. Table 2.1: Onyx Metadata Schema**
The following table provides a consolidated overview of the on-disk structures within the .onx directory, serving as a definitive schema for the implementation. The presence of a dedicated rerere\_cache directory, for example, signals that automated conflict resolution is a core, designed-in feature of the architecture, not an afterthought.1
| Path | Format | Purpose |
| :---- | :---- | :---- |
| oplog | Append-only Binary Log | Stores the transaction history of all state-changing operations, enabling the onx undo/redo functionality. |
| workstreams.json | JSON | Defines the logical Workstreams, their constituent commits, and their mapping to the underlying hidden Git branches. |
| workspace | Plain Text (Symbolic Ref) | Stores the ref pointer to the current ephemeral commit, which represents the live state of the user's working directory. |
| rerere\_cache/ | Git rerere format | Stores recorded conflict resolutions, allowing onx sync to automatically resolve previously seen merge conflicts. |
| index.db | SQLite | (Future Direction) An index of commit metadata (author, date, file paths) to enable fast, complex queries for the Temporal Explorer. |
## **Section 3: Core Component Implementation: The Four Pillars**
This section details the engineering approach for each of Onyx's foundational features, translating the architectural concepts and data models into concrete algorithms and implementation strategies.
### **3.1. Transparent Versioning and the Ephemeral Workspace**
The elimination of the manual git add/git commit cycle for routine work is a primary goal of Onyx.1 This is achieved through a long-running, lightweight background daemon (onxd) that automates the creation of "ephemeral" snapshots.
The daemon will leverage platform-native filesystem notification APIs to ensure maximum efficiency and minimal resource consumption. The Go ecosystem provides a mature library, fsnotify, that offers a unified, cross-platform abstraction over these APIs (inotify on Linux, kqueue on BSD/macOS, and ReadDirectoryChangesW on Windows).7
The snapshotting algorithm executed by the daemon will be as follows:
1. **Trigger:** Upon receiving a file change notification from the OS, the daemon will start a short debounce timer (e.g., 500ms) to batch subsequent rapid changes, such as those occurring during a file save operation.
2. **Tree Creation:** Once the timer expires, the daemon will programmatically create a new Git tree object. This is not a diff; it is a full snapshot of the *entire* current state of the working directory, which is consistent with Git's core "snapshot, not differences" philosophy.5 This involves iterating through the directory, creating blob objects for each file's content, and recursively building tree objects for each subdirectory.
3. **Commit Creation:** The daemon will then create a new Git commit object. This commit will point to the newly created root tree object. The parent of this new commit will be the SHA-1 hash of the previous ephemeral commit, which is read from the ref pointed to by .onx/workspace. The commit message will be a simple, machine-readable placeholder (e.g., "ephemeral snapshot @ timestamp").
4. **Ref Update:** Finally, the daemon will atomically update the Git ref refs/onyx/workspaces/current to point to the SHA-1 hash of the new ephemeral commit.
This automated process completely removes the cognitive burden of the staging area, a primary source of user friction with Git.1 The user's work is continuously and safely versioned in the background, allowing them to focus on their creative tasks.
### **3.2. Workstreams: The Stack-Native Workflow Engine**
Workstreams are the core component for managing development tasks and enabling high-velocity, stacked-diff workflows. The implementation of the onx save and onx sync commands is critical to this engine.
The algorithm for onx save \-m "\<message\>" will be:
1. **Identify Source:** Read the current ephemeral commit SHA from the ref pointed to by .onx/workspace.
2. **Create Pinned Commit:** Create a new, durable Git commit object. This is effectively an amendment of the ephemeral commit: it points to the same tree object but replaces the placeholder message with the user-provided message and sets the correct author and committer metadata.
3. **Allocate Branch:** Determine the next available branch name in the current Workstream's sequence based on the data in .onx/workstreams.json (e.g., if the last branch was .../3, the new one is .../4).
4. **Create Branch:** Create this new Git branch and point it to the SHA of the new durable commit.
5. **Update Metadata:** Update the .onx/workstreams.json file to add this new commit (its SHA, branch ref, and description) to the current Workstream's ordered list of commits.
The algorithm for onx sync, the powerhouse of the Workstream model, will be:
1. **Fetch Updates:** Perform a git fetch on the configured remote to get the latest changes for the base branch (e.g., origin/main).
2. **Identify Stack:** Read the ordered list of branches for the current Workstream from .onx/workstreams.json.
3. **Rebase Head:** Programmatically perform a git rebase of the first branch in the stack (e.g., .../1) onto the new tip of origin/main.
4. **Sequential Rebase:** For each subsequent branch in the stack (.../2, .../3, etc.), programmatically rebase it onto the *newly rebased* tip of the preceding branch. This automated, sequential process is equivalent to the manual and error-prone series of interactive rebases required in standard Git, or a more modern git rebase \--update-refs operation.1
5. **Automated Conflict Resolution:** Throughout this process, Git's rerere (reuse recorded resolution) feature will be enabled. The .onx/rerere\_cache directory will be configured as the storage location. This allows Onyx to learn how a user resolves a specific conflict once and then apply that same resolution automatically in all future onx sync operations where the same conflict arises.1
A standard git rebase is not an atomic operation; it can fail midway, leaving the repository in a confusing, partially-rebased state that requires manual intervention (--continue or \--abort). The onx sync command, however, is presented to the user as a single, atomic operation. This is made possible by the Action Log. The onx sync command must begin by writing a "BEGIN\_SYNC" entry to the oplog. If the entire sequential rebase completes successfully, it writes a corresponding "END\_SYNC" entry. If any step fails due to an unresolvable conflict, the entire operation can be instantly and safely rolled back by invoking onx undo, which will use the state\_before from the "BEGIN\_SYNC" entry to restore all branch pointers to their pre-sync state. In this way, Onyx adds a transactional layer on top of Git's primitive operations, providing a fundamental enhancement to safety and usability.
### **3.3. The Temporal Explorer (Phase 1 Stub)**
While the full interactive, terminal-based visualizer described in the RFCs is a post-Phase 1 feature, the foundation can be laid with a powerful onx log command.1 The Phase 1 implementation will focus on a command-line query engine based on the revset language pioneered by Mercurial and Jujutsu.1
The implementation will consist of two main parts:
* **Revset Parser:** A parser for a subset of the revset grammar. The initial scope for Phase 1 will include essential filters and operators:
* **Filters:** author(regex), file(glob), description(regex)
* **Set Operators:** x | y (union), x & y (intersection), \~x (negation)
* **Ancestry Operators:** x..y (commits reachable from y but not x), ::x (ancestors of x)
* **Query Engine:** This engine will take the parsed query and execute it against the Git commit graph. It will leverage the commit iteration capabilities provided by the chosen Git library (go-git) to efficiently traverse the DAG.6 The engine will apply the filters at each node to build the final set of matching commits.
This component provides a significantly more intuitive and powerful way for developers to navigate and understand project history compared to the complex and often-forgotten flag combinations of the standard git log command.1
### **3.4. The Action Log: A Transactional Safety Net**
The Action Log is the most critical safety feature in Onyx, transforming the user experience from one of caution to one of fearless experimentation.1 Its implementation requires that every state-changing onx command be wrapped in a transactional function.
The logic for this transactional wrapper will be:
1. **Capture Pre-State:** Before executing any logic, capture the current state of all Onyx-managed refs (Workstream branch tips, the workspace pointer, etc.) by reading their current SHA-1 hashes.
2. **Begin Transaction:** Write a new entry to the .onx/oplog. This entry will contain a new unique ID, the ID of the parent operation, the command being executed, and the captured state\_before.
3. **Execute Command Logic:** Run the core implementation of the command (e.g., the onx sync sequential rebase algorithm).
4. **Finalize Transaction (on Success):** If the command logic completes successfully, capture the new state of all managed refs (state\_after) and update the oplog entry to include this information.
5. **Handle Failure:** If the command logic fails, log the failure and provide a clear, actionable error message to the user, guiding them to run onx undo to revert to a clean state.
The algorithm for the onx undo command itself will be:
1. **Read Log:** Read the most recent, un-undone entry from the oplog.
2. **Restore Refs:** For each key-value pair in the entry's state\_before map, perform a direct, forceful update of the Git ref (the key) to point to the stored SHA-1 hash (the value).
3. **Update Workspace:** Perform a git checkout of the appropriate commit to restore the working directory to its previous state.
4. **Update Log Pointer:** Move the oplog's internal "HEAD" pointer to the parent operation. This stack-based model enables sequential undo calls to step further back in the operation history, a crucial usability improvement over the sometimes confusing behavior of jj undo.1
## **Section 4: The onx Command-Line Interface: Phase 1 Specification**
The onx command-line interface is the primary surface through which developers will experience Onyx. Its design is paramount to fulfilling the "iPhone of VCS" vision. It will be a thoughtfully designed, user-centric interface that embodies the principles of velocity, simplicity, and safety, drawing inspiration from the consistency and user-focus of Mercurial's CLI.2
### **4.1. Design Philosophy**
The development of the onx CLI will be guided by a set of core design principles:
* **Orthogonality:** Each command will have a single, well-defined purpose. This principle explicitly avoids the pitfalls of overloaded and confusing commands like git checkout, which handles branch switching, file restoration, and historical checkouts.1
* **Intention-Based Naming:** Commands will be named for the user's goal (e.g., onx new, onx save, onx review), not the underlying mechanical operation (git checkout \-b, git commit, git push).2 This makes the interface more intuitive and easier to learn.
* **Guidance and Discoverability:** The CLI will be self-documenting. Every command will feature rich \--help text with practical examples. Furthermore, the CLI will be an active guide: error messages will be human-readable, explain the problem, and suggest the exact command to fix it. Successful operations will provide clear confirmation and suggest the next logical step in a common workflow.2
### **4.2. Table 4.1: onx CLI Command Specification (Phase 1\)**
The following table provides a comprehensive reference for the commands required to fulfill the scope of Phase 1\. It serves as the primary specification for the CLI development team and provides stakeholders with a clear summary of the product's initial functionality.
| Command | Arguments/Options | Git Equivalent (Conceptual) | Description |
| :---- | :---- | :---- | :---- |
| onx init | \[directory\] | git init | Initializes a new Onyx-managed repository, creating both a standard .git directory and the .onx metadata directory. |
| onx new | \<name\> | git checkout \-b \<name\> | Creates a new Workstream for a feature or task, automatically branching from the configured mainline. |
| onx save | \-m, \--message "message" | git add. && git commit | Creates a durable, named snapshot (a "pinned" commit) of the current work within a Workstream. |
| onx list | | git branch | Lists all available Workstreams and indicates the currently active one. |
| onx switch | \<name\> | git checkout \<name\> | Switches the current context to a different Workstream, restoring its files and history. |
| onx push | \[remote\] | git push | Pushes the current Workstream's underlying branches to a remote repository. (A simplified precursor to onx review). |
| onx sync | | git pull \--rebase origin main | Updates the current Workstream by fetching the latest changes from its base branch and automatically rebasing the entire stack. |
| onx undo | | git reflog && git reset \--hard \<ref\> | Reverses the last state-changing operation recorded in the Action Log, providing a universal safety net. |
### **4.3. Table 4.2: Git vs. Onyx Workflow Mapping**
A critical tool for driving adoption will be helping experienced Git users map their existing, often painful, workflows to the simpler, more powerful Onyx paradigm. The "unlearning curve" for Git veterans is a significant adoption barrier.2 This "Rosetta Stone" table directly addresses that friction by demonstrating Onyx's value proposition in a single, easily digestible format.
| Goal / Workflow | Git Commands | Onyx Commands | Analysis of Benefit |
| :---- | :---- | :---- | :---- |
| Start a new feature | git checkout main git pull git checkout \-b feature/auth | onx new feature/auth | A single, intention-based command replaces three mechanical steps. Onyx handles synchronization automatically. |
| Save work to switch tasks | git add. git stash git checkout hotfix/bug | onx switch hotfix/bug | The entire concept of stashing is eliminated. Transparent Versioning means work is always saved; switching is frictionless. |
| Update feature with main | git pull \--rebase origin main | onx sync | Onyx's sync automates the rebase for the entire stack of commits in a Workstream, not just a single branch. |
| Amend an older commit | git rebase \-i \<base\> (mark commit with edit) ...make changes... git commit \--amend git rebase \--continue | onx down 2 ...make changes... onx save \--amend | Onyx allows direct editing of historical commits. The tool automatically handles the rebase of all dependent commits in the stack. |
| Undo a botched rebase | git reflog (find correct ref) git reset \--hard HEAD@{n} | onx undo | A single, memorable, and safe command replaces the arcane and dangerous reflog/reset dance. |
## **Section 5: Phase 1 Implementation Roadmap**
This section provides a practical, milestone-based plan for building and delivering Phase 1 of Onyx. It transforms the architectural proposal into an actionable project plan, allowing for accurate resource planning and progress tracking. The dependencies between milestones are explicit, ensuring a logical and efficient development sequence.
### **Milestone 0: Foundation and Core Abstractions**
* **Tasks:**
1. Initialize the Go module structure, including workspace setup, CI/CD pipelines, and dependency management.
2. Select and integrate go-git as the core Git interaction library.6
3. Implement the core Repository struct, which will serve as the central object, encapsulating access to both the underlying Git repository (via go-git) and the Onyx metadata within the .onx directory.
4. Implement low-level, internal functions for programmatically reading and writing the four fundamental Git object types: blobs, trees, commits, and tags, using the go-git API.9
* **Goal:** A foundational library that can programmatically create a valid Git commit from a directory snapshot, forming the bedrock for all higher-level Onyx features.
### **Milestone 1: The Action Log and onx init**
* **Tasks:**
1. Implement the on-disk data structure for the oplog as a robust, append-only binary file.
2. Develop the transactional wrapper function that all state-changing commands will use. This function will handle capturing state\_before, writing to the oplog, and finalizing the entry with state\_after.
3. Implement the onx init command. This will be the first user-facing command and will use the transactional wrapper to log its own creation of the .onx directory and its initial files.
4. Implement the onx undo command to read the oplog and revert the init operation.
* **Goal:** A working onx init command and a fully testable, robust undo/redo foundation. This milestone proves the core safety mechanism of the entire system.
### **Milestone 2: Transparent Versioning and onx save**
* **Tasks:**
1. Build the cross-platform onxd filesystem monitoring daemon using a library like fsnotify.7
2. Implement the snapshotting algorithm within the daemon to automatically create ephemeral commits and update the workspace pointer.
3. Implement the onx save command, which "pins" the current ephemeral commit by giving it a user-provided message and associating it with a Workstream.
* **Goal:** The core "save work" loop is fully functional. The Git staging area is now officially obsolete within the Onyx workflow.
### **Milestone 3: Workstreams (onx new, onx list, onx switch)**
* **Tasks:**
1. Implement the on-disk data model for Workstreams in .onx/workstreams.json, including functions for reading, writing, and modifying this state.
2. Implement the onx new command to create a new Workstream.
3. Implement the onx list command to display available Workstreams.
4. Implement the onx switch command to change the active Workstream, which involves updating the working directory and the internal workspace pointer.
* **Goal:** The core branching and context-switching workflow is complete, providing a fluid and frictionless way for developers to manage multiple tasks.
### **Milestone 4: Synchronization and Remote Interaction (onx sync, onx push)**
* **Tasks:**
1. Implement the automated stacked rebase logic for the onx sync command, ensuring it correctly handles the sequential rebasing of the entire commit stack.
2. Integrate Git's rerere functionality to enable automated conflict resolution.
3. Implement the onx push command to push all the underlying hidden branches of a single Workstream to a remote repository.
* **Goal:** Users can now collaborate with others and keep their local work up-to-date with a shared mainline branch, completing the core 80% of common developer workflows.
### **5.5. Table 5.1: Phase 1 Milestone Breakdown**
| Milestone | Key Tasks | Dependencies | Complexity (Points) |
| :---- | :---- | :---- | :---- |
| **M0: Foundation** | Project Setup, go-git Integration, Core Git Object I/O | \- | 8 |
| **M1: Action Log** | oplog Implementation, Transactional Wrapper, onx init, onx undo | M0 | 13 |
| **M2: Versioning** | onxd Daemon, Filesystem Monitoring, Snapshot Algorithm, onx save | M1 | 21 |
| **M3: Workstreams** | Workstream Data Model, onx new, onx list, onx switch | M2 | 13 |
| **M4: Sync & Push** | Stacked Rebase Logic, rerere Integration, onx sync, onx push | M3 | 21 |
## **Section 6: Recommended Technical Stack and Dependencies**
This section provides and justifies the selection of the core technologies for building Onyx, ensuring the project is built on a modern, performant, and reliable foundation.
### **6.1. Implementation Language: Go**
Go is the recommended language for implementing Onyx. Its key features—simplicity, strong performance, and a powerful first-class concurrency model—are critical for building a systems-level tool like a version control system. Go compiles to a single, statically-linked binary, making distribution and deployment trivial across all major platforms. Its garbage collector simplifies memory management, while its robust standard library and pragmatic design accelerate development. The language's built-in support for goroutines and channels is ideal for building the concurrent components of Onyx, such as the background filesystem daemon (onxd), without the complexity of external runtimes.
### **6.2. Core Git Interaction Library: go-git**
The Go ecosystem offers two primary libraries for low-level Git interaction: git2go, which provides Go bindings to the mature C library libgit2 10, and go-git, a pure-Go, from-scratch implementation of Git.6 While libgit2 is highly feature-complete, using it via git2go introduces CGo, which can add significant complexity to the build process, cross-compilation, and memory management, and creates a dependency on a C toolchain.11
For Onyx, the recommended library is go-git. This choice represents a strategic alignment with Onyx's core philosophy of building a modern, simple, and self-contained tool. As a pure Go implementation, go-git avoids the overhead and complexity of CGo, simplifying the build and deployment process and ensuring the entire stack benefits from Go's memory safety and tooling.12 go-git is actively developed and used in major projects like Gitea and Pulumi, and it provides idiomatic Go APIs for both low-level (plumbing) and high-level (porcelain) operations, making it a more strategic and future-proof choice for a Go-native project.6
### **6.3. Key Dependencies**
* **CLI Framework:** cobra is the de facto standard for building feature-rich command-line applications in Go. It is used by major projects like Kubernetes and Docker and provides excellent support for nested commands, argument parsing, and automatic help generation.13
* **Filesystem Monitoring:** The fsnotify package will be used to provide a cross-platform abstraction over native filesystem event APIs, forming the core of the onxd daemon.7
* **Serialization:** Go's standard library encoding/json package is the canonical choice for handling the on-disk JSON format of the workstreams.json file. It is robust, performant, and requires no external dependencies.15
* **Concurrency:** Go's built-in **goroutines and channels** will be used as the asynchronous runtime for managing the background daemon, handling concurrent filesystem events, and executing any other long-running or I/O-bound tasks efficiently.
## **Section 7: Future Directions: Beyond Phase 1**
While the Phase 1 implementation plan focuses on delivering a robust and complete core workflow, the architecture is designed to be extensible. This concluding section outlines the logical next steps for Onyx's evolution, ensuring that the initial engineering effort provides a solid foundation for future growth.
### **7.1. The Full Temporal Explorer**
Beyond the command-line query engine of Phase 1, the next major feature will be the implementation of the full Temporal Explorer. This includes an interactive, terminal-based GUI visualizer for the commit graph, as envisioned in the original proposal.1 This tool will provide a clean, comprehensible rendering of the repository's Directed Acyclic Graph, allowing for interactive exploration, zooming, and direct manipulation of commits, addressing a long-standing need within the developer community for better native history visualization tools.1
### **7.2. Advanced Review Workflows**
The Phase 1 onx push command is a stepping stone to the more powerful onx review command. This future implementation will integrate directly with the APIs of major code hosting providers like GitHub and GitLab. onx review will automate the entire process of submitting a Workstream for code review, including pushing all underlying branches and creating a series of linked, dependent pull requests, thus fully realizing the velocity benefits of the stacked diffs workflow.1
### **7.3. AI-Powered Assistance**
The structured nature of Onyx's metadata, particularly the high-level developer intent captured in the Action Log and the semantic grouping of commits within Workstreams, provides a rich substrate for AI integration. Future versions of Onyx could leverage this data to provide:
* **AI-Generated Commit Messages:** Analyzing the diff of a work-in-progress, an AI model could propose a structured, conventional commit message for the onx save command.1
* **Automated Conflict Resolution:** Building upon the rerere concept, an AI could learn from how developers resolve complex conflicts during onx sync and begin to suggest or even automatically apply resolutions for common conflict patterns.1
### **7.4. Ecosystem Integration**
Long-term success depends on deep integration with the broader developer toolkit. A key future direction is the development of dedicated plugins for major IDEs, such as Visual Studio Code and the JetBrains suite. These plugins would provide a first-class graphical user experience that natively understands and visualizes Onyx's high-level abstractions like Workstreams and the Action Log, moving beyond the limitations of existing Git integrations that would only see the underlying hidden branches.2 This will make Onyx's power accessible to a much wider audience and solidify its position as an indispensable tool for high-velocity engineering teams.
#### **Works cited**
1. Designing Onyx: A New VCS
2. Designing Onyx: The Next VCS
3. Git Book \- The Git Object Model, accessed October 8, 2025, [https://shafiul.github.io/gitbook/1\_the\_git\_object\_model.html](https://shafiul.github.io/gitbook/1_the_git_object_model.html)
4. Git Object Model | Online Video Tutorial by thoughtbot, accessed October 8, 2025, [https://thoughtbot.com/upcase/videos/git-object-model](https://thoughtbot.com/upcase/videos/git-object-model)
5. 1.3 Getting Started \- What is Git?, accessed October 8, 2025, [https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F)
6. A highly extensible Git implementation in pure Go. \- GitHub, accessed October 8, 2025, [https://github.com/go-git/go-git](https://github.com/go-git/go-git)
7. fsnotify/fsnotify: Cross-platform filesystem notifications for Go. \- GitHub, accessed October 8, 2025, [https://github.com/fsnotify/fsnotify](https://github.com/fsnotify/fsnotify)
8. fsnotify package \- github.com/fsnotify/fsnotify \- Go Packages, accessed October 8, 2025, [https://pkg.go.dev/github.com/fsnotify/fsnotify](https://pkg.go.dev/github.com/fsnotify/fsnotify)
9. object package \- github.com/go-git/go-git/v5/plumbing/object \- Go Packages, accessed October 8, 2025, [https://pkg.go.dev/github.com/go-git/go-git/v5/plumbing/object](https://pkg.go.dev/github.com/go-git/go-git/v5/plumbing/object)
10. libgit2, accessed October 8, 2025, [https://libgit2.org/](https://libgit2.org/)
11. Extending GObjects From Go and Making Them Available to C | tinyzimmer's blog, accessed October 8, 2025, [https://tinyzimmer.github.io/posts/exporting-gobject-from-go/](https://tinyzimmer.github.io/posts/exporting-gobject-from-go/)
12. Consider migrating to libgit2/git2go · fluxcd flux2 · Discussion \#426 \- GitHub, accessed October 8, 2025, [https://github.com/fluxcd/flux2/discussions/426](https://github.com/fluxcd/flux2/discussions/426)
13. What is the essential difference between urfave/cli и spf13/cobra? : r/golang \- Reddit, accessed October 8, 2025, [https://www.reddit.com/r/golang/comments/5sdvoh/what\_is\_the\_essential\_difference\_between/](https://www.reddit.com/r/golang/comments/5sdvoh/what_is_the_essential_difference_between/)
14. Things I can't live without in a new Go project in no particular order: \- https:... | Hacker News, accessed October 8, 2025, [https://news.ycombinator.com/item?id=36047892](https://news.ycombinator.com/item?id=36047892)
15. encoding/json \- Go Packages, accessed October 8, 2025, [https://pkg.go.dev/encoding/json](https://pkg.go.dev/encoding/json)