daaaea5c82
RFC 0001 - Cross-Repo Coordination with Realms: - Daemon architecture with HTTP server on localhost:7865 - SQLite persistence for sessions, realms, notifications - Realm service with git-based storage and caching - CLI commands: realm status/sync/check/worktree/pr/admin - Session coordination for multi-repo work RFC 0002 Phase 1 - Realm MCP Integration: - realm_status: Get realm overview (repos, domains, contracts) - realm_check: Validate contracts/bindings with errors/warnings - contract_get: Get contract details with bindings - Context detection from .blue/config.yaml - 98% expert panel alignment via 12-expert dialogue Also includes: - CLI documentation in docs/cli/ - Spike for Forgejo tunnelless access - 86 tests passing Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
203 lines
5.1 KiB
Markdown
203 lines
5.1 KiB
Markdown
# Realm CLI
|
|
|
|
Cross-repo coordination for shared contracts and dependencies.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 1. Create a realm
|
|
blue realm admin init --name mycompany
|
|
|
|
# 2. Join repos to the realm (run in each repo)
|
|
cd ~/projects/api-server
|
|
blue realm admin join mycompany
|
|
|
|
cd ~/projects/web-client
|
|
blue realm admin join mycompany
|
|
|
|
# 3. Create a domain for coordination
|
|
blue realm admin domain --realm mycompany --name api-types --repos api-server,web-client
|
|
|
|
# 4. Define a contract (owned by api-server)
|
|
blue realm admin contract --realm mycompany --domain api-types --name user-schema --owner api-server
|
|
|
|
# 5. Create bindings
|
|
blue realm admin binding --realm mycompany --domain api-types --repo api-server --role provider
|
|
blue realm admin binding --realm mycompany --domain api-types --repo web-client --role consumer
|
|
|
|
# 6. Check everything is valid
|
|
blue realm check
|
|
```
|
|
|
|
## Concepts
|
|
|
|
**Realm** - A coordination space for multiple repos. Think of it as a shared namespace.
|
|
|
|
**Domain** - A specific area of coordination within a realm. Example: "api-types", "s3-access", "config-schemas".
|
|
|
|
**Contract** - A versioned schema or value that one repo exports and others import. Has a single owner who can modify it.
|
|
|
|
**Binding** - Declares a repo's relationship to a domain: provider (exports contracts), consumer (imports), or both.
|
|
|
|
## Commands
|
|
|
|
### Status & Validation
|
|
|
|
```bash
|
|
# Show realm status - repos, domains, contracts, bindings
|
|
blue realm status
|
|
|
|
# Validate all contracts and bindings
|
|
blue realm check
|
|
|
|
# Check specific realm with strict mode (fail on warnings)
|
|
blue realm check --realm mycompany --strict
|
|
|
|
# Sync pending changes to realm repo
|
|
blue realm sync
|
|
```
|
|
|
|
### Administration
|
|
|
|
```bash
|
|
# Initialize a new realm
|
|
blue realm admin init --name <name> [--forgejo <url>]
|
|
|
|
# Join current repo to a realm
|
|
blue realm admin join <realm-name> [--repo <name>]
|
|
|
|
# Create a domain
|
|
blue realm admin domain --realm <realm> --name <domain> --repos <repo1,repo2,...>
|
|
|
|
# Create a contract
|
|
blue realm admin contract --realm <realm> --domain <domain> --name <contract> --owner <repo>
|
|
|
|
# Create a binding
|
|
blue realm admin binding --realm <realm> --domain <domain> --repo <repo> --role <provider|consumer|both>
|
|
```
|
|
|
|
### Worktree Management
|
|
|
|
For working on changes across multiple repos simultaneously:
|
|
|
|
```bash
|
|
# Create worktrees for an RFC (creates branch + worktree in each repo)
|
|
blue realm worktree create --rfc rfc-0042-new-api
|
|
|
|
# List active worktrees
|
|
blue realm worktree list
|
|
|
|
# Remove worktrees when done
|
|
blue realm worktree remove --rfc rfc-0042-new-api
|
|
```
|
|
|
|
### PR Workflow
|
|
|
|
Coordinate PRs across multiple repos:
|
|
|
|
```bash
|
|
# Check PR status across repos
|
|
blue realm pr status --rfc rfc-0042-new-api
|
|
|
|
# Commit uncommitted changes in all worktrees
|
|
blue realm pr prepare --rfc rfc-0042-new-api --message "Implement new API"
|
|
```
|
|
|
|
### Sessions
|
|
|
|
Track active work across repos:
|
|
|
|
```bash
|
|
# Start a work session (run in repo directory)
|
|
blue session start --rfc rfc-0042-new-api
|
|
|
|
# List active sessions
|
|
blue session list
|
|
|
|
# Check session status
|
|
blue session status
|
|
|
|
# End session
|
|
blue session stop
|
|
```
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
~/.blue/
|
|
├── daemon.db # Session and notification state
|
|
└── realms/
|
|
└── mycompany/ # Realm repo (git)
|
|
├── realm.yaml # Realm config
|
|
├── repos/
|
|
│ ├── api-server.yaml
|
|
│ └── web-client.yaml
|
|
└── domains/
|
|
└── api-types/
|
|
├── domain.yaml
|
|
├── contracts/
|
|
│ └── user-schema.yaml
|
|
└── bindings/
|
|
├── api-server.yaml
|
|
└── web-client.yaml
|
|
```
|
|
|
|
Each repo that joins a realm gets:
|
|
|
|
```
|
|
my-repo/
|
|
└── .blue/
|
|
├── config.yaml # Realm membership
|
|
└── session # Active session ID (if any)
|
|
```
|
|
|
|
## Example: S3 Access Coordination
|
|
|
|
Two repos need to coordinate S3 bucket access - one defines paths, the other consumes them.
|
|
|
|
```bash
|
|
# Setup
|
|
blue realm admin init --name letemcook
|
|
blue realm admin domain --realm letemcook --name s3-access --repos aperture,fungal
|
|
blue realm admin contract --realm letemcook --domain s3-access --name s3-permissions --owner aperture
|
|
blue realm admin binding --realm letemcook --domain s3-access --repo aperture --role provider
|
|
blue realm admin binding --realm letemcook --domain s3-access --repo fungal --role consumer
|
|
|
|
# Aperture exports paths it uses
|
|
# (edit ~/.blue/realms/letemcook/domains/s3-access/contracts/s3-permissions.yaml)
|
|
|
|
# Fungal imports those paths for IAM policies
|
|
# (its binding declares the import)
|
|
|
|
# Validate
|
|
blue realm check
|
|
```
|
|
|
|
## Daemon
|
|
|
|
The daemon tracks sessions and notifications. Start it before using session commands:
|
|
|
|
```bash
|
|
# Start daemon (foreground)
|
|
blue daemon start
|
|
|
|
# Check if running
|
|
blue daemon status
|
|
```
|
|
|
|
The daemon runs on `localhost:7865` and stores state in `~/.blue/daemon.db`.
|
|
|
|
## CI Integration
|
|
|
|
Add to your CI pipeline:
|
|
|
|
```yaml
|
|
- name: Check realm contracts
|
|
run: blue realm check --strict
|
|
```
|
|
|
|
This validates:
|
|
- All contracts have valid semver versions
|
|
- All bindings reference existing contracts
|
|
- Import version requirements are satisfied
|
|
- No broken imports
|