PLOW-41 - trckr

← PLOW-41

feature

Created: 2025-12-21 • Updated: 2025-12-21

Relationships Loading...

## Summary

Change the default behavior of `trckr-plow visualize` from ASCII to Mermaid SVG output. Add `--ascii` flag for users who prefer terminal output.

## Implementation

### CLI Changes

```python
@main.command()
@click.option("--step", "-s", help="Highlight a specific step")
@click.option("--ascii", "-a", is_flag=True, help="Output ASCII diagram to terminal (legacy)")
def visualize(step: str | None, ascii: bool) -> None:
    """Display the workflow as a diagram.
    
    By default, renders as SVG and opens in your default viewer.
    Use --ascii for terminal output.
    """
    if ascii:
        # Legacy ASCII output
        ...
    else:
        # Default: Mermaid SVG
        ...
```

### Behavior

- `trckr-plow visualize` → Mermaid SVG (opens viewer)
- `trckr-plow visualize --ascii` → ASCII to terminal
- `trckr-plow visualize --step 1` → Mermaid SVG with highlight
- `trckr-plow visualize --step 1 --ascii` → ASCII with highlight

### Migration

- Remove `--mermaid` flag (becomes default)
- Add `--ascii` flag for backward compatibility
- Update help text and docstrings
- Update README examples

## Files to Modify

- `src/trckr_plow/cli.py` - Change default, add --ascii flag
- `tests/test_cli.py` - Update tests for new defaults
- `README.md` - Update visualization examples

## Acceptance Criteria

- [ ] `trckr-plow visualize` opens SVG in viewer (not terminal output)
- [ ] `trckr-plow visualize --ascii` shows ASCII diagram in terminal
- [ ] `--step` flag works with both modes
- [ ] Help text clearly explains default behavior
- [ ] Graceful fallback to ASCII if mmdc not installed (with warning)

Pull Requests (comma-separated URLs)

Attachments

Comments (1)

agent · 2025-12-21

## Implementation Complete Changed the default visualization mode from ASCII to Mermaid SVG output: ### Changes Made **src/trckr_plow/cli.py:692-720** - Updated visualize command to use --ascii / -a flag for terminal output - Added short flag -s for --step option - Updated docstring to reflect new default behavior **src/trckr_plow/visualization.py:395-563** - Added is_mmdc_available() function to check for mermaid-cli - Added render_workflow_svg() to generate SVG via mmdc - Added open_svg_viewer() to open SVG in system viewer (supports macOS, Windows, Linux) - Added visualize_workflow() main function with intelligent fallback - Graceful fallback to ASCII with warning if mmdc not installed **tests/test_cli.py:714-803** - Updated tests to use --ascii flag for ASCII output assertions - Added tests for new default fallback behavior - Added tests for short flags (-a, -s) **README.md:229-271** - Updated documentation to reflect new default behavior - Added usage examples for all flag combinations ### Verification - All 791 tests pass - Linter (ruff) passes - Manual testing confirms: - trckr-plow visualize → Falls back to ASCII with warning (mmdc not installed) - trckr-plow visualize --ascii → ASCII output without warning - trckr-plow visualize -s 1 -a → ASCII with highlighted step