ze - Quick Configuration Editor¶

ze [target]
```bash

### Targets

- **No argument**: Edit main framework file (`zshrc.zsh`)
- **Partial name**: Fuzzy match in `core/` directory
  - `ze alias` → `core/05_aliases.zsh`
  - `ze func` → `core/90_functions.zsh`
- **Special targets**:
  - `ze main` or `ze zshrc` → `~/.zshrc` (user file)
  - `ze os` or `ze ubuntu` → OS-specific template

## Examples

### Basic Editing

```bash
# Edit main framework configuration file
# Opens the primary config file in your editor with syntax validation
ze

# Edit aliases configuration
# Opens the aliases file for adding/removing shell aliases
ze alias

# Edit functions
# Opens the functions directory for editing custom functions
ze func

# Edit core configuration
# Opens core framework settings like theme, plugins, etc.
ze core
```bash

### OS-Specific Configuration

```bash
# Edit Ubuntu-specific settings
# Configures Ubuntu/Debian-specific paths, package managers, etc.
ze ubuntu

# Edit macOS settings
# Configures macOS-specific features like Homebrew, Spotlight, etc.
ze osx

# Edit WSL configuration
# Configures Windows Subsystem for Linux specific settings
ze wsl
```bash

### Advanced Usage

```bash
# Edit specific function by name
# Opens functions/my-function.zsh if it exists
ze functions/my-function

# Edit private functions
# Opens private user functions not shared in dotfiles
ze private

# Edit hooks
# Opens Zsh hook configurations for prompt, chpwd, etc.
ze hooks

# Edit keybindings
# Opens custom keybinding configurations
ze keys
```bash

### Workflow Examples

```bash
# Quick alias addition
ze alias
# Add: alias ll='ls -la'
# Save, validate, rebuild

# Function development
ze functions/new-feature
# Write function code
# Save, validate, rebuild, test

# Configuration tuning
ze core
# Adjust settings like theme, plugins
# Save, validate, rebuild
```bash

### Advanced Usage

```bash
# Edit with specific editor
EDITOR=nvim ze core

# Edit and immediately rebuild
ze hooks && zr
```bash

## Workflow

1. **Target resolution**: Fuzzy matches your input to find the right file
2. **Editor launch**: Opens file in `$EDITOR` with `--block` (waits for close)
3. **Syntax validation**: Runs `zsh -n` to check for syntax errors
4. **Rebuild suggestion**: If valid, prompts to run `zr` to apply changes
5. **Error handling**: If invalid, shows error and suggests fixes

## Configuration

### Editor Selection

`ze` uses the `$EDITOR` environment variable:

```bash
# Set preferred editor
export EDITOR=nvim
export EDITOR=code
export EDITOR=emacs
```bash

### Fuzzy Matching

Searches these locations in order:

1. `core/` directory (framework files)
2. OS-specific templates in `installers/`
3. Special targets (`main`, `zshrc`)

## Dependencies

- **Required:** `zsh`, `$EDITOR` with `--block` support
- **Optional:** `zr` (for rebuild suggestions)

## Troubleshooting

### Editor Won't Open

**Symptom:** `ze` exits without opening editor

**Cause:** `$EDITOR` not set or doesn't support `--block`

**Fix:**

```bash
# Set editor with block support
export EDITOR="code --wait"
export EDITOR="cursor --block"

# Test editor
$EDITOR --help | grep -i block
```bash

### Syntax Errors

**Symptom:** "Syntax error in file" message

**Cause:** Invalid Zsh syntax in edited file

**Fix:**

```bash
# Check syntax manually
zsh -n core/file.zsh

# Edit again
ze file

# Get better error messages
ZSHAND_DEV_MODE=1 exec zsh
```bash

### File Not Found

**Symptom:** "No matching file found"

**Cause:** Fuzzy match didn't find your intended file

**Fix:**

```bash
# List available files
ls core/*.zsh

# Use more specific search
ze aliases  # instead of "alias"
```bash

## Performance

- **Launch time**: Instant (no diff generation)
- **Validation**: Fast syntax check (~100ms)
- **Rebuild suggestion**: Optional, can be skipped

## Integration

### With zd (Diff Editor)

```bash
# Quick edit (fast)
ze config

# Careful edit (with review)
zd config
```bash

### With zr (Rebuild)

```bash
# Manual workflow
ze functions
zr  # Apply changes

# Suggested workflow (ze prompts for zr)
ze functions
# "Run zr to rebuild? [Y/n]" y
```bash

### With Development

```bash
# Edit-rebuild-test cycle
ze my-function && zr --quiet && exec zsh

# Multiple edits
ze core && ze functions && zr
```bash

## Technical Details

### Target Resolution Algorithm

1. **Exact match**: Check for exact filename
2. **Prefix match**: Find files starting with target
3. **Substring match**: Find files containing target
4. **Special targets**: Handle `main`, `zshrc`, OS names

### Syntax Validation

- Uses `zsh -n` for syntax checking
- Only validates the edited file (not dependencies)
- Catches common errors: unclosed quotes, missing `fi`/`done`, etc.

### Editor Integration

- Passes `--block` flag to wait for editor to close
- Preserves all editor arguments and environment
- Works with: VS Code, Cursor, Vim, Emacs, etc.

## Gotchas

### Editor Not Configured

**Problem:** "EDITOR not set" or editor doesn't open.

**Cause:** `$EDITOR` environment variable not set.

**Solution:** Set your preferred editor:

```bash
export EDITOR="code"        # VS Code
export EDITOR="cursor"      # Cursor
export EDITOR="vim"         # Vim
export EDITOR="emacs"       # Emacs
```bash

### Syntax Validation Fails

**Problem:** File saves but syntax validation reports errors.

**Cause:** Zsh syntax errors in the file.

**Solution:** Fix the syntax errors. Common issues:

- Missing quotes around variables: `$VAR` → `"$VAR"`
- Incorrect array syntax: `array=(item1 item2)` → `array=("item1" "item2")`
- Unmatched brackets or quotes

### Rebuild Prompt Ignored

**Problem:** Changes don't take effect even after rebuilding.

**Cause:** Need to restart shell session for compiled changes to load.

**Solution:** Run `exec zsh` or start a new terminal session after `zr`.

### File Not Found

**Problem:** "File not found" error.

**Cause:** Target doesn't exist or wrong path.

**Solution:** Use tab completion or check available targets with `ze --list`.
Common targets: `config`, `aliases`, `functions/my-function`, etc.

### Editor Hangs

**Problem:** `ze` appears to hang or doesn't return.

**Cause:** Editor not properly configured for blocking mode.

**Solution:** Some editors need special flags. For VS Code:

```bash
export EDITOR="code --wait"
```bash

### Large Files Slow

**Problem:** Opening very large configuration files is slow.

**Cause:** Some editors struggle with large files.

**Solution:** Use `zd` for large files (shows diffs) or split large configs
into smaller files.

## See Also

- **[zd](zd.md)** - Diff-based editor (safer for complex changes)
- **[zr](zr.md)** - Framework rebuild tool
- **[rclink](rclink.md)** - Zshrc setup and management
- **[Configuration Guide](../../README.md#configuration)** - Framework
  configuration overview