221 lines
7.4 KiB
Markdown
221 lines
7.4 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 push --stacked` | Push stacked diffs | N/A (advanced) |
|
|
| `onx undo` | Undo last operation | `git reflog && reset` |
|
|
|
|
## Push Workflows
|
|
|
|
Onyx supports two push workflows to match different development styles:
|
|
|
|
### Single-Branch Mode (Default) - Recommended for AI Development
|
|
|
|
```bash
|
|
onx push
|
|
```
|
|
|
|
**When to use:**
|
|
- Default for all standard feature development
|
|
- When creating traditional pull requests
|
|
- For AI-assisted development sessions
|
|
- When you want a clean remote repository UI
|
|
|
|
**What happens:**
|
|
- Pushes workstream as ONE branch named after the workstream
|
|
- Example: `milestone-4` branch contains all commits
|
|
- Remote UI shows single branch per workstream (clean)
|
|
- Perfect for creating GitHub/Gitea pull requests
|
|
|
|
**AI Development Guidance:**
|
|
Use this mode by default. It provides the cleanest integration with standard Git workflows and PR creation tools.
|
|
|
|
### Stacked Diffs Mode (Advanced)
|
|
|
|
```bash
|
|
onx push --stacked
|
|
```
|
|
|
|
**When to use:**
|
|
- Large, complex features requiring incremental review
|
|
- When each commit needs independent review/approval
|
|
- Meta/Google-style stacked diff workflows
|
|
- When explicitly requested by the user
|
|
|
|
**What happens:**
|
|
- Pushes EACH commit as a separate branch
|
|
- Example: `onyx/workstreams/milestone-4/commit-1`, `commit-2`, etc.
|
|
- Remote UI shows multiple branches (one per commit)
|
|
- Each branch can have its own pull request
|
|
|
|
**AI Development Guidance:**
|
|
Only use when specifically requested or when the feature is complex enough to warrant incremental review. The additional branches may clutter the remote UI.
|
|
|
|
## 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
|
|
|
|
### IMPORTANT: Dogfooding Policy
|
|
|
|
**This repository uses Onyx for its own development.** All development work MUST use Onyx commands exclusively:
|
|
|
|
- ✅ **Use `onx save -m "message"`** to commit changes (NOT `git commit`)
|
|
- ✅ **Use `onx new <name>`** to create feature branches (NOT `git checkout -b`)
|
|
- ✅ **Use `onx switch <name>`** to switch workstreams (NOT `git checkout`)
|
|
- ✅ **Use `onx sync`** to update from remote (NOT `git pull`)
|
|
- ✅ **Use `onx push`** to push to remote (NOT `git push`)
|
|
- ✅ **Use `onx undo`** to undo operations (NOT `git reset`)
|
|
- ✅ **Use `onx list`** to view workstreams (NOT `git branch`)
|
|
|
|
**Exception:** Only use `git` commands for:
|
|
- Initial remote setup (`git remote add`)
|
|
- Creating pull requests via GitHub CLI (`gh pr create`)
|
|
- Inspecting low-level Git state when debugging Onyx itself
|
|
|
|
This dogfooding validates our user experience and ensures Onyx works correctly for real-world development.
|
|
|
|
### 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. |