Migration to CLI-first, more testable, UI independent architecture

[RamiAwar]

Privileged issue

• I've been directed through Discussions to create an issue here.

Issue Content

Problem Statement

Pet currently faces two major architectural challenges:

1. Testing is Extremely Difficult

• The application is CUI-first with tightly coupled I/O operations
• Features chain together in a pipeline requiring user interaction (load -> filter -> fzf/peco -> gocui -> substitute)
• The monolithic filter() function in cmd/util.go is nearly impossible to unit test
• Global state in dialog/params.go makes testing even harder

2. CLI Potential is Wasted

• Pet is designed CUI-first, requiring interactive selection for everything
• No way to execute commands directly: pet exec "docker ps" doesn't exist
• Can't pass parameters via flags for scripting/automation
• Users want one-line commands but are forced through interactive prompts

Proposed Solution

Refactor Pet to use Hexagonal Architecture (Ports & Adapters) where:

• Core business logic is pure, testable, with zero I/O dependencies
• Adapters handle all I/O (gocui, fzf/peco, files, etc.)
• Interfaces allow swapping implementations (interactive vs direct, real vs mock)
• CLI commands become thin composition layers

Architecture Overview

┌─────────────────────────────────────────────┐
│         Adapters (UI Layer)                 │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐ │
│  │CLI Direct│  │CUI Inter.│  │Future:API │ │
│  └────┬─────┘  └────┬─────┘  └─────┬─────┘ │
└───────┼─────────────┼──────────────┼───────┘
        │             │              │
┌───────▼─────────────▼──────────────▼───────┐
│     Application Ports (Interfaces)         │
│  - SnippetRepository                       │
│  - ParameterInput                          │
│  - Selector                                │
└──────────────────┬─────────────────────────┘
                   │
┌──────────────────▼─────────────────────────┐
│    Core Business Logic (Pure, No I/O)     │
│  - Snippet CRUD                            │
│  - Parameter extraction/substitution       │
│  - Tag filtering, validation               │
└──────────────────┬─────────────────────────┘
                   │
┌──────────────────▼─────────────────────────┐
│    Repository Implementations              │
│  - FileRepository (TOML)                   │
│  - GistRepository, GitLabRepository        │
└────────────────────────────────────────────┘

Dealing with Gocui

Gocui integration caused a lot of our business logic to be mingled with the main event loop.
Even though it has a blocking event loop, we can then hide it behind a simple interface:

// Interface
type ParameterInput interface {
    GetParameters(params []Parameter, command string) (map[string]string, error)
}
 
// Implementations
- GocuiParameterInput (interactive, current behavior)
- FlagParameterInput (CLI flags, new feature)
- MockParameterInput (testing, new capability)

Callers don't know about the event loop - they just call GetParameters() and get values back.

Benefits

Testability

• Core logic is pure functions - trivial to unit test
• Mock adapters eliminate need for actual gocui/fzf in tests
• Test coverage can be much higher than it is now

CLI-First Capability

# Interactive (current, backward compatible)
pet exec
 
# Direct execution (NEW)
pet exec -d "docker ps"
pet exec -d "docker run" --param container=nginx --param port=8080
pet exec -i "abc123" --use-defaults

Maintainability

• Clear separation of concerns
• Easy to add new adapters (REST API, HTTP server, whatever you can dream of!)
• Business logic changes don't affect UI and vice versa

Implementation Roadmap

We'll do a gradual migration (not a big-bang rewrite) to keep changes reviewable and maintain backward compatibility.

Phase 1: Foundation (v1.1.0)

Create domain/ package with core types and interfaces. No breaking changes.

Phase 2: Repository Pattern (v1.2.0)

Abstract storage behind SnippetRepository interface. Add tests.

Phase 3: Parameter Input Abstraction (v1.3.0)

Refactor gocui into GocuiParameterInput adapter. Remove global state. Add FlagParameterInput and MockParameterInput.

Phase 4: Selector Abstraction (v1.4.0)

Abstract fzf/peco behind Selector interface. Add DirectSelector for CLI mode.

Phase 5: Refactor Commands (v1.5.0)

Update all commands to use new architecture. Remove monolithic filter(). Add integration tests.

Phase 6: CLI-First Features (v1.6.0)

Add new flags: -d/--description, -i/--id, --param, --use-defaults, --json. Enable scripting!

Phase 7: Documentation & Polish (v2.0.0)

Complete ARCHITECTURE.md, update README, add examples, prepare release.

Timeline: 2-3 months for gradual migration
Breaking Changes: None until 2.0 (if needed)

Success Metrics

• Add coverage metrics (lol)
• Test coverage increases to ??%
• All commands testable without mocking I/O
• CLI-first usage works: pet exec -d "name" --param x=1 or whatever syntax
• No breaking changes to existing CUI workflows

[RamiAwar]

I am not proposing this because a lot of feature requests were placed. I'm proposing this because it's near impossible to write tests in the current state making maintenance a real pain and extension hard. Even with the help of AI I wasn't able to properly test what we have now.

I was inspired by NATS which have a CLI tool that's just a layer on top of core logic. That allows them to do everything via CLI, but also expose all those operations via other interfaces ex. REST. Powerful.

That being said, this will please quite a few users. Here are a few example feature requests blocked by the fact that we are not CLI-first:

1. Issue Feature Request: Allow pet new to accept arguments via flags or stdin (non-interactive mode) #352: Non-Interactive Snippet Creation

# Current (interactive only)
pet new
# ... prompted for description
# ... prompted for command
# ... prompted for tags

# Requested
pet new --command "ls -la" --tag "list" --description "List directory"

Issue #117: Pass Parameters as Arguments

# Snippet stored:
ffmpeg -i <input> -vf "fps=<fps=10>,scale=<scale-width=1080>:-1" <output>.gif

# Current (forced to use interactive parameter dialog)
pet exec
# ... select snippet from fzf
# ... gocui dialog pops up
# ... fill in each parameter manually

# What they want:
pet exec ffmpeg-to-gif ./video.mkv ./output 15 720
# Or with named parameters:
pet exec ffmpeg-to-gif --input ./video.mkv --output ./output --fps 15 --scale-width 720

3. Issue pet exec without additional search and enter #147 & [Feature Request] Enter first match with shortcut key #164: Execute First Match Automatically

# Current
pet exec -q "private"
# ... fzf shows matches
# ... must press ENTER to select
# ... then gocui dialog (if params)

# Requested
pet exec -q "private" --first-match --use-defaults
# Executes immediately, no interaction

4. Issue add support for pet search <search term> #180: Search with Direct Execution

# Current
pet search
# ... fzf for selection
# ... command printed to stdout
# ... must copy/paste to execute

# Requested
pet search "docker" --exec
# Automatically executes first match

pet search "docker" --list
# Lists all matches without fzf

5. Issue Option to output all metadata from search? #84: Structured Output for Automation

# Current
pet list
# Human-readable output only

# Requested
pet list --json
# Output:
# [
#   {"id": "abc123", "description": "docker ps", "command": "docker ps -a", "tags": ["docker"]},
#   ...
# ]

# Use case: Process with jq for automation
pet list --json | jq '.[] | select(.tags[] == "docker")' | jq -r '.command'