onyx-prebootstrap/README.md

# Onyx

A next-generation version control system designed as a superior user experience layer on top of Git.

## Overview

Onyx provides transparent versioning, workstreams for stacked-diff management, and an action log for universal undo functionality. The project is written in Go and uses the go-git library for Git interaction.

## Features

- **100% Git Data Model Compatibility**: Uses standard .git directory for shared truth
- **Transparent Versioning**: Background daemon creates continuous snapshots
- **Workstreams**: Stacked-diff workflow management
- **Action Log**: Transactional undo/redo capability
- **Hybrid Storage**: .git for Git objects, .onx for Onyx-specific metadata

## Quick Start

### Prerequisites

- Go 1.24.2 or later
- Git 2.30.0 or later

### Installation

```bash
# Clone the repository
git clone https://git.dws.rip/DWS/onyx.git
cd onyx

# Install dependencies
go mod tidy

# Build the CLI and daemon
make build

# Install to PATH
make install
```

### Usage

```bash
# Initialize repository
onx init

# Create workstream
onx new feature-branch

# Save work
onx save -m "Add new feature"

# List workstreams
onx list

# Switch workstreams
onx switch main

# Sync with remote
onx sync

# Push workstream
onx push

# Undo last operation
onx undo
```

## Push Workflows: Single-Branch vs Stacked Diffs

Onyx supports two push workflows to match your team's needs:

### Single-Branch Mode (Default) - Recommended

**Perfect for:** Traditional teams, simple features, clean remote UI

```bash
onx new add-login --base main
onx save -m "Add login form"
onx save -m "Add validation"
onx save -m "Add tests"

# Push creates ONE branch with all commits
onx push

# Result on remote:
# - Branch: add-login (contains all 3 commits)
# - Clean UI, easy PR workflow
```

**What you get:**
- ✅ One clean branch per workstream
- ✅ Perfect for traditional PR workflows
- ✅ All commits preserved locally for undo
- ✅ Clean remote repository UI

### Stacked Diffs Mode - Advanced

**Perfect for:** Complex features, incremental review, Meta/Google-style workflows

```bash
onx new big-refactor --base main
onx save -m "Step 1: Database schema"
onx save -m "Step 2: API endpoints"
onx save -m "Step 3: Frontend UI"

# Push creates MULTIPLE branches (one per commit)
onx push --stacked

# Result on remote:
# - Branch: onyx/workstreams/big-refactor/commit-1
# - Branch: onyx/workstreams/big-refactor/commit-2
# - Branch: onyx/workstreams/big-refactor/commit-3
# - Each can have its own PR for focused review
```

**What you get:**
- ✅ One branch per commit for incremental review
- ✅ PRs can be merged independently
- ✅ Better for large, complex changes
- ⚠️  More branches in remote UI

### Choosing Your Workflow

| Criterion | Single-Branch (`onx push`) | Stacked Diffs (`onx push --stacked`) |
|-----------|---------------------------|-------------------------------------|
| **Team Style** | Traditional Git workflow | Meta/Google stacked review |
| **Feature Size** | Any size | Large, complex features |
| **Review Style** | One big PR | Multiple small PRs |
| **Remote UI** | Clean (1 branch) | More branches (N commits) |
| **PR Creation** | `gh pr create --head feature` | Multiple PRs, stacked dependencies |

**Recommendation:** Start with default `onx push` (single-branch). Use `--stacked` only when you need incremental review of complex changes.

## Development

### Building

```bash
# Build the CLI and daemon
go build -o bin/onx ./cmd/onx
go build -o bin/onxd ./cmd/onxd

# Install to PATH
go install ./cmd/onx
go install ./cmd/onxd
```

### Testing

```bash
# Run all tests
go test -v ./...

# Run tests with coverage
go test -cover ./...

# Run specific test package
go test -v ./internal/core
```

### Linting and Code Quality

The project uses several tools to maintain code quality:

```bash
# Run linter
golangci-lint run

# Run security scanner
gosec ./...

# Run tests with race detection
go test -race ./...
```

## CI/CD

This project uses Gitea Actions for continuous integration and deployment. The workflow includes:

### CI Pipeline

- **Test**: Runs unit tests with race detection and coverage reporting
- **Build**: Cross-compiles binaries for multiple platforms (Linux, Windows, macOS)
- **Security**: Runs security scans using Gosec
- **Lint**: Performs comprehensive code linting with golangci-lint
- **Release**: Creates releases and uploads artifacts for main branch builds

### Supported Platforms

- Linux (amd64, arm64)
- Windows (amd64)
- macOS (amd64, arm64)

### Workflow Triggers

- Push to `main` or `develop` branches
- Pull requests to `main` branch

## Architecture

### Project Structure

```
onyx/
├── cmd/
│   ├── onx/           # CLI entry point
│   └── onxd/          # Daemon entry point
├── internal/
│   ├── core/          # Core abstractions
│   ├── git/           # Git interaction layer
│   ├── models/        # Data models
│   ├── storage/       # .onx directory management
│   ├── commands/      # CLI command implementations
│   ├── daemon/        # Daemon implementation
│   └── utils/         # Utilities
├── pkg/               # Public APIs
├── test/              # Integration tests
└── docs/              # Documentation
```

### Core Components

- **Repository**: Central object encapsulating access to both Git repository and Onyx metadata
- **Action Log**: Append-only binary log storing state before/after each operation
- **Workstreams**: Manages stacked-diff workflows through .onx/workstreams.json
- **Daemon**: Background process for continuous snapshot creation

## Contributing

1. Fork the repository
2. Create a feature branch (`onx new feature-name`)
3. Make your changes
4. Run tests and linting (`make test lint`)
5. Commit your changes (`onx save -m "Add feature"`)
6. Push to your fork (`onx push`)
7. Create a pull request

## License

[License information to be added]

## Acknowledgments

- [go-git](https://github.com/go-git/go-git) - Git implementation in pure Go
- [cobra](https://github.com/spf13/cobra) - CLI framework
- [fsnotify](https://github.com/fsnotify/fsnotify) - Filesystem monitoring