shortcuts-tui 0.2.1

# Shortcuts TUI

A comprehensive terminal user interface (TUI) application for displaying and managing tools and shortcuts from configuration files.

[![Crates.io](https://img.shields.io/crates/v/shortcuts-tui.svg)](https://crates.io/crates/shortcuts-tui)
[![Documentation](https://docs.rs/shortcuts-tui/badge.svg)](https://docs.rs/shortcuts-tui)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)

## Features

- 🖥️ **Modern TUI Interface** - Built with [ratatui](https://github.com/ratatui-org/ratatui) for a responsive terminal experience
- 📁 **Multiple Configuration Formats** - Support for both TOML and JSON configuration files
- 🌐 **Cross-Platform Config Discovery** - Automatic configuration file discovery across Windows, macOS, Linux, and Android/Termux
- 🔧 **Environment Variable Support** - Use `SHORTCUTS_TUI_CONFIG` environment variable to specify config file location
- 🔍 **Powerful Search** - Search across tool names, descriptions, tags, and metadata
- 🏷️ **Flexible Organization** - Organize tools by categories and tags
- ⌨️ **Keyboard Shortcuts** - Define and display keyboard shortcuts for quick access
- 🚀 **Command Execution** - Execute tool commands directly from the interface
- ✅ **Configuration Validation** - Built-in validation with helpful error messages
- 📊 **Multiple Views** - Tools, categories, search, and help views
- 🎨 **Customizable** - Extensible design for easy customization

## Quick Start

### Installation

Install from crates.io:

```bash
cargo install shortcuts-tui
```

Or build from source:

```bash
git clone https://github.com/yourusername/shortcuts-and-tools
cd shortcuts-and-tools
cargo build --release
```

### Basic Usage

1. **Create a sample configuration:**
   ```bash
   shortcuts-tui init my-tools.toml
   ```

2. **Edit the configuration file** to add your tools and shortcuts

3. **Run the TUI application:**
   ```bash
   # Option 1: Specify config file directly
   shortcuts-tui --config my-tools.toml
   
   # Option 2: Use environment variable
   export SHORTCUTS_TUI_CONFIG="my-tools.toml"
   shortcuts-tui
   
   # Option 3: Place config in a standard location and let it auto-discover
   mkdir -p ~/.config/shortcuts-tui
   mv my-tools.toml ~/.config/shortcuts-tui/shortcuts.toml
   shortcuts-tui
   ```

### Command Line Interface

```
shortcuts-tui [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -c, --config <FILE>    Configuration file path (TOML or JSON)
    -v, --verbose          Increase logging verbosity
    -h, --help             Print help information
    -V, --version          Print version information

SUBCOMMANDS:
    init        Initialize a new configuration file
    validate    Validate a configuration file
    list        List tools from configuration
    help        Print this message or the help of the given subcommand(s)
```

## Configuration

### Configuration File Loading

Shortcuts TUI provides flexible configuration loading with multiple options:

#### 1. Environment Variable
Set the `SHORTCUTS_TUI_CONFIG` environment variable to specify a configuration file:

```bash
export SHORTCUTS_TUI_CONFIG="/path/to/my/config.toml"
shortcuts-tui  # Automatically uses the config from environment variable
```

#### 2. Command Line Argument
Specify a configuration file using the `--config` flag (overrides environment variable):

```bash
shortcuts-tui --config /path/to/my/config.toml
```

#### 3. Automatic Discovery
If no configuration is specified, shortcuts-tui searches in these locations (in order):

**On All Platforms:**
- Current directory (`.`)
- User config directory (varies by platform)

**Linux/Unix/macOS:**
- `/etc/shortcuts-tui/`
- `/usr/local/etc/shortcuts-tui/`  
- `$XDG_CONFIG_HOME/shortcuts-tui/` (if XDG_CONFIG_HOME is set)
- `$HOME/.config/shortcuts-tui/`
- `$HOME/.shortcuts-tui/`

**Windows:**
- `%PROGRAMDATA%\shortcuts-tui\`
- `%APPDATA%\shortcuts-tui\`
- `%LOCALAPPDATA%\shortcuts-tui\`

**Android/Termux:**
- `$PREFIX/etc/shortcuts-tui/` (usually `/data/data/com.termux/files/usr/etc/shortcuts-tui/`)
- `$HOME/.config/shortcuts-tui/`
- `$HOME/.shortcuts-tui/`

For each directory, it searches for files named:
- `shortcuts.toml`, `shortcuts.json`
- `config.toml`, `config.json`  
- `tools.toml`, `tools.json`

### Configuration Format

Shortcuts TUI supports both TOML and JSON configuration formats. The configuration consists of:

- **Metadata** - Information about your tool collection
- **Categories** - Optional groupings for your tools
- **Tools** - The actual tools and shortcuts

### TOML Example

```toml
[metadata]
title = "My Development Tools"
description = "A collection of useful development tools and shortcuts"
version = "1.0"
author = "Developer"

[[categories]]
id = "dev"
name = "Development"
description = "Software development tools"
icon = "💻"
color = "blue"

[[categories]]
id = "system"
name = "System"
description = "System administration tools"
icon = "⚙️"
color = "red"

[[tools]]
id = "git_status"
name = "Git Status"
description = "Check git repository status"
command = "git status"
shortcut = "Ctrl+G S"
category = "dev"
tags = ["git", "vcs"]
priority = 10
enabled = true

[tools.metadata]
documentation = "https://git-scm.com/docs/git-status"

[[tools]]
id = "disk_usage"
name = "Disk Usage"
description = "Check disk usage"
command = "df -h"
category = "system"
tags = ["disk", "monitoring"]
priority = 5
enabled = true
```

### JSON Example

```json
{
  "metadata": {
    "title": "My Development Tools",
    "description": "A collection of useful development tools and shortcuts",
    "version": "1.0",
    "author": "Developer"
  },
  "categories": [
    {
      "id": "dev",
      "name": "Development",
      "description": "Software development tools",
      "icon": "💻",
      "color": "blue"
    }
  ],
  "tools": [
    {
      "id": "git_status",
      "name": "Git Status",
      "description": "Check git repository status",
      "command": "git status",
      "shortcut": "Ctrl+G S",
      "category": "dev",
      "tags": ["git", "vcs"],
      "priority": 10,
      "enabled": true,
      "metadata": {
        "documentation": "https://git-scm.com/docs/git-status"
      }
    }
  ]
}
```

## TUI Interface

### Navigation

- **Arrow Keys / j,k** - Navigate up/down in lists
- **1-4** - Switch between views (Tools, Categories, Search, Help)
- **Tab** - Switch between panels
- **Enter** - Execute selected tool
- **Space** - Show tool details
- **/** - Start search
- **Esc** - Cancel search/close popup
- **q / Ctrl+C** - Quit application

### Views

1. **Tools View** - Main list of tools with details panel
2. **Categories View** - Browse tools by category
3. **Search View** - Search and filter tools
4. **Help View** - Keyboard shortcuts and help

## Configuration Schema

### Tool Properties

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | String | ✅ | Unique identifier |
| `name` | String | ✅ | Display name |
| `description` | String | ❌ | Tool description |
| `command` | String | ❌ | Command to execute |
| `shortcut` | String | ❌ | Keyboard shortcut |
| `category` | String | ❌ | Category ID |
| `tags` | Array | ❌ | Tags for searching |
| `metadata` | Object | ❌ | Custom key-value pairs |
| `enabled` | Boolean | ❌ | Whether tool is active (default: true) |
| `priority` | Integer | ❌ | Sort priority (default: 0) |

### Category Properties

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | String | ✅ | Unique identifier |
| `name` | String | ✅ | Display name |
| `description` | String | ❌ | Category description |
| `icon` | String | ❌ | Icon or emoji |
| `color` | String | ❌ | Color theme |

## Library Usage

Shortcuts TUI can also be used as a library in your Rust projects:

```rust
use shortcuts_tui::{
    config::{Config, Tool, Category, loader::ConfigLoader},
    ui::TuiApp,
    error::Result,
};

fn main() -> Result<()> {
    // Load configuration
    let loader = ConfigLoader::new();
    let config = loader.load_file("my-config.toml")?;

    // Create and run TUI
    let app = TuiApp::new(config)?;
    app.run()?;

    Ok(())
}
```

## Examples

The `examples/` directory contains several examples:

- `basic_usage.rs` - Creating configuration programmatically
- `config_loader.rs` - Different ways to load configurations

Run examples with:

```bash
cargo run --example basic_usage
cargo run --example config_loader
```

## Development

### Building

```bash
cargo build
```

### Testing

```bash
# Run unit tests
cargo test

# Run integration tests
cargo test --test integration_tests

# Run all tests with logging
RUST_LOG=debug cargo test

# Run expensive tests (large configurations)
cargo test --features expensive_tests
```

### Linting

```bash
cargo clippy
cargo fmt
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

### Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## License

This project is licensed under either of

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes in each version.

## Acknowledgments

- Built with [ratatui](https://github.com/ratatui-org/ratatui) for the terminal UI
- Uses [serde](https://serde.rs/) for configuration parsing
- Inspired by various terminal-based tool launchers and shortcuts managers