temp for tree extraction
This commit is contained in:
221
CLAUDE.md
Normal file
221
CLAUDE.md
Normal file
@ -0,0 +1,221 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user