MuyueWorkspace/README.md

# muyue

AI-powered development environment assistant by **La Légion de Muyue**.

## What it does

`muyue` is a single binary that transforms your entire development environment:

- **Scans** your system for tools, runtimes, and configs
- **Installs** missing tools automatically (Crush, Claude Code, BMAD, Starship, runtimes...)
- **Updates** everything in the background
- **Profiles** you on first run to personalize the experience
- **Unifies** control of Crush and Claude Code from one TUI
- **Orchestrates** AI agents via MiniMax M2.7
- **Customizes** your terminal prompt (branch, commits, language, etc.)
- **Configures** MCP servers, LSPs, and skills automatically
- **Previews** HTML/visual outputs in your browser

## Tech Stack

- **Go** — single binary, no dependencies
- **Charm** — Bubble Tea, Lip Gloss, Huh (TUI, styling, forms)
- **Starship** — terminal prompt customization
- **MiniMax M2.7** — AI orchestration
- **BMAD-METHOD** — structured development workflows

## Install

```bash
go build -o muyue ./cmd/muyue/
```

Or with Make:

```bash
make build
make install-local
```

## Usage

```bash
muyue              # Start interactive TUI
muyue scan         # Scan system
muyue install      # Install missing tools
muyue update       # Check and apply updates
muyue setup        # Run setup wizard
muyue config       # Show configuration
muyue doctor       # Diagnose configuration issues
muyue version      # Show version
```

### LSP Management

```bash
muyue lsp scan              # Scan for installed LSP servers
muyue lsp install           # Install LSPs for configured languages
muyue lsp install gopls     # Install a specific LSP
```

### MCP Server Configuration

```bash
muyue mcp config            # Configure MCP servers for Crush and Claude Code
muyue mcp scan              # Scan available MCP servers
```

### Skills Management

```bash
muyue skills list           # List installed skills
muyue skills init           # Install built-in skills
muyue skills show <name>    # Show skill details
muyue skills generate <name> <desc> [crush|claude|both]  # AI-generate a skill
muyue skills deploy         # Deploy skills to Crush and Claude Code
muyue skills delete <name>  # Delete a skill
```

## TUI — 4 Tabs

The TUI is organized into 4 tabs with a red/rose theme (`#E8364F` → `#FF6B8A`):

### ◉ Dashboard

System overview: installed tools with status, active agents, updates, LSP/MCP/daemon status, and quick actions (install, update, scan).

### ◈ Studio

Central AI chat with a collapsible sidebar (`Ctrl+S`) containing 3 panels:

| Panel | Shortcut | Description |
|-------|----------|-------------|
| **Chat** | `1` | AI conversation, `/plan <goal>` to start workflows |
| **Agents** | `2` | Start/stop Crush and Claude Code agents |
| **Workflows** | `3` | Plan→Execute workflow controls (approve, reject, next step) |

### ▶ Shell

Split-view terminal with an AI assistant panel (`Ctrl+A` to toggle). The AI knows your system and suggests commands you can easily copy into the terminal.

### ⚙ Config

Profile, API providers, terminal/starship settings, BMAD, and skills — displayed in a two-column layout.

### Keyboard Shortcuts

| Key | Context | Action |
|-----|---------|--------|
| `Ctrl+T` | Global | Open tab switcher |
| `Ctrl+S` | Studio | Toggle sidebar |
| `Ctrl+A` | Shell | Toggle AI assistant panel |
| `Ctrl+C` | Global | Quit confirmation |
| `i` | Dashboard | Install missing tools |
| `u` | Dashboard | Check for updates |
| `s` | Dashboard | Rescan system |
| `1` `2` `3` | Studio sidebar | Switch panels (Chat/Agents/Workflows) |
| `a` | Workflow | Approve plan |
| `r` | Workflow | Reject plan |
| `g` | Workflow | Generate plan |
| `n` | Workflow | Next step |
| `x` | Workflow | Cancel workflow |

## Configuration

Config stored at `$XDG_CONFIG_HOME/muyue/config.yaml` (defaults to `~/.config/muyue/config.yaml`).

API keys are encrypted at rest using AES-GCM with a machine-local key stored in `~/.muyue_key`.

First run launches an interactive profiling wizard that:
1. Asks your name, pseudo, email
2. Detects your languages and editor
3. Chooses your AI provider
4. Scans your system
5. Installs missing tools

## Security

- API keys are encrypted at rest (AES-256-GCM) with a per-machine key
- Config files use restrictive permissions (0600)
- MCP config files use restrictive permissions (0600)
- Integrated terminal blocks dangerous commands (rm -rf /, mkfs, fork bombs, etc.)

## Cross-Platform

Built for Linux (primary), macOS, and Windows. WSL supported.

## Contributing — GitFlow Workflow

This project uses a **lightweight GitFlow** with 2 permanent branches and conventional commits.

### Branch model

```
feature/xxx  ──PR (squash)──▶  develop  ──PR (merge)──▶  main
fix/xxx      ──PR (squash)──▶  develop
hotfix/xxx   ──PR (squash)──▶  main (+ backport develop)
```

| Branch | Purpose | Permanent? |
|--------|---------|------------|
| `main` | Production — stable releases only | Yes |
| `develop` | Integration — all features merge here first | Yes |
| `feature/*` | New feature or enhancement | No (deleted after merge) |
| `fix/*` | Bug fix | No |
| `hotfix/*` | Urgent fix on production | No |

### Release channels

| Event | Channel | Tag format | Prerelease? |
|-------|---------|------------|-------------|
| PR merge → `develop` | **Beta** | `vX.Y.Z-beta.N` | Yes |
| Merge `develop` → `main` | **Stable** | `vX.Y.Z` | No |

### CI/CD Pipelines

| Workflow | Trigger | What it does |
|----------|---------|--------------|
| `ci-pr.yml` | PR to `main` or `develop` | vet + test + build (no release) |
| `ci-develop.yml` | Push to `develop` | vet + test + build all platforms + create beta release |
| `ci-main.yml` | Push to `main` | vet + test + build all platforms + update CHANGELOG.md + create stable release |

### Step-by-step: contribute a feature

```bash
# 1. Create your branch from develop
git checkout develop
git pull
git checkout -b feature/my-feature

# 2. Work, commit with conventional messages
git commit -m "feat: add amazing thing"
git commit -m "docs: update usage"

# 3. Push and create a PR to develop (squash merge)
git push -u origin feature/my-feature
# → Create PR on Gitea: feature/my-feature → develop
# → CI runs ci-pr.yml (test + vet + build)
# → Squash & merge the PR
# → ci-develop.yml triggers: beta release created
```

### Step-by-step: release a stable version

```bash
# 1. Bump the version in internal/version/version.go
#    Change: Version = "0.2.1"  →  Version = "0.3.0"
#    Commit on develop:
git checkout develop
# (edit internal/version/version.go)
git commit -m "chore: bump version to 0.3.0"
git push

# 2. Create a PR from develop to main
# → CI runs ci-pr.yml (test + vet + build)
# → Merge the PR
# → ci-main.yml triggers:
#    - Builds all platforms
#    - Auto-generates changelog from conventional commits
#    - Updates CHANGELOG.md
#    - Creates stable release v0.3.0
```

### Step-by-step: hotfix on production

```bash
# 1. Create hotfix branch from main
git checkout main
git pull
git checkout -b hotfix/critical-fix

# 2. Fix and commit
git commit -m "fix: resolve critical issue"

# 3. Create PR to main (squash merge)
# → CI runs, then ci-main.yml creates a new stable release

# 4. Backport to develop
git checkout develop
git merge hotfix/critical-fix
git push
```

### Versioning — How it works

**The base version (`X.Y.Z`) is manual.** It lives in `internal/version/version.go`:

```go
const (
    Version = "0.2.1"  // ← bump this before a release
)
```

**The prerelease suffix is automatic:**

- **Beta**: `ci-develop.yml` auto-increments `beta.N` by counting existing `vX.Y.Z-beta.*` tags
- **Stable**: `ci-main.yml` uses the exact version from `version.go` (no suffix)

Binary version is injected at build time via `-ldflags`:

```bash
# Beta build (automatic in CI)
go build -ldflags="-X github.com/muyue/muyue/internal/version.Prerelease=beta.3" ./cmd/muyue/
# → muyue v0.2.1-beta.3

# Stable build (automatic in CI)
go build -ldflags="-s -w" ./cmd/muyue/
# → muyue v0.2.1
```

### Conventional commits

Use [Conventional Commits](https://www.conventionalcommits.org/) for all commit messages:

| Prefix | Use for | Example |
|--------|---------|---------|
| `feat:` | New feature | `feat: add Docker support` |
| `fix:` | Bug fix | `fix: correct config path on Windows` |
| `docs:` | Documentation | `docs: add API reference` |
| `chore:` | Maintenance | `chore: bump version to 0.3.0` |
| `refactor:` | Code restructuring | `refactor: split scanner module` |
| `perf:` | Performance | `perf: cache scanner results` |
| `test:` | Tests | `test: add config unit tests` |
| `ci:` | CI/CD changes | `ci: add beta release workflow` |
| `security:` | Security fixes | `security: encrypt API keys at rest` |

### Branch protection (configure in Gitea UI)

- **`main`**: Require PR + passing CI + at least 1 approval
- **`develop`**: Require PR + passing CI
- **Squash merge**: Enabled by default for PRs to `develop`
- **Merge commit**: For PRs from `develop` to `main`

## License

MIT