flyshell 1.0.0__py3-none-any.whl

flyshell/core/loader.py

@@ -0,0 +1,90 @@
+# src\flyshell\core\loader.py
+
+from flyshell.abstract.base_plugin import BasePlugin
+from flyshell.core import data
+from flyshell.core.directory import COMMAND_REGISTRY
+
+from pathlib import Path
+import importlib.util
+import inspect
+import os
+import sys
+
+RESERVED_NAMES = set(COMMAND_REGISTRY.keys())
+
+def scan_plugins(plugin_folder=None):
+    folder = Path(plugin_folder) if plugin_folder else data.USER_PLUGIN_DIR
+    data.PLUGINS.clear()
+    if not folder.exists():
+        folder.mkdir(parents=True, exist_ok=True)
+        print("\nNo plugins found.")
+        return
+    folder_str = str(folder)
+    if folder_str not in sys.path:
+        sys.path.insert(0, folder_str)
+    candidates = {}
+    for item in folder.iterdir():
+        file_path = None
+        plugin_name = None
+        if item.is_file() and item.suffix == ".py" and not item.name.startswith("_"):
+            file_path = item
+            plugin_name = item.stem
+        elif item.is_dir() and not item.name.startswith((".", "_")):
+            entry = item / "plugin.py"
+            if entry.exists():
+                file_path = entry
+                plugin_name = item.name
+        if not file_path:
+            continue
+        try:
+            spec = importlib.util.spec_from_file_location(plugin_name, file_path)
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+            for _, obj in inspect.getmembers(module, inspect.isclass):
+                if issubclass(obj, BasePlugin) and obj is not BasePlugin:
+                    ctx = build_context(plugin_name, file_path)
+                    instance = obj(ctx)
+                    candidates.setdefault(plugin_name, []).append((instance, file_path))
+                    break
+        except Exception as e:
+            print(f"\n⚠️ Plugin Failure - Failed to inspect '{plugin_name}'")
+            print(f"Exception code: {e}, Flyshell will still launch.")
+    loaded_count = 0
+    first_print = True
+    for name, entries in candidates.items():
+        failed = False
+        if name in RESERVED_NAMES:
+            print(f"\n⚠️ Collision Error - Plugin '{name}' conflicts with a built-in Flyshell command and will not be loaded.")
+            failed = True
+        if len(entries) > 1:
+            paths = "\n    - ".join(str(path) for _, path in entries)
+            print(f"\n⚠️ Collision Error - Multiple plugins named '{name}' detected: {paths}")
+            print(f"The above plugins will not be loaded. Please rename them to unique names.")
+            failed = True
+        if failed:
+            continue
+        instance, _ = entries[0]
+        data.PLUGINS[name] = instance
+        if first_print:
+            print("\nInstalled Plugins:")
+            first_print = False
+        print(f"✅ - {name}")
+        loaded_count += 1
+    if loaded_count > 0:
+        print(f"\nTotal of {loaded_count} plugin(s) found.")
+    else:
+        print("\nNo plugins loaded.")
+
+def build_context(plugin_name, file_path=None):
+    plugin_storage = data.get_all_plugin_data(plugin_name)
+    context = {
+        "plugin_name": plugin_name,
+        "file_path": str(file_path) if file_path else None,
+        "metadata": {
+            "host_os": data.HOST_OS,
+            "version": data.VERSION,
+            "build": data.BUILD
+        },
+        "storage": plugin_storage
+    }
+    return context

flyshell/main.py

@@ -0,0 +1,115 @@
+# src\flyshell\main.py
+
+from pathlib import Path
+import os
+import sys
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+SRC_DIR = PACKAGE_ROOT.parent
+PROJECT_ROOT = SRC_DIR.parent
+
+if str(SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(SRC_DIR))
+
+def boot_check():
+    print("\nFlyshell will now check that your modules exist.")
+    abstract_dir = PACKAGE_ROOT / "abstract"
+    builtin_dir = PACKAGE_ROOT / "builtin"
+    core_dir = PACKAGE_ROOT / "core"
+    REQUIRED_COMPONENTS = [
+        abstract_dir,
+        abstract_dir / "base_cmd.py",
+        abstract_dir / "base_plugin.py",
+        abstract_dir / "parent_cmd.py",
+        builtin_dir,
+        builtin_dir / "fs.py",
+        builtin_dir / "system.py",
+        builtin_dir / "utils.py",
+        core_dir,
+        core_dir / "auth.py",
+        core_dir / "console.py",
+        core_dir / "data.py",
+        core_dir / "directory.py",
+        core_dir / "loader.py",
+    ]
+    present = []
+    missing = []
+    for path in REQUIRED_COMPONENTS:
+        if path.exists():
+            present.append(str(path))
+        else:
+            missing.append(str(path))
+    if missing:
+        print("\nCRITICAL BOOT ERROR: Critical system module(s) could not be found.")
+    for i in present:
+        print(f"✅ {i} - File found")
+    for i in missing:
+        print(f"❌ {i} - FILE NOT FOUND")
+    if missing:
+        return False
+    tests_dir = PROJECT_ROOT / "tests"
+    if tests_dir.exists():
+        print("\nFlyshell will now check internal additional packages and features. These are not required.")
+        for path in tests_dir.glob("test_*.py"):
+            print(f"✅ {path.name} - Test found")
+        try:
+            import pytest
+            print(f"✅ Your tests can be run using Pytest.")
+        except ImportError:
+            print(f"⚠️ Your tests cannot be run as Pytest is not installed.")
+    print("\nFlyshell will now check external additional packages and features. These are not required.")
+    from flyshell.core import console
+    if console.check_readline():
+        print("✅ Terminal Readline - Available (Use arrow keys to navigate input history)")
+    else:
+        print("⚠️ Terminal Readline - Unavailable (This does not affect your performance)")
+    return True
+
+def main():
+    os.system("")
+    print("\033[H\033[2J", end="")
+    print("\nLaunch process initiated. Flyshell is checking it is able to launch...")
+    try:
+        if boot_check():
+            from flyshell.core import auth, console, data, loader
+            if data.HOST_OS in ["Windows", "Darwin", "Linux"]:
+                if sys.version_info < (3, 10):
+                    print("\nCRITICAL ERROR: Your Python version is too old to be supported by Flyshell.")
+                    print("Flyshell cannot launch because it requires Python 3.10 or newer.")
+                    sys.exit(1)
+                print(f"\nYour OS '{data.HOST_OS}' is compatible with Flyshell.")
+                print("Flyshell will now boot.")
+                loader.scan_plugins()
+                if auth.login_flow():
+                    console.boot()
+                else:
+                    print("Shutting down...\n")
+                    sys.exit(0)
+            else:
+                print(f"\nCRITICAL ERROR: Host operating system '{data.HOST_OS}' is not supported.")
+                print("Flyshell cannot launch because your operating system is not supported.")
+                sys.exit(1)
+        else:
+            print("\nFlyshell cannot launch until the above file paths are restored.")
+            sys.exit(1)
+    except KeyboardInterrupt:
+        print("\n\nFlyshell session terminated, shutting down...\n")
+        sys.exit(0)
+    except Exception as e:
+        print("\n❌❌❌ Oops! An unexpected error occurred.")
+        print(f"Error details: {e}")
+        print("We don't really know what happened there. Sorry about that.\n")
+        print("Print traceback message? Default is N.")
+        choice = input("[y/n]?: ")
+        if choice.lower() == "y":
+            import traceback
+            raw = traceback.extract_tb(e.__traceback__)
+            last_frame = raw[-1] 
+            print("\nTraceback details:")
+            print(f"File: '{last_frame[0]}'")
+            print(f"Line: {last_frame[1]}")
+            print(f"Exception message: '{e}'")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

flyshell-1.0.0.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: flyshell
+Version: 1.0.0
+Summary: A modular, zero-dependency command-line environment in Python.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: readline
+Requires-Dist: pyreadline3; sys_platform == "win32" and extra == "readline"
+Dynamic: license-file
+
+# Flyshell
+
+![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+![Licence](https://img.shields.io/badge/license-MIT-green.svg)
+![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)
+![Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)
+![Tests](https://github.com/kianodev/flyshell/actions/workflows/pytest.yml/badge.svg)
+
+> Documentation last updated: v1.0.0
+
+A modular, zero-dependency command-line environment and extensible runtime interface built in Python.
+
+Flyshell provides a modular, extensible shell environment featuring dynamic runtime plugin loading, session persistence, secure authentication, and cross-platform process isolation, using only Python standard libraries.
+
+No extra packages required, just install and enjoy!
+
+## Key Features
+
+1. **Zero External Dependencies** - Flyshell is built entirely with native Python modules with absolutely zero third-party packages required to enjoy full functionality.
+2. **Dynamic Plugin Architecture**: Flyshell employs a dynamic plugin architecture that automatically scans for plugins in the User Directory following the standard defined in `src/flyshell/abstract/base_plugin.py`.
+3. **Secure Authentication**: Flyshell uses salted PBKDF2 HMAC (SHA-256, 600,000 iterations) with constant-time equality comparisons to prevent timing attacks on password information.
+4. **Cross-Platform Support**: Flyshell is fully supported by Windows (NT), macOS (Darwin) and Linux installations with native OS management and POSIX-aware parsing. Note that Flyshell is **not** supported by any other systems.
+5. **State and History Persistence**: Flyshell has a fully encapsulated SQL storage system using SQLite3 providing session metrics and ISO 8601 UTC audit logging.
+
+## System Requirements
+
+1. **Python**: Your Python installation or IDE must support **Python 3.10 or newer** as Flyshell utilises structural pattern matching features. Older Python installations will be rejected by Flyshell on boot or could crash the system.
+2. **Operating System**: Your operating system must be **Windows 10/11, macOS (Darwin) or Linux**. Any other operating system will be rejected by Flyshell on boot.
+
+## System Architecture
+
+```
+flyshell/
+├── .github/
+│   └── workflows/
+│       └── pytest.yml
+├── src/
+│   └── flyshell/
+│       ├── abstract/
+│       │   ├── __init__.py
+│       │   ├── base_cmd.py
+│       │   ├── base_plugin.py
+│       │   └── parent_cmd.py
+│       ├── builtin/
+│       │   ├── __init__.py
+│       │   ├── fs.py
+│       │   ├── system.py
+│       │   └── utils.py
+│       ├── core/
+│       │   ├── __init__.py
+│       │   ├── auth.py
+│       │   ├── console.py
+│       │   ├── data.py
+│       │   ├── directory.py
+│       │   └── loader.py
+│       ├── __init__.py
+│       └── main.py
+├── tests/
+│   ├── test_auth.py
+│   ├── test_data.py
+│   ├── test_directory.py
+│   ├── test_loader.py
+│   └── test_security.py
+├── .gitignore
+├── LICENSE
+├── pyproject.toml
+└── README.md
+```
+
+## Installing Flyshell
+
+There are two methods to install Flyshell.
+
+### Method 1: Install via `pip` (Best for General Use)
+
+Install Flyshell through `pip`:
+```bash
+pip install flyshell
+```
+
+Then, you can simply run Flyshell:
+```bash
+flyshell
+```
+
+### Method 2: Install from source via `git` (Best for Development & Custom Plugins)
+
+Clone the GitHub repository:
+```bash
+git clone https://github.com/kianodev/flyshell.git
+```
+
+Switch to the Flyshell directory and install in editable mode:
+```bash
+cd flyshell
+pip install -e .
+```
+
+### Adding optional dependencies
+
+To install Readline (on Windows):
+```bash
+pip install -e .[readline]
+```
+
+To install the development and testing suite (including Pytest):
+```bash
+pip install -e .[dev]
+```
+
+## Exploring Flyshell
+
+Once you have installed Flyshell using either of the methods above, you will be prompted to initialise your user profile. Once this is complete, you will be greeted with a prompt that looks like this:
+```console
+Flyshell [v1.x.x] (current_dir)>>
+```
+
+From this stage, you can enter a wide variety of commands. To see the commands list for your installation, type `cmds` or `help` to return a full up-to-date directory. Use `fs plugins` to return plugin information.
+
+Flyshell also supports command chaining out of the box. Use `;` to chain commands together regardless of result, `&&` to execute only on success and `||` to execute only on failure.
+
+Use `-h` or `--help` after any command to return that command's specific help list.
+
+To close Flyshell once you are done, enter `kill` onto the command line then confirm, or press Ctrl + D to close the session immediately.
+
+## Creating Custom Plugins
+
+Flyshell features an extensible plugin API. This API supports both single-file and multi-file plugins. Follow the below guide to create your own.
+
+Plugins must inherit from the `BasePlugin` contract defined in `src/flyshell/abstract/base_plugin.py`. Plugins are stored in the User Directory. Navigate to your App Storage folder:
+- **Windows**: `%APPDATA%\Flyshell\plugins`
+- **macOS**: `~/Library/Application Support/Flyshell/plugins`
+- **Linux**: `~/.local/share/Flyshell/plugins`
+
+Place your plugins inside the `plugins/` folder.
+
+All plugins should define the required attributes. Flyshell can read this information for both `fs plugins` and `[my_plugin] -h` / `--help` which are both supported out of the box. Flyshell will discover, inspect and import your plugin from the `plugins/` folder without you having to alter any internal code.
+
+### The Entry-Point
+
+All plugins must have an entry-point file. For single-file plugins, this is the plugin file. For multi-file plugins, this file must be named `plugin.py` and stored directly inside of your plugin's own folder.
+
+This file is what enables Flyshell to speak to your plugin.
+
+```python
+# Entry-point (my_plugin.py or my_plugin\plugin.py)
+
+from flyshell import BasePlugin # This is required
+
+class MyPlugin(BasePlugin):
+	name = "My Plugin" # The name you want visible to Flyshell
+	description = "This is my plugin." # A short one-line explaining what your plugin does
+	version = "1.0.0" # Default is 1.0.0
+	author = "kianodev" # You can put your name, your GitHub handle, or leave blank to make it 'Unknown'
+	usage = "" # (OPTIONAL) Explain how to use your plugin
+	extended_help = "" # (OPTIONAL) A more detailed, multi-line guide containing specific assistance
+	
+	def on_load(self): # (OPTIONAL) Enables your program to handle specialist set-up tasks before execute()
+		pass
+
+	def on_unload(self): # (OPTIONAL) Enables your program to handle specialist shut-down tasks
+		super().on_unload() # If you use a custom on_unload(), end it with this
+
+
+	def execute(self, args): # This is what Flyshell calls to execute
+		print(f"Hello! Arguments: {args}")
+		return
+```
+
+### Extra Functions
+
+Additional functions are available for you to use:
+
+1. `get_data(key, default=None)`: Retrieves a value from local plugin memory.
+2. `set_data(key, value)`: Updates a key in local memory and automatically persists it to SQLite via `save_storage()`.
+3. `load_storage()`: Reloads fresh key-value pairs directly from SQLite into `self.storage`.
+4. `save_storage()`: Writes all in-memory key-value pairs in `self.storage` back to SQLite.
+
+Plugins save automatically on shut-down. If `on_unload()` is not used, it is automatic. If `on_unload()` is used, `super().on_unload()` saves your files.
+
+### Built-in Attributes
+
+Every plugin has direct access to the following instance variables:
+
+- `self.plugin_name` (`str`): The unique name identifier used to invoke the plugin.
+- `self.storage` (`dict`): In-memory key-value data automatically loaded from the persistent database.
+- `self.context` (`dict`): Environmental metadata provided at start-up, within it:
+  - `self.context["metadata"]["host_os"]`: Operating system (e.g., `'Windows'`, `'Linux'`, `'Darwin'`).
+  - `self.context["metadata"]["version"]`: Current Flyshell version.
+  - `self.context["file_path"]`: Full path to the plugin's source file.
+
+### Extra Notes
+
+You are welcome to catch errors yourself. However, Flyshell will handle them automatically. That said, if you would like your plugin to continue after an error, you need to implement error handling yourself as the default system closes your plugin.

flyshell-1.0.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+flyshell/__init__.py,sha256=45hJEblK9nMHFJF0N_x53uhAX9oocKmzy2kF-qHoLBo,164
+flyshell/main.py,sha256=hf2B2Ad35FMTXynwXyZk29wVdVrIPsVbOkICtcl86Rc,4492
+flyshell/abstract/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flyshell/abstract/base_cmd.py,sha256=kyKDLAmZJrBFbce0epBT6nom05GXYqZGhl0Fy1cImNU,982
+flyshell/abstract/base_plugin.py,sha256=W3E-ysd6zqSgwcqtATLujV9Bxf2_YXSifepTRqWU7W8,2408
+flyshell/abstract/parent_cmd.py,sha256=WSVDKCklQkHHOkKPsrY8F0ltTAuCzbl7bHEY9Sp0OIY,2387
+flyshell/builtin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flyshell/builtin/fs.py,sha256=dItltDzduKAexjmbsIVl_OUb-G4fCyX86tFwK60Sb0I,7215
+flyshell/builtin/system.py,sha256=sgk4GPV8mO6luQgWMUyuTQVBFL4Y0NzB2w37XQogEJE,4974
+flyshell/builtin/utils.py,sha256=cvzP43dU3oJm1a39fEBScUv-WJ5U9zoRuedvRIPpmr4,3478
+flyshell/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flyshell/core/auth.py,sha256=MwTM6uM-kddDi6B-yXc4B6TQlh0xuqOQJOZ4QhnbI9A,4271
+flyshell/core/console.py,sha256=Ktu2Qvaa6ZGFZCw7Vld_6HDJPQBnwYJDFuX9FkEeLxM,2155
+flyshell/core/data.py,sha256=0FlwssulyntbPoEjhHGfMd7YAoJEEDOGOjkOeA8IfGI,8842
+flyshell/core/directory.py,sha256=bXe6sEGfjKDVrYkX2Bc6mD7hIWjVvKr1VdCatV_otWI,8360
+flyshell/core/loader.py,sha256=2QUCAhkxf6p75O6nz5e0HG4jfIZvksBzQyEwVt-fvnU,3466
+flyshell-1.0.0.dist-info/licenses/LICENSE,sha256=0dEPo6haQq5yozzi3aql0C0FnUCTZ0WRakYTNQakEEw,1086
+flyshell-1.0.0.dist-info/METADATA,sha256=UVKhQ6WJxT9jxSueb9kJOCMA6uiUNW2nOVKprz9VCxE,9198
+flyshell-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flyshell-1.0.0.dist-info/entry_points.txt,sha256=MIfpdu-2yd0LEUu2gpmHiPxcytTQNrMgpQDNEmQH0UI,48
+flyshell-1.0.0.dist-info/top_level.txt,sha256=oOEQzHfYVg-GEu9H5YnHffSAMkyiB6ud9KUAj_TlHRw,9
+flyshell-1.0.0.dist-info/RECORD,,

flyshell-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flyshell-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flyshell = flyshell.main:main

flyshell-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kianodev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flyshell-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flyshell