Metadata-Version: 2.4
Name: mango-tui
Version: 0.2.3
Summary: Keyboard-driven TUI for running multi-step shell command sequences defined in YAML
Author-email: Juan Pablo Leon <juanpabloleonmaya.dev@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/juanleon8581/mango-assistant
Project-URL: Repository, https://github.com/juanleon8581/mango-assistant
Project-URL: Issues, https://github.com/juanleon8581/mango-assistant/issues
Keywords: tui,terminal,cli,macros,shell,automation,textual
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.60.0
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

<div align="center">

# 🥭 mango

**A keyboard-driven TUI for running your shell command sequences — no more copy-pasting the same commands.**

[![PyPI version](https://img.shields.io/pypi/v/mango-tui)](https://pypi.org/project/mango-tui/)
[![Python versions](https://img.shields.io/pypi/pyversions/mango-tui)](https://pypi.org/project/mango-tui/)
[![License](https://img.shields.io/github/license/juanleon8581/mango-assistant)](LICENSE)

</div>

---

![mango TUI — main view](docs/screenshot-main.png)

---

## Install

```bash
pip install mango-tui
```

Requires Python 3.10+.

## Run

```bash
mango
```

That's it. On first run mango creates its config at `~/.config/mango/` and opens the TUI.

---

## How it works

mango lets you define **macros** — named sequences of shell commands — grouped by category. You pick one from the TUI and it runs, streaming output to the bottom panel in real time.

Macros that need input (a branch name, a service, a version tag) show a prompt dialog before running.

![mango TUI — param dialog](docs/screenshot-params.png)

---

## Keyboard reference

| Key | Action |
|---|---|
| `↑` / `↓` | Move through the list |
| `←` / `→` | Switch between category and macro panels |
| `Enter` | Run the selected macro |
| `Tab` / `Shift+Tab` | Cycle focus (categories → macros → shortcut bar) |
| `q` | Quit |

### Shortcut mode

Type `<category>><macro>` at any time to jump straight to a macro without using the menus:

```
g>su   →  git › switch-and-pull
g>cb   →  git › create-branch-push
d>up   →  docker › up
```

---

## Built-in macros

mango ships with a set of common macros ready to use:

### `g` — Git

| Shortcut | Description |
|---|---|
| `g>cb` | Create a new branch and push it to origin |
| `g>su` | Switch to a branch, fetch and pull |
| `g>db` | Delete branch locally and on remote, then prune |
| `g>nt` | Create a new tag and push it |
| `g>st` | Show git status |
| `g>lo` | Show the last 10 commits |

### `d` — Docker

| Shortcut | Description |
|---|---|
| `d>up` | `docker compose up -d` |
| `d>dn` | `docker compose down` |
| `d>lg` | Follow logs for a service |

### `m` — Mango

| Shortcut | Description |
|---|---|
| `m>up` | Upgrade mango to the latest version |

---

## Adding your own macros

Create `~/.config/mango/config.local.yaml`. Your macros are merged with the built-in defaults and survive package upgrades.

```yaml
categories:
  git:
    shortcut: "g"          # must match an existing category exactly to add macros into it
    macros:
      cleanup:
        shortcut: "cl"
        description: "Delete merged branches"
        steps:
          - git branch --merged | grep -v main | xargs git branch -d

  tools:                   # a new category — key and shortcut must not exist in the defaults
    shortcut: "t"
    macros:
      hello:
        shortcut: "hi"
        description: "Say hello"
        steps:
          - echo "hello world"
```

### Macros with parameters

Use `params` to collect input before the steps run. Reference each param in steps as `{name}`:

```yaml
categories:
  tools:
    shortcut: "t"
    macros:
      deploy:
        shortcut: "dp"
        description: "Deploy to an environment"
        params:
          - name: env
            prompt: "Environment (staging/prod)"
        steps:
          - ./deploy.sh {env}
          - echo "Deployed to {env}"
```

---

## Config files

mango manages three files under `~/.config/mango/` (respects `$XDG_CONFIG_HOME`):

| File | What it is |
|---|---|
| `config.default.yaml` | Built-in macros — overwritten on each update |
| `config.local.yaml` | **Your macros** — edit this one |
| `commands.yaml` | Merged result read by the app — do not edit |

### Merge rules

- To **add macros into an existing category**: use the same category key and shortcut as the default.
- To **add a new category**: both the key and shortcut must not conflict with any default.
- Within a shared category, each local macro key and shortcut must be unique.

Conflicts are skipped and reported before the TUI opens:

```
[mango] config conflict: macro 'git>status' — key already defined in default (skipped)
```

---

## YAML schema reference

```yaml
categories:
  <category-key>:
    shortcut: "g"            # unique globally; one or more chars
    macros:
      <macro-key>:
        shortcut: "su"       # unique within its category
        description: "..."
        params:              # optional
          - name: branch
            prompt: "Branch name"
        steps:               # run sequentially; first non-zero exit aborts
          - git checkout {branch}
          - git fetch
          - git pull
```
