# 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
```

## 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