Metadata-Version: 2.4
Name: shevam
Version: 0.1.0
Summary: A project & tools management CLI built with Typer and Textual
Requires-Python: >=3.10
Requires-Dist: gitpython>=3.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.60.0
Requires-Dist: typer[all]>=0.12.0
Description-Content-Type: text/markdown

# Shevam ◈  v0.2.0

**Shevam** is a modular project & tools manager with a full **plugin system**.
Built with [Typer](https://typer.tiangolo.com/) + [Textual](https://textual.textualize.io/).  
Pure-Python JSON storage — zero external DB required.

---

## Install

```bash
pip install -e .   # Python 3.10+
```

---

## Core workflow

```bash
shevam init [dir]    # writes project.json into dir (npm init style)
shevam add  [dir]    # reads project.json → registers in ~/.shevam/db.json
shevam list          # table of all projects
shevam show <n>      # full detail panel
shevam update <n>    # update fields + rewrite project.json
shevam remove <n>    # remove from DB
shevam recent        # recently accessed
shevam ui            # full Textual TUI
```

---

## Plugin system

### Storage
```
~/.shevam/
  db.json          registered projects
  recent.json      access history
  plugins.json     enabled/disabled state
  plugins/
    <name>/
      plugin.py    user-installed plugins
shevam/plugins_builtin/
  stats_widget/    built-in: type breakdown widget + CLI
  git_info/        built-in: git status TUI view + CLI
```

### What plugins can do

| Capability | How |
|---|---|
| **Dashboard widget** | `self.add_dashboard_widget(label, factory, position)` |
| **New TUI view** | `self.add_tui_view(view_id, label, factory, nav_key)` |
| **Theme / CSS patch** | `self.add_css(css_string)` or full replace via `theme_registry.replace()` |
| **CLI sub-app** | `self.add_cli_app(typer_app)` → `shevam <plugin_id> <cmd>` |
| **CLI top-level cmd** | `self.add_cli_command(fn)` |
| **Hooks** | `self.add_hook("before_add", fn)` etc. |

### Available hooks

| Hook | When fired | Context keys |
|---|---|---|
| `before_init` | Before project.json is written | `name`, `path` |
| `after_init`  | After project.json written | `name`, `path` |
| `before_add`  | Before registering in DB | all project fields |
| `after_add`   | After registering in DB | `name`, `path`, `project_type` |
| `before_update` | Before update | `name`, `fields` |
| `after_update`  | After update | `name` |
| `before_remove` | Before removal (return False to abort) | `name` |
| `after_remove`  | After removal | `name` |

### Module mode (plugin CLI)

```bash
shevam -m stats_widget summary
shevam -m git_info status my-app
shevam -m git_info log my-app -n 20

# or directly as sub-commands:
shevam stats_widget summary
shevam git_info status all
```

### Plugin management

```bash
shevam plugin list
shevam plugin install /path/to/my_plugin/
shevam plugin disable git_info
shevam plugin enable  git_info
```

### Writing a plugin

Create `~/.shevam/plugins/my_plugin/plugin.py`:

```python
from shevam.plugin_engine import ShevamPlugin
import typer

cli = typer.Typer()

@cli.command("hello")
def hello():
    print("Hello from my_plugin!")

class MyPlugin(ShevamPlugin):
    plugin_id   = "my_plugin"
    plugin_name = "My Plugin"
    version     = "0.1.0"
    description = "Example user plugin"

    def load(self):
        # Add dashboard widget
        from textual.widgets import Static
        self.add_dashboard_widget(
            label="MY WIDGET",
            factory=lambda: Static("Hello from plugin!"),
            position="bottom",
        )
        # Add CLI
        self.add_cli_app(cli)
        # Add hook
        self.add_hook("after_add", lambda ctx: print(f"Added: {ctx['name']}"))
        # Patch CSS
        self.add_css("/* custom styles */")
```

Then: `shevam plugin install ~/.shevam/plugins/my_plugin/`

---

## TUI key bindings

| Key | Action |
|-----|--------|
| `1` | Dashboard |
| `2` | Projects list |
| `3` | Git view (git_info plugin) |
| `9` | Plugin registry |
| `a` | Add project |
| `e` | Edit selected |
| `d` | Delete selected |
| `r` | Refresh |
| `q` | Quit |
