# RainbowTerm - Claude Code Context

## CRITICAL: Config Sync Requirement

**After ANY changes to `config.toml`, ALWAYS sync to the installed config:**

```bash
# macOS
cp config.toml ~/Library/Application\ Support/rainbowterm/config.toml

# Linux
cp config.toml ~/.config/rainbowterm/config.toml
```

This is MANDATORY. The `rt` command uses the platform-specific config by default, NOT the project's `config.toml`. Failing to sync causes:
- New patterns appearing broken when they actually work
- Debugging the wrong config file
- Wasted time on phantom issues

**When to sync:** After every commit that touches `config.toml`, after switching branches, before testing.

---

## CRITICAL: Publish to crates.io After Push

**After pushing to remote, ALWAYS publish to crates.io:**

```bash
# Bump version in Cargo.toml first
cargo publish
```

This keeps the published crate in sync with the GitHub repository. Users installing via `cargo install rainbowterm` should get the latest patterns.

---

## CRITICAL: Regression Testing with Sample Files

**Before AND after adding/modifying ANY pattern in `config.toml`, ALWAYS run the sample files:**

```bash
# Test ALL profiles to catch regressions
# Juniper - show commands and config
for f in tests/networking/juniper/common/*.conf; do cat "$f" | rt --profile juniper; done
for f in tests/networking/juniper/ex/**/*.conf; do cat "$f" | rt --profile juniper; done
for f in tests/networking/juniper/qfx/**/*.conf; do cat "$f" | rt --profile juniper; done

# Other vendors
for f in tests/networking/cisco/ios/*.conf; do cat "$f" | rt --profile cisco; done
for f in tests/networking/arista/eos/*.conf; do cat "$f" | rt --profile arista; done
for f in tests/networking/versa/sdwan/*.conf; do cat "$f" | rt --profile versa; done
```

**Why this matters:**
- New patterns can break existing coloring due to priority conflicts
- Regex changes may have unintended side effects
- Visual inspection catches issues automated tests miss

**Sample file requirements:**
- Must cover ALL pattern types for that vendor/model
- Include edge cases and boundary conditions
- Represent real device output (not synthetic)
- Use `.conf` extension for sample files
- Organized by: `tests/networking/<vendor>/<series>/<model>/`

**File naming convention:**
- Show commands: `sample1.conf` or `<hostname>_prechecks_<date>.conf`
- Config hierarchical: `hierarchical.conf` or `<hostname>_configuration_<date>.conf`
- Config set: `set.conf` or `<hostname>_configuration_set_<date>.conf`
- Config inheritance: `inheritance.conf`
- Config diff: `diff.conf`

Descriptive naming (hostname/date) preferred for traceability.

**Collecting samples:**
1. Use `commands.txt` in each vendor directory as the command reference
2. Run PART 1 (show commands) in sequence → save to `sample1.conf`
3. Run PART 2 (config commands) → save to individual files as noted
4. Multiple show samples per model encouraged for coverage

**When adding new patterns:**
1. FIRST: Run existing samples, note current coloring
2. Add pattern to `config.toml`
3. Sync config to platform path
4. Run samples AGAIN - verify new pattern works AND nothing else broke
5. If adding new output types, ADD them to appropriate sample file

This is NON-NEGOTIABLE. Pattern regressions waste hours of debugging.

---

## Project Overview

**RainbowTerm** is a high-performance Rust CLI tool that provides context-aware syntax highlighting for network device output. It's designed for network engineers who work with routers and switches via SSH.

## Key Concepts

### Terminology: Semantic vs Context-Aware

- **Semantic Coloring** (the philosophy): Color based on *meaning*, not just pattern. The same value can have different colors depending on what it represents (e.g., `1298458` as traffic bytes = blue, as error count = red)
- **Context-Aware** (the mechanism): State machine that tracks multi-line context to enable semantic coloring (e.g., remembers "interface is UP" so subsequent "Half-duplex" = red warning)

### Unique Features
- **Magnitude Spectrum Coloring**: Numbers are colored by magnitude (hundreds→purple, thousands→blue, millions→green, etc.) for instant visual comprehension of packet/byte counters
- **Context-Aware State Machine**: Tracks multi-line state to enable semantic coloring across lines
- **Profile System**: Vendor-specific patterns with inheritance (base → juniper/cisco/arista)
- **Embedded Config**: Works immediately after install, no setup required

### Architecture
```
src/
├── main.rs      - Core engine, pattern matching, CLI
├── config.rs    - TOML parsing, profile management, pattern compilation
├── context.rs   - State machine for context-aware rules
├── convert.rs   - ChromaTerm YAML → TOML converter (optional 'convert' feature)
└── lib.rs       - Library interface

config.toml      - Default config (embedded via include_str!)
tests/           - Vendor-specific test files (no SSH required!)
```

## Current State

### Profiles Implemented (Priority Order)
1. ✅ **Juniper** (PRIMARY): JunOS interfaces (ge/xe/et/ae), BGP, OSPF, STP, logs
2. ⚠️ **Versa**: Test file created, profile NOT YET implemented in config.toml
3. ✅ **Cisco**: IOS/IOS-XE/NX-OS interfaces, BGP, OSPF, STP, VTP
4. ⚠️ **Arista**: Test file created, profile NOT YET implemented in config.toml

- ✅ **Base**: Universal patterns (IPs, MACs, dates, generic status) - inherited by all

### Installation
```bash
# From crates.io (recommended)
cargo install rainbowterm

# From GitHub
cargo install --git https://github.com/Legendberg/rainbowterm

# From local source
cargo install --path .
```
Creates single binary: `rt`

### Usage
```bash
ssh router "show interfaces" | rt
rt --profile cisco < cisco-output.txt
rt --list-profiles
```

## Configuration Paths

| OS | Config Path |
|----|-------------|
| **Linux** | `~/.config/rainbowterm/config.toml` |
| **macOS** | `~/Library/Application Support/rainbowterm/config.toml` |
| **Windows** | `C:\Users\<user>\AppData\Roaming\rainbowterm\config.toml` |

Config auto-creates on first run from embedded default.

## Development Workflow

### Testing (No SSH Required!)
```bash
# Manual testing
cat tests/networking/juniper/common/sample.txt | rt --profile juniper
cat tests/networking/cisco/ios/sample.txt | rt --profile cisco

# Automated testing
cargo test                          # All tests
cargo test --test integration_tests # Integration only
```

### Adding New Patterns
1. Add regex pattern to `config.toml` under appropriate profile
2. Set priority (200=critical, 100=interfaces, 90=states, etc.)
3. Test with: `cargo run -- --profile <name> < tests/<vendor>-sample.txt`
4. Sync config: `cp config.toml <platform-config-path>/config.toml`
5. Rebuild: `cargo install --path .`

### Configuration Priority System
- **200+**: Critical keywords (error, warning, failure)
- **168**: Error counter zeros (green = healthy)
- **166-160**: Error spectrum (trillions down to hundreds)
- **155-150**: Dropped packets column (error spectrum)
- **155-145**: Neutral spectrum (trillions down to hundreds) and queue counters
- **100**: Interface names
- **90**: Protocol states (BGP, OSPF, STP)
- **85**: Routing markers, roles
- **80**: Speed indicators
- **10**: Generic up/down

## Important Files

### config.toml Structure
```toml
[palette]           # Color definitions (#hex)
[profiles.base]     # Universal patterns
[profiles.juniper]  # Inherits from base
[profiles.cisco]    # Inherits from base
```

### Pattern Format
```toml
[[profiles.vendor.patterns]]
description = "Human-readable description"
regex = '''regex pattern'''
color = "palette-color-name"
priority = 100
[profiles.vendor.patterns.groups]  # Optional: per-capture-group colors
1 = "color-for-group-1"
```

## Known Issues / Gotchas

1. **Config Caching**: `include_str!` embeds config at compile time. After editing `config.toml`:
   - Users with existing config need to update it manually
   - Or delete it to use embedded default
   - Fresh installs always get latest embedded config

2. **Development Config Drift**: ⚠️ **SEE CRITICAL SECTION AT TOP OF FILE** ⚠️
   - The installed config at platform-specific path is used by default
   - Project's `config.toml` changes are NOT automatically installed
   - **ALWAYS sync after config changes**

3. **Cargo Install**: Must use `--path .` for local changes, or `--git` for GitHub

4. **Test Files**: Arista test file exists but profile implementation is incomplete

5. **TOML Syntax**: Watch for nested sections - new `[profiles.vendor]` must be at top level, not inside another profile's arrays

## Git Workflow

- **Main branch**: `main`
- **Remote alias**: `github-legendberg` (SSH key: `~/.ssh/id_ed25519_github2`)
- **Push**: `git push github-legendberg main`
- **Clone**: `git clone git@github-legendberg:Legendberg/rainbowterm.git`

The `github-legendberg` SSH alias is configured in `~/.ssh/config` to use a dedicated SSH key for this account.

## Code Style

- Rust 2021 edition
- Use `anyhow` for error handling
- Regex patterns: Use raw strings `'''pattern'''`
- Keep main.rs focused on colorization logic
- Config parsing in config.rs
- Release build: LTO enabled, stripped, optimized for size

## Dependencies

- `regex` - Pattern matching engine
- `clap` - CLI with derive macros
- `toml` (0.9) - Config parsing
- `termcolor` - Terminal color output
- `dirs` (6.0) - Platform config directory detection
- `serde` - Config serialization
- `anyhow` - Error handling

## Status

- **Version**: 0.2.9
- **Published**: [crates.io/crates/rainbowterm](https://crates.io/crates/rainbowterm)
- **License**: MIT OR Apache-2.0

## Next Steps (Roadmap)

**Vendor Priority: Juniper → Versa → Cisco → Arista**

- [ ] Expand Juniper coverage (MX, SRX, QFX-specific patterns)
- [ ] Complete Versa SD-WAN profile implementation
- [ ] Enhance Cisco profile (NX-OS, ASA)
- [ ] Complete Arista EOS profile implementation
- [ ] Shell completions (bash, zsh, fish)
- [ ] Performance benchmarks
- [ ] Additional vendor profiles (Palo Alto, F5, Fortinet, etc.)

## Testing Philosophy

**Sample files are the source of truth for visual correctness.**

We maintain comprehensive test files with realistic vendor output so development doesn't require SSH access to actual devices. These files serve dual purposes:
1. **Verification**: Confirm new patterns produce expected colors
2. **Regression**: Ensure existing patterns aren't broken

### Test File Structure
```
tests/networking/
├── juniper/
│   ├── commands.txt         # Command reference (PART 1: show, PART 2: config)
│   ├── common/              # Patterns shared across Juniper platforms
│   │   ├── sample1.conf     # Show commands output
│   │   └── spectrum.conf    # Magnitude spectrum test cases
│   ├── ex/                  # EX series (access/distribution switches)
│   │   ├── ex2300/
│   │   │   ├── sample1.conf       # Show commands
│   │   │   ├── sample2.conf
│   │   │   ├── hierarchical.conf  # Config formats
│   │   │   ├── set.conf
│   │   │   ├── inheritance.conf
│   │   │   └── diff.conf
│   │   ├── ex3400/
│   │   ├── ex4100/
│   │   └── ex4600/
│   ├── qfx/                 # QFX series (datacenter/spine-leaf)
│   │   ├── qfx5110/
│   │   └── qfx10002/
│   ├── mx/                  # MX series (routers) - TODO
│   └── srx/                 # SRX series (firewalls) - TODO
├── cisco/
│   ├── commands.txt
│   ├── ios/                 # IOS/IOS-XE
│   ├── nxos/                # Nexus - TODO
│   └── asa/                 # Firewall - TODO
├── arista/
│   ├── commands.txt
│   └── eos/                 # Arista EOS
└── versa/
    ├── commands.txt
    └── sdwan/               # Versa SD-WAN (FlexVNF/Director)
```

### When Adding Patterns
1. Run ALL sample files BEFORE making changes (establish baseline)
2. Add realistic examples to appropriate sample file
3. Test both positive matches AND edge cases
4. Verify priority ordering with overlapping patterns
5. Check magnitude spectrum colors on various number sizes
6. Run ALL sample files AFTER changes (regression check)
7. Visually compare before/after - automated tests can't catch color issues

## Common Commands

```bash
# Development
cargo build --release
cargo install --path .
cargo check

# Testing
cargo test
cat tests/networking/juniper/common/sample.txt | rt --profile juniper

# Sync config (IMPORTANT - do this when switching branches or debugging)
# macOS:
cp config.toml ~/Library/Application\ Support/rainbowterm/config.toml
# Linux:
cp config.toml ~/.config/rainbowterm/config.toml

# Debugging
rt --list-profiles
rt --no-context < output.txt  # Disable state machine

# Git (uses github-legendberg SSH alias)
git push github-legendberg main
```

## Context for Claude

When working on this project:
- **Vendor priority: Juniper → Versa → Cisco → Arista** - focus efforts accordingly
- **ALWAYS run sample files before AND after pattern changes** - this catches regressions
- **Semantic over syntactic**: Always ask "what does this mean in context?" before coloring
- Prioritize correctness of regex patterns over brevity
- Test changes with the test files before committing
- Update test files when adding new pattern types - samples must stay comprehensive
- Keep patterns vendor-specific (don't add Cisco patterns to Juniper profile)
- Remember: magnitude spectrum is a key differentiator
- The `rt` command should feel instant (performance matters)
- Use context-aware rules when the same keyword has different meanings based on state
- When I ask about colors in output, I can see them - describe what you observe

## Project Philosophy

1. **Zero Configuration**: Works immediately after install
2. **Visual Clarity**: Colors convey meaning (magnitude, state, criticality)
3. **Semantic Coloring**: Color based on *meaning*, not just keywords. The same word can mean different things:
   - `up down` (admin up, link down) = 🔴 Red (problem)
   - `down down` (admin down, link down) = 🟡 Yellow (intentional, but notable)
   - `up up` = 🟢 Green (healthy)
   - Achieved via context-aware state machine that tracks meaning across lines
4. **Vendor Aware**: Respect syntax differences between vendors
5. **Developer Friendly**: Test without hardware access
6. **Performance**: No lag on large outputs (SSH compatibility)
