shevam 0.1.0

A project & tools management CLI built with Typer and Textual

Shevam ◈ v0.2.0

Shevam is a modular project & tools manager with a full plugin system. Built with Typer + Textual.
Pure-Python JSON storage — zero external DB required.

---

Install

pip install -e .   # Python 3.10+

---

Core workflow

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)

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

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:

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