155 lines
5.0 KiB
Markdown
155 lines
5.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Onyx is a next-generation version control system designed as a superior user experience layer on top of Git. It 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.
|
|
|
|
## Development Commands
|
|
|
|
### 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
|
|
```
|
|
|
|
### Development Setup
|
|
This is a Go 1.24.2 project. Initialize dependencies with:
|
|
```bash
|
|
go mod tidy
|
|
```
|
|
|
|
Key dependencies:
|
|
- `github.com/go-git/go-git/v5` - Git interaction
|
|
- `github.com/spf13/cobra` - CLI framework (planned)
|
|
- `github.com/fsnotify/fsnotify` - Filesystem monitoring (planned)
|
|
|
|
## Architecture
|
|
|
|
### Core Design Principles
|
|
- **100% Git Data Model Compatibility**: Uses standard .git directory for shared truth
|
|
- **Hybrid Storage**: .git for Git objects, .onx for Onyx-specific metadata
|
|
- **Transparent Versioning**: Background daemon creates continuous snapshots
|
|
- **Workstreams**: Stacked-diff workflow management
|
|
- **Action Log**: Transactional undo/redo capability
|
|
|
|
### Project Structure (Planned)
|
|
```
|
|
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
|
|
```
|
|
|
|
### Key Components
|
|
|
|
#### 1. Repository (`internal/core/repository.go`)
|
|
Central object encapsulating access to both Git repository (via go-git) and Onyx metadata.
|
|
|
|
#### 2. Action Log (`internal/storage/oplog.go`)
|
|
Append-only binary log storing state before/after each operation for undo functionality.
|
|
|
|
#### 3. Workstreams (`internal/storage/workstreams.go`)
|
|
Manages stacked-diff workflows through .onx/workstreams.json.
|
|
|
|
#### 4. Daemon (`internal/daemon/`)
|
|
Background process using fsnotify for continuous snapshot creation.
|
|
|
|
## .onx Directory Structure
|
|
```
|
|
.onx/
|
|
├── oplog # Append-only binary action log
|
|
├── workstreams.json # Workstream definitions
|
|
├── workspace # Pointer to current ephemeral commit
|
|
├── rerere_cache/ # Git rerere conflict resolution cache
|
|
└── index.db # SQLite index (future feature)
|
|
```
|
|
|
|
## Core Commands (Phase 1)
|
|
|
|
| Command | Purpose | Git Equivalent |
|
|
|---------|---------|----------------|
|
|
| `onx init` | Initialize repository | `git init` |
|
|
| `onx new <name>` | Create workstream | `git checkout -b` |
|
|
| `onx save -m "msg"` | Save work | `git add && git commit` |
|
|
| `onx list` | List workstreams | `git branch` |
|
|
| `onx switch <name>` | Switch workstreams | `git checkout` |
|
|
| `onx sync` | Update with remote | `git pull --rebase` |
|
|
| `onx push` | Push workstream | `git push` |
|
|
| `onx undo` | Undo last operation | `git reflog && reset` |
|
|
|
|
## Implementation Status
|
|
|
|
This is currently a planning/prototype phase. The codebase contains:
|
|
- Go module setup
|
|
- Comprehensive architectural documentation in `notes/`
|
|
- Detailed implementation roadmap
|
|
- Technical specifications for core components
|
|
|
|
## Development Guidelines
|
|
|
|
### Code Style
|
|
- Follow Go conventions and idioms
|
|
- Use structured logging (planned: zap or logrus)
|
|
- Implement proper error handling with custom error types
|
|
|
|
### Testing Strategy
|
|
- Unit tests for each component (target: 80% coverage)
|
|
- Integration tests for full workflows
|
|
- Benchmark tests for performance-critical paths
|
|
|
|
### Git Integration
|
|
- All repository data must remain compatible with standard Git clients
|
|
- Onyx operations should be reversible via standard Git commands
|
|
- Never break the underlying Git object model
|
|
|
|
## Key Algorithms
|
|
|
|
### Transparent Versioning
|
|
1. Daemon monitors filesystem with fsnotify
|
|
2. On changes (debounced 500ms), create Git tree snapshot
|
|
3. Create ephemeral commit with auto-generated message
|
|
4. Update refs/onyx/workspaces/current pointer
|
|
|
|
### Workstream Sync
|
|
1. Fetch latest from origin base branch
|
|
2. Sequentially rebase each commit in workstream stack
|
|
3. Use rerere for automated conflict resolution
|
|
4. Update all branch refs atomically
|
|
|
|
### Action Log Transaction
|
|
1. Capture state_before (all managed refs)
|
|
2. Execute command logic
|
|
3. Capture state_after
|
|
4. Write entry to oplog with both states
|
|
|
|
This architecture enables sophisticated workflows while maintaining full Git compatibility. |