Metadata-Version: 2.3
Name: terminal-extensions
Version: 0.1.0
Summary: A library for extending terminal environments with custom hooks
License: MIT
Keywords: terminal,extensions,cli
Author: Your Name
Author-email: your.email@example.com
Requires-Python: >=3.7
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: lint
Provides-Extra: test
Requires-Dist: black (>=22.0) ; extra == "dev"
Requires-Dist: black (>=22.0) ; extra == "lint"
Requires-Dist: build ; extra == "dev"
Requires-Dist: mkdocs ; extra == "dev"
Requires-Dist: mkdocs ; extra == "docs"
Requires-Dist: mkdocs-material ; extra == "dev"
Requires-Dist: mkdocs-material ; extra == "docs"
Requires-Dist: mkdocstrings[python] ; extra == "dev"
Requires-Dist: mkdocstrings[python] ; extra == "docs"
Requires-Dist: mypy (>=0.950) ; extra == "dev"
Requires-Dist: mypy (>=0.950) ; extra == "lint"
Requires-Dist: pre-commit ; extra == "dev"
Requires-Dist: pre-commit ; extra == "lint"
Requires-Dist: pytest (>=7.0) ; extra == "dev"
Requires-Dist: pytest (>=7.0) ; extra == "test"
Requires-Dist: pytest-asyncio ; extra == "dev"
Requires-Dist: pytest-asyncio ; extra == "test"
Requires-Dist: ruff ; extra == "dev"
Requires-Dist: ruff ; extra == "lint"
Requires-Dist: twine ; extra == "dev"
Requires-Dist: types-Markdown ; extra == "dev"
Requires-Dist: types-PyYAML ; extra == "dev"
Requires-Dist: types-click ; extra == "dev"
Requires-Dist: types-requests ; extra == "dev"
Project-URL: Documentation, https://github.com/swecc/terminal-extensions#readme
Project-URL: Homepage, https://github.com/swecc/terminal-extensions
Project-URL: Issues, https://github.com/swecc/terminal-extensions/issues
Description-Content-Type: text/markdown

# Terminal Extensions

A lightweight Python library for extending your terminal environment with custom hooks. This library allows you to easily add custom functionality to your terminal by writing simple Python functions.

## Features

- Simple decorator-based API for registering hooks
- Support for both prefix-specific and global hooks
- Automatic loading of hooks from a `.hooks` directory
- Minimal overhead and easy integration

## Installation

```bash
pip install terminal-extensions
```

## Quick Start

1. Create a `.hooks` directory in your project
2. Add Python files with your hooks:

```python
from terminal_extensions import terminal_hook

# Hook that runs for all commands
@terminal_hook()
def log_commands(command: str) -> bool:
    print(f"Executing: {command}")
    return True  # Continue processing other hooks

# Hook that only runs for commands starting with "git"
@terminal_hook("git")
def git_helper(command: str) -> bool:
    if command == "git status":
        print("Nice job checking in!")
    return True
```

3. Run the terminal extensions:

```bash
terminal-ext
```

## Writing Hooks

### Hook Types

1. **Global Hooks** - Run for every command:
```python
@terminal_hook()
def my_hook(command: str) -> bool:
    # Process any command
    return True
```

2. **Prefix Hooks** - Run only for commands with specific prefixes:
```python
@terminal_hook("docker")
def docker_hook(command: str) -> bool:
    # Process only docker commands
    return True
```

### Hook Return Values

- Return `True` to continue processing other hooks and execute the command
- Return `False` to stop processing and prevent command execution

### Hook Organization

Place your hooks in `.py` files within the `.hooks` directory:

```
your_project/
├── .hooks/
│   ├── git_hooks.py
│   ├── docker_hooks.py
│   └── general_hooks.py
└── ...
```

## Examples

### Command Logging
```python
@terminal_hook()
def log_commands(command: str) -> bool:
    with open("command_history.log", "a") as f:
        f.write(f"{command}\n")
    return True
```

### Security Check
```python
@terminal_hook("rm")
def confirm_delete(command: str) -> bool:
    response = input("Are you sure you want to delete? [y/N] ")
    return response.lower() == 'y'
```

### Command Enhancement
```python
@terminal_hook("git")
def git_shortcuts(command: str) -> bool:
    if command == "git st":
        print("Expanding to git status...")
        return "git status"
    return True
```

## Configuration

The library automatically looks for hooks in the `.hooks` directory of your current working directory.

## Error Handling

Hooks are executed in a safe environment. If a hook raises an exception:
- The error is logged to stderr
- Processing continues with the next hook
- The original command is still executed (unless explicitly prevented)

## Contributing

See [CONTRIBUTORS.md](CONTRIBUTORS.md) for guidelines on contributing to this project.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

