mango-tui 0.2.0__tar.gz

mango_tui-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Juan Pablo Leon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mango_tui-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: mango-tui
+Version: 0.2.0
+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
+
+# mango
+
+A keyboard-driven terminal UI for running multi-step shell command sequences defined in YAML.
+
+## What it does
+
+mango lets you define "macros" — named sequences of shell commands — grouped into categories. You run them by navigating the TUI or typing shortcut combos like `g>su` (category `g`, macro `su`). Macros can prompt for parameters before running.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+```bash
+mango
+```
+
+Navigate with arrow keys or `j`/`k`. Press `Enter` to run a macro. If the macro has params, a dialog prompts for them before execution. Output streams to a panel at the bottom. Press `q` to quit.
+
+**Shortcut mode:** type `<category_shortcut>><macro_shortcut>` (e.g. `g>su`) to jump directly to a macro from anywhere in the TUI.
+
+## Config
+
+mango manages three files under `~/.config/mango/` (respects `$XDG_CONFIG_HOME`):
+
+| File | Purpose |
+|---|---|
+| `config.default.yaml` | Macros bundled with the package — updated automatically on each startup |
+| `config.local.yaml` | Your personal macros — optional, persists across package updates |
+| `commands.yaml` | Merge output read by the app — **do not edit manually** |
+
+On each startup mango propagates the built-in defaults and merges them with your local config into `commands.yaml`. The merge is lazy: it only runs when either source file changes.
+
+### Adding your own macros
+
+Create `~/.config/mango/config.local.yaml` with the same YAML schema:
+
+```yaml
+categories:
+  git:
+    shortcut: "g"          # must match the default exactly to add macros into it
+    macros:
+      my-cleanup:
+        shortcut: "cl"
+        description: "Delete merged branches"
+        steps:
+          - git branch --merged | grep -v main | xargs git branch -d
+  my-tools:                # entirely new category — key and shortcut must not exist in defaults
+    shortcut: "t"
+    macros:
+      hello:
+        shortcut: "hi"
+        description: "Say hello"
+        steps:
+          - echo "hello"
+```
+
+**Merge rules:**
+
+- To add macros into an existing default category: the category `key` and `shortcut` must match the default exactly.
+- To add a new category: both the `key` and `shortcut` must not exist in the defaults.
+- Within a shared category, each local macro must have a `key` and `shortcut` not already used by the defaults.
+
+Conflicts are skipped and reported to stderr before the TUI opens:
+
+```
+[mango] config conflict: category 'tools' — shortcut 'g' already used by 'git' (skipped)
+[mango] config conflict: macro 'git>status' — key already defined in default (skipped)
+```
+
+### Schema reference
+
+```yaml
+categories:
+  git:
+    shortcut: "g"
+    macros:
+      switch-and-pull:
+        shortcut: "su"
+        description: "Switch branch, fetch and pull"
+        params:
+          - name: branch
+            prompt: "Branch name"
+        steps:
+          - git checkout {branch}
+          - git fetch
+          - git pull
+      status:
+        shortcut: "st"
+        description: "Show git status"
+        steps:
+          - git status
+```
+
+- `shortcut` — unique within its scope (category shortcuts must be globally unique; macro shortcuts must be unique within their category)
+- `params` — optional list of `{name, prompt}` pairs; referenced in steps as `{name}`
+- `steps` — shell commands run sequentially; first non-zero exit code aborts the sequence
+
+## Development
+
+```bash
+# Test with a local config instead of ~/.config/mango/
+XDG_CONFIG_HOME=.test-config mango
+```
+
+Dependencies: [`textual`](https://github.com/Textualize/textual), [`pyyaml`](https://pyyaml.org/)

mango_tui-0.2.0/README.md

@@ -0,0 +1,115 @@
+# mango
+
+A keyboard-driven terminal UI for running multi-step shell command sequences defined in YAML.
+
+## What it does
+
+mango lets you define "macros" — named sequences of shell commands — grouped into categories. You run them by navigating the TUI or typing shortcut combos like `g>su` (category `g`, macro `su`). Macros can prompt for parameters before running.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+```bash
+mango
+```
+
+Navigate with arrow keys or `j`/`k`. Press `Enter` to run a macro. If the macro has params, a dialog prompts for them before execution. Output streams to a panel at the bottom. Press `q` to quit.
+
+**Shortcut mode:** type `<category_shortcut>><macro_shortcut>` (e.g. `g>su`) to jump directly to a macro from anywhere in the TUI.
+
+## Config
+
+mango manages three files under `~/.config/mango/` (respects `$XDG_CONFIG_HOME`):
+
+| File | Purpose |
+|---|---|
+| `config.default.yaml` | Macros bundled with the package — updated automatically on each startup |
+| `config.local.yaml` | Your personal macros — optional, persists across package updates |
+| `commands.yaml` | Merge output read by the app — **do not edit manually** |
+
+On each startup mango propagates the built-in defaults and merges them with your local config into `commands.yaml`. The merge is lazy: it only runs when either source file changes.
+
+### Adding your own macros
+
+Create `~/.config/mango/config.local.yaml` with the same YAML schema:
+
+```yaml
+categories:
+  git:
+    shortcut: "g"          # must match the default exactly to add macros into it
+    macros:
+      my-cleanup:
+        shortcut: "cl"
+        description: "Delete merged branches"
+        steps:
+          - git branch --merged | grep -v main | xargs git branch -d
+  my-tools:                # entirely new category — key and shortcut must not exist in defaults
+    shortcut: "t"
+    macros:
+      hello:
+        shortcut: "hi"
+        description: "Say hello"
+        steps:
+          - echo "hello"
+```
+
+**Merge rules:**
+
+- To add macros into an existing default category: the category `key` and `shortcut` must match the default exactly.
+- To add a new category: both the `key` and `shortcut` must not exist in the defaults.
+- Within a shared category, each local macro must have a `key` and `shortcut` not already used by the defaults.
+
+Conflicts are skipped and reported to stderr before the TUI opens:
+
+```
+[mango] config conflict: category 'tools' — shortcut 'g' already used by 'git' (skipped)
+[mango] config conflict: macro 'git>status' — key already defined in default (skipped)
+```
+
+### Schema reference
+
+```yaml
+categories:
+  git:
+    shortcut: "g"
+    macros:
+      switch-and-pull:
+        shortcut: "su"
+        description: "Switch branch, fetch and pull"
+        params:
+          - name: branch
+            prompt: "Branch name"
+        steps:
+          - git checkout {branch}
+          - git fetch
+          - git pull
+      status:
+        shortcut: "st"
+        description: "Show git status"
+        steps:
+          - git status
+```
+
+- `shortcut` — unique within its scope (category shortcuts must be globally unique; macro shortcuts must be unique within their category)
+- `params` — optional list of `{name, prompt}` pairs; referenced in steps as `{name}`
+- `steps` — shell commands run sequentially; first non-zero exit code aborts the sequence
+
+## Development
+
+```bash
+# Test with a local config instead of ~/.config/mango/
+XDG_CONFIG_HOME=.test-config mango
+```
+
+Dependencies: [`textual`](https://github.com/Textualize/textual), [`pyyaml`](https://pyyaml.org/)

mango_tui-0.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mango-tui"
+version = "0.2.0"
+description = "Keyboard-driven TUI for running multi-step shell command sequences defined in YAML"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+    { name = "Juan Pablo Leon", email = "juanpabloleonmaya.dev@gmail.com" },
+]
+keywords = ["tui", "terminal", "cli", "macros", "shell", "automation", "textual"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Terminals",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "textual>=0.60.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/juanleon8581/mango-assistant"
+Repository = "https://github.com/juanleon8581/mango-assistant"
+Issues = "https://github.com/juanleon8581/mango-assistant/issues"
+
+[project.scripts]
+mango = "mango.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mango = ["*.yaml"]

mango_tui-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mango_tui-0.2.0/src/mango/config.default.yaml

@@ -0,0 +1,81 @@
+categories:
+  git:
+    shortcut: "g"
+    macros:
+      create-branch-push:
+        shortcut: "cb"
+        description: "Create a new branch and push it to origin"
+        params:
+          - name: branch
+            prompt: "Branch name"
+        steps:
+          - git checkout -b {branch}
+          - git push -u origin {branch}
+      new-tag-and-push:
+        shortcut: "nt"
+        description: "Create a new tag and push it to origin"
+        params:
+          - name: tag
+            prompt: "Tag name"
+        steps:
+          - git tag {tag}
+          - git push --tags
+      switch-and-pull:
+        shortcut: "su"
+        description: "Switch branch, fetch and pull"
+        params:
+          - name: branch
+            prompt: "Branch name"
+        steps:
+          - git checkout {branch}
+          - git fetch
+          - git pull
+      delete-branch-local-remote-and-prune:
+        shortcut: "db"
+        description: "Delete branch in local and remote, and prune"
+        params:
+          - name: branch
+            prompt: "Branch name"
+        steps:
+          - git push origin --delete {branch}
+          - git branch -D {branch}
+          - git fetch --prune
+      status:
+        shortcut: "st"
+        description: "Show git status"
+        steps:
+          - git status
+      log:
+        shortcut: "lo"
+        description: "Show recent commits"
+        steps:
+          - git log --oneline -10
+  docker:
+    shortcut: "d"
+    macros:
+      up:
+        shortcut: "up"
+        description: "Start containers"
+        steps:
+          - docker compose up -d
+      down:
+        shortcut: "dn"
+        description: "Stop containers"
+        steps:
+          - docker compose down
+      logs:
+        shortcut: "lg"
+        description: "Follow logs for a service"
+        params:
+          - name: service
+            prompt: "Service name"
+        steps:
+          - docker compose logs -f {service}
+  mango:
+    shortcut: "m"
+    macros:
+      upgrade-mango:
+        shortcut: "up"
+        description: "Upgrade mango"
+        steps:
+          - pip install --force-reinstall --no-cache-dir git+https://github.com/juanleon8581/mango-assistant.git

mango_tui-0.2.0/src/mango/config.py

@@ -0,0 +1,128 @@
+from dataclasses import dataclass, field
+from importlib.resources import files
+from pathlib import Path
+import hashlib
+import os
+import yaml
+
+
+@dataclass
+class Param:
+    name: str
+    prompt: str
+
+
+@dataclass
+class Macro:
+    shortcut: str
+    description: str
+    steps: list[str]
+    params: list[Param] = field(default_factory=list)
+
+
+@dataclass
+class Category:
+    name: str
+    shortcut: str
+    macros: dict[str, Macro]
+
+
+@dataclass
+class Config:
+    categories: dict[str, Category]
+
+
+
+def _file_sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def get_config_path() -> Path:
+    xdg_config = os.environ.get("XDG_CONFIG_HOME", "")
+    base = Path(xdg_config) if xdg_config else Path.home() / ".config"
+    return base / "mango" / "commands.yaml"
+
+
+def ensure_config(config_dir: Path) -> None:
+    config_dir.mkdir(parents=True, exist_ok=True)
+    resource = files("mango").joinpath("config.default.yaml")
+    content = resource.read_bytes()
+    resource_hash = hashlib.sha256(content).hexdigest()
+    dest = config_dir / "config.default.yaml"
+    if not dest.exists() or _file_sha256(dest) != resource_hash:
+        dest.write_bytes(content)
+
+
+def _parse_param(data: object, macro_name: str, idx: int) -> Param:
+    if not isinstance(data, dict):
+        raise ValueError(f"Macro '{macro_name}': param[{idx}] must be a mapping")
+    name = data.get("name")
+    prompt = data.get("prompt")
+    if not name:
+        raise ValueError(f"Macro '{macro_name}': param[{idx}] missing 'name'")
+    if not prompt:
+        raise ValueError(f"Macro '{macro_name}': param[{idx}] missing 'prompt'")
+    return Param(name=str(name), prompt=str(prompt))
+
+
+def _parse_macro(data: object, macro_key: str, cat_name: str) -> Macro:
+    if not isinstance(data, dict):
+        raise ValueError(f"Category '{cat_name}': macro '{macro_key}' must be a mapping")
+    shortcut = data.get("shortcut")
+    description = data.get("description")
+    steps = data.get("steps")
+    if not shortcut:
+        raise ValueError(f"'{cat_name}.{macro_key}': missing 'shortcut'")
+    if not description:
+        raise ValueError(f"'{cat_name}.{macro_key}': missing 'description'")
+    if not steps or not isinstance(steps, list):
+        raise ValueError(f"'{cat_name}.{macro_key}': missing or empty 'steps'")
+    params = [_parse_param(p, macro_key, i) for i, p in enumerate(data.get("params") or [])]
+    return Macro(
+        shortcut=str(shortcut),
+        description=str(description),
+        steps=[str(s) for s in steps],
+        params=params,
+    )
+
+
+def _parse_category(data: object, cat_key: str) -> Category:
+    if not isinstance(data, dict):
+        raise ValueError(f"Category '{cat_key}' must be a mapping")
+    shortcut = data.get("shortcut")
+    macros_raw = data.get("macros") or {}
+    if not shortcut:
+        raise ValueError(f"Category '{cat_key}': missing 'shortcut'")
+    if not isinstance(macros_raw, dict):
+        raise ValueError(f"Category '{cat_key}': 'macros' must be a mapping")
+    macros: dict[str, Macro] = {}
+    seen_shortcuts: set[str] = set()
+    for mk, mv in macros_raw.items():
+        macro = _parse_macro(mv, mk, cat_key)
+        if macro.shortcut in seen_shortcuts:
+            raise ValueError(f"Category '{cat_key}': duplicate macro shortcut '{macro.shortcut}'")
+        seen_shortcuts.add(macro.shortcut)
+        macros[mk] = macro
+    return Category(name=cat_key, shortcut=str(shortcut), macros=macros)
+
+
+def load_config(path: Path) -> Config:
+    raw = yaml.safe_load(path.read_text())
+    if not isinstance(raw, dict) or "categories" not in raw:
+        raise ValueError("Config must have a top-level 'categories' key")
+    cats_raw = raw["categories"]
+    if not isinstance(cats_raw, dict):
+        raise ValueError("'categories' must be a mapping")
+    categories: dict[str, Category] = {}
+    seen_shortcuts: set[str] = set()
+    for ck, cv in cats_raw.items():
+        cat = _parse_category(cv, ck)
+        if cat.shortcut in seen_shortcuts:
+            raise ValueError(f"Duplicate category shortcut '{cat.shortcut}'")
+        seen_shortcuts.add(cat.shortcut)
+        categories[ck] = cat
+    return Config(categories=categories)
+
+
+def interpolate(template: str, params: dict[str, str]) -> str:
+    return template.format_map(params)

mango_tui-0.2.0/src/mango/main.py

@@ -0,0 +1,23 @@
+import sys
+from pathlib import Path
+
+from .config import ensure_config, get_config_path, load_config
+from .merger import merge_configs
+
+
+def main() -> None:
+    config_path = get_config_path()
+    config_dir = config_path.parent
+    try:
+        ensure_config(config_dir)
+        merge_configs(config_dir)
+        config = load_config(config_path)
+    except Exception as exc:
+        print(f"mango: config error — {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    from .tui.app import MangoApp
+
+    cwd = str(Path.cwd())
+    app = MangoApp(config=config, cwd=cwd)
+    app.run()

mango_tui-0.2.0/src/mango/merger.py

@@ -0,0 +1,113 @@
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+_MERGE_STATE_FILE = ".merge-state.json"
+
+
+def _load_merge_state(config_dir: Path) -> dict:
+    state_path = config_dir / _MERGE_STATE_FILE
+    if not state_path.exists():
+        return {}
+    return json.loads(state_path.read_text())
+
+
+def _save_merge_state(config_dir: Path, default_hash: str, local_hash: str | None) -> None:
+    state_path = config_dir / _MERGE_STATE_FILE
+    state_path.write_text(json.dumps({"default_hash": default_hash, "local_hash": local_hash}))
+
+
+def _sha256_file(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def should_merge(config_dir: Path) -> bool:
+    default_path = config_dir / "config.default.yaml"
+    local_path = config_dir / "config.local.yaml"
+
+    state = _load_merge_state(config_dir)
+    if not state:
+        return True
+
+    if _sha256_file(default_path) != state.get("default_hash"):
+        return True
+
+    current_local_hash = _sha256_file(local_path) if local_path.exists() else None
+    return current_local_hash != state.get("local_hash")
+
+
+def merge_configs(config_dir: Path) -> list[str]:
+    default_path = config_dir / "config.default.yaml"
+    local_path = config_dir / "config.local.yaml"
+    commands_path = config_dir / "commands.yaml"
+
+    if not should_merge(config_dir):
+        return []
+
+    warnings: list[str] = []
+
+    default_raw = yaml.safe_load(default_path.read_text())
+    default_cats: dict = (default_raw or {}).get("categories", {})
+
+    merged_cats: dict = {}
+    for key, data in default_cats.items():
+        merged_cats[key] = {"shortcut": data["shortcut"], "macros": dict(data.get("macros") or {})}
+
+    if local_path.exists():
+        local_raw = yaml.safe_load(local_path.read_text())
+        local_cats: dict = (local_raw or {}).get("categories", {})
+
+        default_shortcuts: set[str] = {str(v["shortcut"]) for v in default_cats.values()}
+
+        for local_key, local_data in local_cats.items():
+            local_shortcut = str(local_data.get("shortcut", ""))
+
+            if local_key in default_cats:
+                default_shortcut = str(default_cats[local_key].get("shortcut", ""))
+                if local_shortcut == default_shortcut:
+                    # Exact match — merge macros
+                    default_macros: dict = merged_cats[local_key]["macros"]
+                    default_macro_shortcuts = {str(m.get("shortcut", "")) for m in default_macros.values()}
+                    for macro_key, macro_data in (local_data.get("macros") or {}).items():
+                        macro_shortcut = str(macro_data.get("shortcut", ""))
+                        if macro_key in default_macros:
+                            warnings.append(
+                                f"[mango] config conflict: macro '{local_key}>{macro_key}' — "
+                                f"key already exists in default (skipped)"
+                            )
+                        elif macro_shortcut in default_macro_shortcuts:
+                            warnings.append(
+                                f"[mango] config conflict: macro '{local_key}>{macro_key}' — "
+                                f"shortcut '{macro_shortcut}' already used by a default macro (skipped)"
+                            )
+                        else:
+                            merged_cats[local_key]["macros"][macro_key] = macro_data
+                else:
+                    warnings.append(
+                        f"[mango] config conflict: category '{local_key}' — "
+                        f"shortcut '{local_shortcut}' conflicts with default shortcut '{default_shortcut}' (skipped)"
+                    )
+            elif local_shortcut in default_shortcuts:
+                conflicting_key = next(k for k, v in default_cats.items() if str(v["shortcut"]) == local_shortcut)
+                warnings.append(
+                    f"[mango] config conflict: category '{local_key}' — "
+                    f"shortcut '{local_shortcut}' already used by '{conflicting_key}' (skipped)"
+                )
+            else:
+                merged_cats[local_key] = local_data
+
+    commands_path.write_text(
+        yaml.dump({"categories": merged_cats}, default_flow_style=False, allow_unicode=True, sort_keys=False)
+    )
+
+    default_hash = _sha256_file(default_path)
+    local_hash = _sha256_file(local_path) if local_path.exists() else None
+    _save_merge_state(config_dir, default_hash, local_hash)
+
+    for warning in warnings:
+        print(warning, file=sys.stderr)
+
+    return warnings

mango_tui-0.2.0/src/mango/runner.py

@@ -0,0 +1,51 @@
+import re
+import subprocess
+from typing import Callable
+
+from .config import Macro, interpolate
+
+
+def _validate_steps(macro: Macro, params: dict[str, str]) -> None:
+    param_names = set(params.keys())
+    for step in macro.steps:
+        for match in re.finditer(r"\{(\w+)\}", step):
+            name = match.group(1)
+            if name not in param_names:
+                raise ValueError(
+                    f"Step '{step}' references undefined param '{name}'"
+                )
+
+
+def run_step(command: str, cwd: str, on_output: Callable[[str], None]) -> int:
+    proc = subprocess.Popen(
+        command,
+        shell=True,
+        cwd=cwd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        stdin=subprocess.DEVNULL,
+        text=True,
+        bufsize=1,
+    )
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        on_output(line.rstrip())
+    proc.wait()
+    return proc.returncode
+
+
+def run_macro(
+    macro: Macro,
+    params: dict[str, str],
+    cwd: str,
+    on_output: Callable[[str], None],
+) -> tuple[bool, int | None, str | None]:
+    _validate_steps(macro, params)
+    total = len(macro.steps)
+    for i, step_template in enumerate(macro.steps, 1):
+        cmd = interpolate(step_template, params)
+        on_output(f"[bold cyan][step {i}/{total}][/] $ {cmd}")
+        rc = run_step(cmd, cwd, on_output)
+        if rc != 0:
+            return False, rc, cmd
+    return True, None, None

mango_tui-0.2.0/src/mango/tui/app.py

@@ -0,0 +1,368 @@
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.screen import ModalScreen, Screen
+from textual.widgets import Input, Label, ListItem, ListView, RichLog, Static
+
+from ..config import Category, Config, Macro, Param
+
+
+# ── Custom ListItem subclasses ────────────────────────────────────────────────
+
+
+class CategoryItem(ListItem):
+    def __init__(self, category: Category) -> None:
+        super().__init__(Label(f"\\[{category.shortcut}]  {category.name}"))
+        self.category = category
+
+
+class MacroItem(ListItem):
+    def __init__(self, macro: Macro) -> None:
+        params_hint = (
+            " " + " ".join(f"<{p.name}>" for p in macro.params) if macro.params else ""
+        )
+        super().__init__(Label(f"\\[{macro.shortcut}]  {macro.description}{params_hint}"))
+        self.macro = macro
+
+
+# ── Parameter input dialog ────────────────────────────────────────────────────
+
+
+class ParamDialog(ModalScreen[dict[str, str] | None]):
+    DEFAULT_CSS = """
+    ParamDialog {
+        align: center middle;
+    }
+    #dialog {
+        background: $surface;
+        border: solid $primary;
+        width: 60;
+        height: auto;
+        padding: 1 2;
+    }
+    #dialog-title {
+        text-style: bold;
+        padding-bottom: 1;
+        color: $text;
+    }
+    #param-label {
+        color: $text-muted;
+        padding-bottom: 1;
+    }
+    """
+
+    BINDINGS = [Binding("escape", "cancel", "Cancel")]
+
+    def __init__(self, params: list[Param]) -> None:
+        super().__init__()
+        self._params = params
+        self._values: dict[str, str] = {}
+        self._idx = 0
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="dialog"):
+            yield Label("Parameters", id="dialog-title")
+            yield Label(self._params[0].prompt if self._params else "", id="param-label")
+            yield Input(
+                placeholder=self._params[0].prompt if self._params else "",
+                id="param-input",
+            )
+
+    def on_mount(self) -> None:
+        self.query_one("#param-input", Input).focus()
+
+    @on(Input.Submitted, "#param-input")
+    def _on_submitted(self, event: Input.Submitted) -> None:
+        param = self._params[self._idx]
+        self._values[param.name] = event.value
+        self._idx += 1
+        if self._idx >= len(self._params):
+            self.dismiss(self._values)
+            return
+        next_param = self._params[self._idx]
+        self.query_one("#param-label", Label).update(next_param.prompt)
+        inp = self.query_one("#param-input", Input)
+        inp.value = ""
+        inp.focus()
+
+    def action_cancel(self) -> None:
+        self.dismiss(None)
+
+
+# ── Main screen ───────────────────────────────────────────────────────────────
+
+
+class MainScreen(Screen):
+    DEFAULT_CSS = """
+    MainScreen {
+        layout: vertical;
+    }
+    #panels {
+        layout: horizontal;
+        height: 2fr;
+    }
+    #category-panel {
+        width: 1fr;
+        border: solid $primary;
+    }
+    #category-panel > Label {
+        background: $primary;
+        color: $text;
+        text-align: center;
+        height: 1;
+        width: 1fr;
+    }
+    #macro-panel {
+        width: 3fr;
+        border: solid $accent;
+    }
+    #macro-panel > Label {
+        background: $accent;
+        color: $text;
+        text-align: center;
+        height: 1;
+        width: 1fr;
+    }
+    #output-log {
+        height: 1fr;
+        border: solid $warning;
+        display: none;
+    }
+    #footer {
+        dock: bottom;
+        height: 4;
+        layout: vertical;
+        border-top: solid $primary;
+    }
+    #shortcut-row {
+        height: 3;
+        layout: horizontal;
+        align: left middle;
+    }
+    #shortcut-label {
+        width: auto;
+        padding: 0 1;
+        color: $text-muted;
+        content-align: center middle;
+    }
+    #shortcut-input {
+        width: 1fr;
+        border: none;
+    }
+    #status-bar {
+        height: 1;
+        padding: 0 1;
+        color: $text-muted;
+    }
+    """
+
+    BINDINGS = [
+        Binding("q", "quit_app", "Quit", show=True),
+        Binding("escape", "quit_app", "Quit", show=False),
+        Binding("tab", "focus_next", "Next panel", show=True),
+        Binding("shift+tab", "focus_previous", "Prev panel", show=False),
+    ]
+
+    def __init__(self, config: Config, cwd: str) -> None:
+        super().__init__()
+        self._config = config
+        self._cwd = cwd
+        self._categories = list(config.categories.values())
+        self._selected_cat_idx = 0
+
+    def compose(self) -> ComposeResult:
+        with Horizontal(id="panels"):
+            with Vertical(id="category-panel"):
+                yield Label(" Categories ")
+                yield ListView(id="category-list")
+            with Vertical(id="macro-panel"):
+                yield Label(" Macros ")
+                yield ListView(id="macro-list")
+        yield RichLog(id="output-log", highlight=True, markup=True)
+        with Vertical(id="footer"):
+            with Horizontal(id="shortcut-row"):
+                yield Static("shortcut> ", id="shortcut-label")
+                yield Input(placeholder="g>su", id="shortcut-input")
+            yield Label("", id="status-bar")
+
+    def on_mount(self) -> None:
+        cat_list = self.query_one("#category-list", ListView)
+        for cat in self._categories:
+            cat_list.append(CategoryItem(cat))
+        if self._categories:
+            self._populate_macros(self._categories[0])
+        cat_list.focus()
+
+    # ── Category navigation ───────────────────────────────────────────────────
+
+    @on(ListView.Highlighted, "#category-list")
+    def _on_category_highlighted(self, event: ListView.Highlighted) -> None:
+        if isinstance(event.item, CategoryItem):
+            self._populate_macros(event.item.category)
+
+    @on(ListView.Selected, "#category-list")
+    def _on_category_selected(self, event: ListView.Selected) -> None:
+        self.query_one("#macro-list", ListView).focus()
+
+    def _populate_macros(self, cat: Category) -> None:
+        macro_list = self.query_one("#macro-list", ListView)
+        macro_list.clear()
+        for macro in cat.macros.values():
+            macro_list.append(MacroItem(macro))
+
+    # ── Macro execution via list selection ────────────────────────────────────
+
+    @on(ListView.Selected, "#macro-list")
+    def _on_macro_selected(self, event: ListView.Selected) -> None:
+        if isinstance(event.item, MacroItem):
+            self._trigger_macro(event.item.macro)
+
+    # ── Shortcut bar ──────────────────────────────────────────────────────────
+
+    @on(Input.Submitted, "#shortcut-input")
+    def _on_shortcut_submitted(self, event: Input.Submitted) -> None:
+        shortcut = event.value.strip()
+        self.query_one("#shortcut-input", Input).value = ""
+        if not shortcut:
+            return
+        self._dispatch_shortcut(shortcut)
+
+    def _dispatch_shortcut(self, shortcut: str) -> None:
+        parts = shortcut.split(">", 1)
+        if len(parts) != 2:
+            self._set_status(
+                f"[red]Invalid format: '{shortcut}'. Use cat>mac (e.g. g>su)[/]"
+            )
+            return
+        cat_sc, macro_sc = parts[0].strip(), parts[1].strip()
+        cat = next((c for c in self._categories if c.shortcut == cat_sc), None)
+        if cat is None:
+            self._set_status(f"[red]Unknown category shortcut: '{cat_sc}'[/]")
+            return
+        macro = next((m for m in cat.macros.values() if m.shortcut == macro_sc), None)
+        if macro is None:
+            self._set_status(
+                f"[red]Unknown macro shortcut: '{macro_sc}' in '{cat.name}'[/]"
+            )
+            return
+        self._trigger_macro(macro)
+
+    # ── Macro trigger + param dialog ─────────────────────────────────────────
+
+    def _trigger_macro(self, macro: Macro) -> None:
+        self._set_status(f"Selected: {macro.description}")
+        if macro.params:
+            self.app.push_screen(
+                ParamDialog(macro.params),
+                callback=lambda values: (
+                    self._execute_macro(macro, values)
+                    if values is not None
+                    else self._set_status("Cancelled")
+                ),
+            )
+        else:
+            self._execute_macro(macro, {})
+
+    # ── Execution ─────────────────────────────────────────────────────────────
+
+    def _execute_macro(self, macro: Macro, params: dict[str, str]) -> None:
+        output_log = self.query_one("#output-log", RichLog)
+        output_log.clear()
+        output_log.display = True
+        self._set_status(f"Running: {macro.description}…")
+        self._run_worker(macro, params, output_log)
+
+    @work(thread=True)
+    def _run_worker(
+        self, macro: Macro, params: dict[str, str], output_log: RichLog
+    ) -> None:
+        from ..runner import run_macro
+
+        def on_output(line: str) -> None:
+            self.app.call_from_thread(output_log.write, line)
+
+        try:
+            success, exit_code, failed_step = run_macro(macro, params, self._cwd, on_output)
+        except ValueError as exc:
+            self.app.call_from_thread(self._on_config_error, str(exc))
+            return
+
+        if success:
+            self.app.call_from_thread(self._on_success, macro, output_log)
+        else:
+            self.app.call_from_thread(
+                self._on_failure, failed_step or "", exit_code or 1, output_log
+            )
+
+    def _on_success(self, macro: Macro, output_log: RichLog) -> None:
+        output_log.write(f"\n[bold green]✓ '{macro.description}' completed[/]")
+        self._set_status(f"[green]✓ Done: {macro.description}[/]")
+
+    def _on_failure(self, step: str, exit_code: int, output_log: RichLog) -> None:
+        output_log.write(
+            f"\n[bold red]✗ Step failed (exit code {exit_code}):[/] {step}"
+        )
+        self._set_status(f"[red]✗ Failed (exit {exit_code}): {step}[/]")
+
+    def _on_config_error(self, message: str) -> None:
+        self._set_status(f"[red]Config error: {message}[/]")
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    def _set_status(self, message: str) -> None:
+        self.query_one("#status-bar", Label).update(message)
+
+    _FOCUS_CYCLE = ["#category-list", "#macro-list", "#shortcut-input"]
+
+    def action_focus_next(self) -> None:
+        focused_id = self.focused.id if self.focused else None
+        ids = self._FOCUS_CYCLE
+        try:
+            idx = ids.index(f"#{focused_id}")
+        except ValueError:
+            idx = -1
+        self.query_one(ids[(idx + 1) % len(ids)]).focus()
+
+    def action_focus_previous(self) -> None:
+        focused_id = self.focused.id if self.focused else None
+        ids = self._FOCUS_CYCLE
+        try:
+            idx = ids.index(f"#{focused_id}")
+        except ValueError:
+            idx = 0
+        self.query_one(ids[(idx - 1) % len(ids)]).focus()
+
+    def action_quit_app(self) -> None:
+        if isinstance(self.focused, Input):
+            return
+        self.app.exit()
+
+    def on_key(self, event) -> None:
+        if isinstance(self.focused, Input):
+            return
+        if event.key == "q":
+            event.stop()
+            self.app.exit()
+        elif event.key == "right" and self.focused and self.focused.id == "category-list":
+            event.stop()
+            self.query_one("#macro-list", ListView).focus()
+        elif event.key == "left" and self.focused and self.focused.id == "macro-list":
+            event.stop()
+            self.query_one("#category-list", ListView).focus()
+
+
+# ── App ───────────────────────────────────────────────────────────────────────
+
+
+class MangoApp(App):
+    TITLE = "mango"
+    SUB_TITLE = "macro runner"
+
+    def __init__(self, config: Config, cwd: str) -> None:
+        super().__init__()
+        self._config = config
+        self._cwd = cwd
+
+    def on_mount(self) -> None:
+        self.push_screen(MainScreen(config=self._config, cwd=self._cwd))

mango_tui-0.2.0/src/mango_tui.egg-info/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: mango-tui
+Version: 0.2.0
+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
+
+# mango
+
+A keyboard-driven terminal UI for running multi-step shell command sequences defined in YAML.
+
+## What it does
+
+mango lets you define "macros" — named sequences of shell commands — grouped into categories. You run them by navigating the TUI or typing shortcut combos like `g>su` (category `g`, macro `su`). Macros can prompt for parameters before running.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+```bash
+mango
+```
+
+Navigate with arrow keys or `j`/`k`. Press `Enter` to run a macro. If the macro has params, a dialog prompts for them before execution. Output streams to a panel at the bottom. Press `q` to quit.
+
+**Shortcut mode:** type `<category_shortcut>><macro_shortcut>` (e.g. `g>su`) to jump directly to a macro from anywhere in the TUI.
+
+## Config
+
+mango manages three files under `~/.config/mango/` (respects `$XDG_CONFIG_HOME`):
+
+| File | Purpose |
+|---|---|
+| `config.default.yaml` | Macros bundled with the package — updated automatically on each startup |
+| `config.local.yaml` | Your personal macros — optional, persists across package updates |
+| `commands.yaml` | Merge output read by the app — **do not edit manually** |
+
+On each startup mango propagates the built-in defaults and merges them with your local config into `commands.yaml`. The merge is lazy: it only runs when either source file changes.
+
+### Adding your own macros
+
+Create `~/.config/mango/config.local.yaml` with the same YAML schema:
+
+```yaml
+categories:
+  git:
+    shortcut: "g"          # must match the default exactly to add macros into it
+    macros:
+      my-cleanup:
+        shortcut: "cl"
+        description: "Delete merged branches"
+        steps:
+          - git branch --merged | grep -v main | xargs git branch -d
+  my-tools:                # entirely new category — key and shortcut must not exist in defaults
+    shortcut: "t"
+    macros:
+      hello:
+        shortcut: "hi"
+        description: "Say hello"
+        steps:
+          - echo "hello"
+```
+
+**Merge rules:**
+
+- To add macros into an existing default category: the category `key` and `shortcut` must match the default exactly.
+- To add a new category: both the `key` and `shortcut` must not exist in the defaults.
+- Within a shared category, each local macro must have a `key` and `shortcut` not already used by the defaults.
+
+Conflicts are skipped and reported to stderr before the TUI opens:
+
+```
+[mango] config conflict: category 'tools' — shortcut 'g' already used by 'git' (skipped)
+[mango] config conflict: macro 'git>status' — key already defined in default (skipped)
+```
+
+### Schema reference
+
+```yaml
+categories:
+  git:
+    shortcut: "g"
+    macros:
+      switch-and-pull:
+        shortcut: "su"
+        description: "Switch branch, fetch and pull"
+        params:
+          - name: branch
+            prompt: "Branch name"
+        steps:
+          - git checkout {branch}
+          - git fetch
+          - git pull
+      status:
+        shortcut: "st"
+        description: "Show git status"
+        steps:
+          - git status
+```
+
+- `shortcut` — unique within its scope (category shortcuts must be globally unique; macro shortcuts must be unique within their category)
+- `params` — optional list of `{name, prompt}` pairs; referenced in steps as `{name}`
+- `steps` — shell commands run sequentially; first non-zero exit code aborts the sequence
+
+## Development
+
+```bash
+# Test with a local config instead of ~/.config/mango/
+XDG_CONFIG_HOME=.test-config mango
+```
+
+Dependencies: [`textual`](https://github.com/Textualize/textual), [`pyyaml`](https://pyyaml.org/)

mango_tui-0.2.0/src/mango_tui.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/mango/__init__.py
+src/mango/config.default.yaml
+src/mango/config.py
+src/mango/main.py
+src/mango/merger.py
+src/mango/runner.py
+src/mango/tui/__init__.py
+src/mango/tui/app.py
+src/mango_tui.egg-info/PKG-INFO
+src/mango_tui.egg-info/SOURCES.txt
+src/mango_tui.egg-info/dependency_links.txt
+src/mango_tui.egg-info/entry_points.txt
+src/mango_tui.egg-info/requires.txt
+src/mango_tui.egg-info/top_level.txt

mango_tui-0.2.0/src/mango_tui.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mango_tui-0.2.0/src/mango_tui.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mango = mango.main:main

mango_tui-0.2.0/src/mango_tui.egg-info/requires.txt

@@ -0,0 +1,2 @@
+textual>=0.60.0
+pyyaml>=6.0

mango_tui-0.2.0/src/mango_tui.egg-info/top_level.txt

@@ -0,0 +1 @@
+mango