Skip to content

Commit e0be971

Browse files
AkshajSinghalAkshajSinghal
authored
Revise README for clarity and additional features
Jai shree ram
1 parent 8425b0b commit e0be971

1 file changed

Lines changed: 187 additions & 143 deletions

File tree

‎README.md‎

Lines changed: 187 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,174 +1,218 @@
1-
# 🐄 TruShell
2-
A lightweight, context‑aware shell for developers
3-
4-
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
5-
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
6-
7-
---
8-
9-
It is written in Python and uses a SQLite database for todos.
10-
When you type a command TruShell does not recognise, it passes it
11-
directly to the host system’s shell (bash, cmd, etc.).
12-
13-
14-
What makes TruShell useful
15-
--------------------------
16-
17-
* Built‑in todo manager with stable task numbers
18-
– add, delete, update, complete, show
19-
– categories and done/open status stored in SQLite
20-
21-
* Time tools without leaving your terminal
22-
– ‘now’ shows local time
23-
– ‘world’ lists your saved time zones
24-
– ‘alarm’ schedules one‑shot reminders
25-
– ‘sw’ controls a stopwatch (start, pause, lap, reset)
26-
27-
* Jokes, because work needs breaks
28-
– ‘joke’ shows a random joke with cowsay‑style art
29-
– ‘joke_trex’ for a T‑Rex joke, with optional sound
30-
– you can change the character via settings
31-
32-
* Built‑in full‑screen editor (Textual)
33-
– ‘edit <filename>’ opens a quick editor inside the REPL
34-
35-
* Safe external command execution
36-
– piped / chained commands are blocked
37-
– external commands run without a shell when possible
38-
– optional CPU/memory monitoring if psutil is present
39-
40-
41-
Quick start
42-
-----------
43-
44-
Install from PyPI:
1+
# 🐄 TruShell
2+
3+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
4+
[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
5+
[![PyPI version](https://badge.fury.io/py/trushell.svg)](https://pypi.org/project/trushell/)
6+
7+
**TruShell** is a lightweight, context-aware productivity shell for developers. Written in Python, it blends a powerful interactive REPL with built-in tools for task management, time tracking, data visualization, and system navigation. When you type a command TruShell doesn’t recognize, it seamlessly passes it to your host system’s shell (bash, zsh, cmd, etc.), making it a frictionless drop-in replacement for your daily terminal workflow.
8+
9+
## Features
10+
11+
* **Interactive REPL**: A polished command-line interface with history support, tab completion, and emoji-rich prompts (with fallbacks for compatibility).
12+
* **Seamless OS Passthrough**: Unrecognized commands are automatically executed by your host operating system's shell.
13+
* **Task Management**: Built-in todo list with add, complete, update, delete, and show capabilities, persisted in SQLite.
14+
* **ChronoTerm Suite**:
15+
* `now` / `time`: Display current local time.
16+
* `world`: World clock for multiple timezones.
17+
* `tz`: Timezone conversion utilities.
18+
* `alarm`: Set and manage alarms.
19+
* `sw`: Stopwatch functionality.
20+
* **Data Visualization**: `csv-view` command for quick inspection of CSV files directly in the terminal.
21+
* **Developer Tools**:
22+
* `edit`: Launch a full-screen TUI text editor (powered by Textual) for quick file edits.
23+
* `j`: Quick directory jumping/navigation.
24+
* **Fun & Morale**:
25+
* `joke`: Get a random programming joke.
26+
* `joke-trex`: Get a T-Rex themed joke.
27+
* **Extensible Plugin System**: Load custom plugins from `~/.trushell/plugins/` or bundled repository plugins to extend functionality.
28+
* **Settings TUI**: A user-friendly terminal UI for managing application preferences.
29+
* **Cross-Platform**: Works on Linux, macOS, and Windows.
30+
31+
## Architecture
32+
33+
TruShell is built on a modern, modular architecture centered around the **TruKernel**:
34+
35+
* **TruKernel**: The core dispatch engine that manages command registration, execution, and plugin lifecycle. It uses a manifest-driven approach (`builtin_commands.md`) to register commands.
36+
* **Plugin Manager**: Discovers and loads plugins dynamically. Plugins can register new commands, override built-ins, and hook into `pre_exec` and `post_exec` events.
37+
* **SQLite Storage**: Todos, alarms, stopwatch state, and user preferences are stored in a SQLite database located in the platform-specific user data directory:
38+
* **Linux**: `~/.local/share/trushell/`
39+
* **macOS**: `~/Library/Application Support/trushell/`
40+
* **Windows**: `%APPDATA%\trushell\`
41+
* **Libraries**:
42+
* **[Typer](https://typer.tiangolo.com/)**: For CLI entry points and argument parsing.
43+
* **[Rich](https://rich.readthedocs.io/)**: For beautiful terminal output (tables, styled text).
44+
* **[Textual](https://textual.textualize.io/)**: For the full-screen TUI editor and settings interface.
45+
* **[prompt_toolkit](https://prompt-toolkit.readthedocs.io/)**: For advanced readline features, history, and completion in the REPL.
46+
47+
## Installation
48+
49+
### Prerequisites
50+
51+
* Python 3.10 or higher.
52+
53+
### Install via pip
54+
55+
```bash
56+
pip install trushell
57+
```
4558

46-
`pip install trushell`
59+
### Install from Source
4760

48-
Then run:
61+
```bash
62+
git clone https://github.com/TruFoundation/TruShell.git
63+
cd TruShell
64+
pip install .
65+
```
4966

50-
`trushell`
67+
## Usage
5168

52-
Inside TruShell, type ‘help’ for a list of commands.
53-
Type ‘exit’ or Ctrl‑D to quit.
69+
Start TruShell by running:
5470

55-
## Commands
71+
```bash
72+
trushell
73+
```
5674

57-
### Todo
75+
You will enter the interactive REPL:
5876

59-
| Command | Description |
60-
| --- | --- |
61-
| `addtask "<task>" "<category>"` | Add a new todo. |
62-
| `deletetask <position>` | Delete by the number shown in `showtasks`. |
63-
| `updatetask <position> "<task>" "<category>"` | Update task text and category. |
64-
| `completetask <position>` | Mark a task as done. |
65-
| `showtasks` | Print the current todo list. |
77+
```
78+
trushell /home/user/project ❯
79+
```
6680

67-
### Time
81+
### Built-in Commands
6882

6983
| Command | Description |
70-
| --- | --- |
84+
| :--- | :--- |
85+
| `help [command]` | Show help message or details for a specific command. |
86+
| `exit` / `quit` | Exit TruShell. |
87+
| `task` | Manage todos (subcommands: `add`, `complete`, `delete`, `show`, `update`). |
88+
| `joke` | Tell a random joke. |
89+
| `joke-trex` | Tell a T-Rex joke. |
7190
| `now` | Show current local time. |
72-
| `time` | Show the configured ASCII clock. |
73-
| `world` | Show saved time zones. |
74-
| `tz list` | List saved time zones. |
75-
| `tz add <IANA>` | Add a time zone such as `Europe/London`. |
76-
| `tz remove <IANA>` | Remove a saved time zone. |
77-
| `alarm list` | List alarms. |
78-
| `alarm add "<HH:MM>" --label "Name"` | Add an alarm. |
79-
| `alarm remove <id>` | Remove an alarm by ID. |
80-
| `sw start`, `sw pause`, `sw lap`, `sw reset`, `sw show` | Stopwatch controls. |
81-
82-
### Shell And Settings
83-
84-
| Command | Description |
85-
| --- | --- |
86-
| `settings` | Change persisted preferences. |
87-
| `edit <file>` | Open the built-in Textual editor. |
88-
| `cd <dir>` | Change TruShell's current directory. |
89-
| `z [options] [pattern]` | Jump to or list frequently used directories by fuzzy path matching. |
90-
| `help` | Print command help. |
91-
| `exit` or `quit` | Leave the REPL. |
92-
93-
Unrecognized commands are executed directly through the host OS without shell
94-
operator expansion. Commands containing pipes, redirects, or chained operators
95-
are rejected for now because they need a proper parser before they can be passed
96-
through safely.
97-
98-
## Storage
91+
| `time` | Alias for `now`. |
92+
| `world` | Show world clocks. |
93+
| `tz` | Convert time between timezones. |
94+
| `alarm` | Manage alarms. |
95+
| `sw` | Stopwatch controls. |
96+
| `csv-view <file>` | View a CSV file in a formatted table. |
97+
| `edit <file>` | Open a file in the built-in TUI editor. |
98+
| `j <dir>` | Jump to a directory (shortcut for `cd`). |
99+
| `settings` | Open the settings TUI. |
100+
| `<any other command>` | Passed directly to your host shell (e.g., `ls`, `git status`, `python script.py`). |
101+
102+
### Examples
103+
104+
```bash
105+
# Add a todo
106+
trushell ~/dev ❯ task add "Fix login bug" "Work"
107+
108+
# List todos
109+
trushell ~/dev ❯ task show
110+
111+
# Check the time in Tokyo
112+
trushell ~/dev ❯ world Tokyo
113+
114+
# Edit a file
115+
trushell ~/dev ❯ edit main.py
116+
117+
# Run a system command
118+
trushell ~/dev ❯ git status
119+
```
99120

100-
Todos and application preferences are stored in SQLite under the platform's user
101-
data directory. Older JSON state files are migrated into SQLite on first load and
102-
renamed to a `.bak` file so the original settings are not silently discarded.
121+
## 🔌 Plugin Development
122+
123+
TruShell supports plugins written in Python. To create a plugin:
124+
125+
1. Create a directory in `~/.trushell/plugins/` (e.g., `my_plugin`).
126+
2. Add an `__init__.py` file containing a class that inherits from `TruPlugin`.
127+
3. (Optional) Add a `plugin.json` for metadata.
128+
129+
Example `__init__.py`:
130+
131+
```python
132+
from trushell.core.plugin_api import TruPlugin
133+
134+
class MyPlugin(TruPlugin):
135+
name = "my_plugin"
136+
version = "0.1.0"
137+
138+
def on_load(self, kernel):
139+
print("MyPlugin loaded!")
140+
141+
def pre_exec(self, command: str, args: str) -> tuple[str, str]:
142+
# Modify command before execution
143+
return command, args
144+
145+
def post_exec(self, command: str, output: str):
146+
# Process output after execution
147+
pass
148+
```
103149

104-
## Architecture Notes
150+
## Development
105151

106-
TruShell uses a few terminal libraries, each for a narrow job:
152+
### Setup
107153

108-
- Typer owns command parsing and CLI entry points.
109-
- Rich owns formatted terminal output such as tables and styled status text.
110-
- Textual is used only for the full-screen editor, where a widget toolkit is
111-
more appropriate than line-by-line terminal output.
154+
```bash
155+
git clone https://github.com/TruFoundation/TruShell.git
156+
cd TruShell
157+
pip install -e ".[dev]"
158+
```
112159

113-
The main modules are:
160+
### Running Tests
114161

115-
```text
116-
trushell/
117-
cli.py direct CLI commands
118-
project.py interactive REPL and host-command fallback
119-
todocli.py todo commands
120-
database.py SQLite connection and persistence helpers
121-
settings.py prompt-based preference editor
122-
pyfunny.py jokes, cowsay rendering, and sound selection
123-
chronoterm/
124-
shell.py time-related commands
125-
state.py SQLite-backed app state with JSON migration
126-
alarms.py alarm scheduling
127-
timezones.py world clock helpers
128-
stopwatch.py stopwatch state
129-
sound.py platform-specific audio fallback
162+
```bash
163+
pytest
130164
```
131165

132-
Core commands (most useful)
133-
----------------------------
166+
### Code Style
134167

135-
Todo management:
136-
`addtask "task description" "Category"`
137-
`deletetask <number>`
138-
`updatetask <number> "new desc" "new category"`
139-
`completetask <number>`
140-
`showtasks`
168+
TruShell uses `ruff` and `black` for linting and formatting.
141169

142-
Time & alarms:
143-
now
144-
time – shows an ASCII clock
145-
world
146-
tz list | add <zone> | remove <id>
147-
alarm list | add HH:MM --label "name" | remove <id>
148-
sw start | pause | lap | reset | show
149-
150-
Other:
151-
edit <filename>
152-
cd <dir>
153-
settings – change preferences interactively
154-
joke
155-
joke_trex
170+
```bash
171+
ruff check .
172+
black .
173+
```
156174

175+
## 📂 Project Structure
157176

158-
Configuration
159-
-------------
177+
```
178+
trushell/
179+
├── cli.py # CLI entry point and REPL loop
180+
├── __main__.py # Allows running as python -m trushell
181+
├── commands/ # Built-in command implementations
182+
│ ├── core.py # Help, exit
183+
│ ├── tasks.py # Todo management
184+
│ ├── chronoterm.py # Time, alarms, stopwatch
185+
│ ├── data.py # CSV viewer
186+
│ ├── editor.py # TUI editor
187+
│ ├── joke.py # Jokes
188+
│ ├── nav.py # Navigation helpers
189+
│ └── settings.py # Settings TUI
190+
├── core/ # Core architecture
191+
│ ├── trukernel.py # Command dispatch engine
192+
│ ├── plugin_manager.py # Plugin loading and management
193+
│ ├── database.py # SQLite helpers
194+
│ └── models.py # Data models
195+
├── plugins/ # Bundled example plugins
196+
├── sounds/ # Audio assets for alarms
197+
└── config/ # Configuration manifests
198+
├── builtin_commands.md
199+
└── plugins.md
200+
```
160201

161-
Run the ‘settings’ command inside TruShell. You can change:
202+
## 🤝 Contributing
162203

163-
* clock style (LCD, wrist watch, desktop clock)
164-
* 12h / 24h format
165-
* cowsay character for jokes (cow, trex, dragon, tux, kitty, …)
166-
* joke sound (choose from available .mp3 or .wav files)
204+
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
167205

168-
Settings are saved automatically.
206+
1. Fork the repository.
207+
2. Create your feature branch (`git checkout -b feature/amazing-feature`).
208+
3. Commit your changes (`git commit -m 'Add some amazing feature'`).
209+
4. Push to the branch (`git push origin feature/amazing-feature`).
210+
5. Open a Pull Request.
169211

170212
## Star History
171213

214+
If TruShell helps streamline your workflow, consider giving it a star on GitHub! It helps others discover the project and motivates continued development.
215+
172216
<a href="https://www.star-history.com/?repos=AkshajSinghal%2FTruShell&type=date&legend=top-left">
173217
<picture>
174218
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=TruFoundation/TruShell&type=date&theme=dark&legend=top-left" />
@@ -216,4 +260,4 @@ trushell/sounds/ – it will appear in the ‘settings’ menu.
216260
License
217261
-------
218262

219-
Apache 2.0 – see LICENSE file in the repository.
263+
Apache 2.0 – see [LICENSE](LICENSE.md) file in the repository.

0 commit comments

Comments
 (0)