From 347981d97122a5643d6e68c1ba2d5e3a53951e1a Mon Sep 17 00:00:00 2001 From: Elian Thorne <289383015+ElianThorne@users.noreply.github.com> Date: Tue, 2 Jun 2026 08:12:00 +0530 Subject: [PATCH] Revise README for clarity and feature overview Updated README to clarify TruShell's purpose and features. --- README.md | 249 +++++++++++++++++++++++++----------------------------- 1 file changed, 115 insertions(+), 134 deletions(-) diff --git a/README.md b/README.md index 9d60efe..a63c945 100644 --- a/README.md +++ b/README.md @@ -1,158 +1,139 @@ -# 🐄 TruShell +🐄 TruShell - a lightweight, context‑aware shell for developers +=========================================================== -TruShell is a small productivity shell for people who want task tracking and time -tools next to ordinary terminal commands. It is not meant to replace bash, zsh, -fish, or PowerShell; it sits beside them and handles the lightweight workflow -bits that are easy to forget during a coding session. +TruShell is not a full replacement for bash or zsh. It is a small +utility shell that sits next to your normal terminal and helps you +track tasks, check times, set alarms, and run ordinary commands. -## What It Does +It is written in Python and uses a SQLite database for todos. +When you type a command TruShell does not recognise, it passes it +directly to the host system’s shell (bash, cmd, etc.). -- Keeps todos in SQLite with stable display positions. -- Shows local time, world clocks, alarms, and a stopwatch through ChronoTerm. -- Falls back to host operating-system commands when a command is not handled by - TruShell. -- Opens a Textual editor for quick file edits from the REPL. -- Supports short joke breaks with configurable cowsay characters and optional - local sound files. -## Install +What makes TruShell useful +-------------------------- -```bash -pip install trushell -``` + * Built‑in todo manager with stable task numbers + – add, delete, update, complete, show + – categories and done/open status stored in SQLite -For local development: + * Time tools without leaving your terminal + – ‘now’ shows local time + – ‘world’ lists your saved time zones + – ‘alarm’ schedules one‑shot reminders + – ‘sw’ controls a stopwatch (start, pause, lap, reset) -```bash -git clone https://github.com/AkshajSinghal/trushell.git -cd trushell -pip install -e ".[dev]" -``` + * Jokes, because work needs breaks + – ‘joke’ shows a random joke with cowsay‑style art + – ‘joke_trex’ for a T‑Rex joke, with optional sound + – you can change the character via settings -After installation, the `trushell` console script is added to your shell `PATH` and can be run directly. + * Built‑in full‑screen editor (Textual) + – ‘edit ’ opens a quick editor inside the REPL -If you are working from the source tree without installing, run: + * Safe external command execution + – piped / chained commands are blocked + – external commands run without a shell when possible + – optional CPU/memory monitoring if psutil is present -```bash -PYTHONPATH=. python -m trushell -``` -## Quick Start +Quick start +----------- -```bash -$ trushell -Entering TruShell. Type 'exit' to quit. -trushell> help -Available commands: joke, joke_trex, addtask, deletetask, updatetask, completetask, showtask, now, time, world, tz, alarm, sw, settings, exit, help +Install from PyPI: -trushell> addtask "Review PR" "Work" -Task added. + `pip install trushell` -trushell> showtasks -Todos - # Todo Category Done - 1 Review PR Work open +Then run: -trushell> time - ___________________ - | _______________ | - | | 14:30 | | - | |_______________| | - | ___ ___ ___ ___ | - |_|___|___|___|___|_| + `trushell` -trushell> ls -``` +Inside TruShell, type ‘help’ for a list of commands. +Type ‘exit’ or Ctrl‑D to quit. -## Commands - -### Todo - -| Command | Description | -| --- | --- | -| `addtask "" ""` | Add a new todo. | -| `deletetask ` | Delete by the number shown in `showtasks`. | -| `updatetask "" ""` | Update task text and category. | -| `completetask ` | Mark a task as done. | -| `showtasks` | Print the current todo list. | - -### Time - -| Command | Description | -| --- | --- | -| `now` | Show current local time. | -| `time` | Show the configured ASCII clock. | -| `world` | Show saved time zones. | -| `tz list` | List saved time zones. | -| `tz add ` | Add a time zone such as `Europe/London`. | -| `tz remove ` | Remove a saved time zone. | -| `alarm list` | List alarms. | -| `alarm add "" --label "Name"` | Add an alarm. | -| `alarm remove ` | Remove an alarm by ID. | -| `sw start`, `sw pause`, `sw lap`, `sw reset`, `sw show` | Stopwatch controls. | - -### Shell And Settings - -| Command | Description | -| --- | --- | -| `settings` | Change persisted preferences. | -| `edit ` | Open the built-in Textual editor. | -| `cd ` | Change TruShell's current directory. | -| `help` | Print command help. | -| `exit` or `quit` | Leave the REPL. | - -Unrecognized commands are executed directly through the host OS without shell -operator expansion. Commands containing pipes, redirects, or chained operators -are rejected for now because they need a proper parser before they can be passed -through safely. - -## Storage - -Todos and application preferences are stored in SQLite under the platform's user -data directory. Older JSON state files are migrated into SQLite on first load and -renamed to a `.bak` file so the original settings are not silently discarded. - -## Architecture Notes - -TruShell uses a few terminal libraries, each for a narrow job: - -- Typer owns command parsing and CLI entry points. -- Rich owns formatted terminal output such as tables and styled status text. -- Textual is used only for the full-screen editor, where a widget toolkit is - more appropriate than line-by-line terminal output. - -The main modules are: - -```text -trushell/ - cli.py direct CLI commands - project.py interactive REPL and host-command fallback - todocli.py todo commands - database.py SQLite connection and persistence helpers - settings.py prompt-based preference editor - pyfunny.py jokes, cowsay rendering, and sound selection - chronoterm/ - shell.py time-related commands - state.py SQLite-backed app state with JSON migration - alarms.py alarm scheduling - timezones.py world clock helpers - stopwatch.py stopwatch state - sound.py platform-specific audio fallback +To run from source: +``` + git clone https://github.com/AkshajSinghal/trushell + cd trushell + pip install -e . + PYTHONPATH=. python -m trushell ``` -## Development +Core commands (most useful) +---------------------------- -```bash -pip install -e ".[dev]" -pytest tests/ -``` +Todo management: + `addtask "task description" "Category"` + `deletetask ` + `updatetask "new desc" "new category"` + `completetask ` + `showtasks` + +Time & alarms: + now + time – shows an ASCII clock + world + tz list | add | remove + alarm list | add HH:MM --label "name" | remove + sw start | pause | lap | reset | show + +Other: + edit + cd + settings – change preferences interactively + joke + joke_trex + + +Configuration +------------- + +Run the ‘settings’ command inside TruShell. You can change: + + * clock style (LCD, wrist watch, desktop clock) + * 12h / 24h format + * cowsay character for jokes (cow, trex, dragon, tux, kitty, …) + * joke sound (choose from available .mp3 or .wav files) + +Settings are saved automatically. + + +Where data lives +---------------- + +Todos and application preferences are stored in SQLite. The database +file is placed in the platform’s standard user data directory: + + * Linux: ~/.local/share/trushell/ + * macOS: ~/Library/Application Support/trushell/ + * Windows: %APPDATA%\trushell\ + +Old JSON state files (from earlier versions) are automatically +renamed to .bak and migrated into SQLite on first run. + + +Security notes +-------------- + +TruShell blocks commands that contain ‘|’, ‘>’, ‘&&’, or ‘||’ to prevent +accidental chaining inside the REPL. External commands are executed +using Python’s subprocess without a shell when possible. + +If you want to use shell operators, exit TruShell and run the command +in your normal shell. + + +Development +----------- + +Tests: pytest tests/ +Version: kept in sync between trushell/__init__.py and pyproject.toml -The package metadata is in `pyproject.toml`; the runtime version exported by -`trushell.__version__` should be kept in sync with it. +To add a custom sound for jokes, put an .mp3 or .wav file into +trushell/chronoterm/sounds/ – it will appear in the ‘settings’ menu. -For custom joke sounds, prefer `.mp3` and `.wav` assets for the broadest -cross-platform playback support across the available audio backends. -## License +License +------- -Apache-2.0. See [LICENSE](LICENSE) for details. +Apache 2.0 – see LICENSE file in the repository.