Metadata-Version: 2.4
Name: asashin-hub
Version: 0.1.0
Summary: A galaxy-inspired, extensible terminal workspace for developers and ethical pentesters.
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: textual<9,>=8.2
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: psutil<8,>=7.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"

# ASASHIN

![Asashin home screen in a real terminal](docs/assets/mission-control.png)

[Animated preview](docs/assets/galaxy-motion.gif)

Asashin is a Windows and Linux terminal hub for developer and ethical pentesting modules. A still cyan–magenta Milky Way header gets an occasional shooting star; a spiral galaxy rotates behind the compact tool lists. A full-size workspace runs two tools independently while the menu stays available.

Only four working tools ship in the hub: **Hash Lab, API Workbench, System Lens, and Workspace Inspector**. They run on Windows and Linux without shell-command dependencies or administrator rights. Authoring scaffolds remain available separately through `asashin new`, including a buildable C++ starter; they are not catalogue entries. Connect your own HTTPS registry to distribute more modules; no public module marketplace is included.

## Download

Get the Windows ZIP, Linux archive, Python wheel or source package from [tools.asashin.com](https://tools.asashin.com/#download). **Python 3.10+ is required**; these are starter packages rather than standalone binaries. Extract the complete archive, then open `Start Asashin.cmd` on Windows or run `sh start-asashin.sh` on Linux. The first launch creates a private environment in the extracted folder and downloads dependencies from PyPI. Later launches reuse it. SHA-256 checksums are published alongside every release.

The reference-based download website lives in [website](website/README.md). It is separate from the terminal UI.

## Launch

Python 3.10 or newer is required. Run these commands from the project folder.

**Linux**

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/asashin
```

**Windows · PowerShell**

```powershell
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\asashin.exe
```

The commands use the virtual environment directly, so shell activation is optional. On Linux, install your distribution's Python venv package if `python3 -m venv` reports that `ensurepip` is unavailable.

Use a truecolor terminal for the full galaxy palette. **140 columns × 46 rows** gives the starfield room; **80 × 24** uses compact navigation and a scrollable module list. A normal monospace font works. `NO_COLOR` is respected when set; unset it to enable colors.

```bash
asashin --no-animation
# Equivalent environment setting: ASASHIN_REDUCED_MOTION=1
```

Examples below assume the virtual environment is activated or its scripts directory is on your PATH. You can also use its Python executable followed by `-m asashin`.

## Inside the hub

| Key | Action |
| --- | --- |
| `1` | Home |
| `2` | Modules |
| `3` | Tool hub |
| `4` | Settings |
| `5` | Workspace (open tools keep their state) |
| `F6` | Focus menu / return to active workspace tool |
| `F7` | Switch between workspace tools |
| `Tab` | Switch between menu and modules; remember selection |
| `↓` / `↑` | Next / previous item in the focused menu or module list |
| `j` / `k` | Next / previous tool |
| `g` / `G` or `Home` / `End` | First / last tool |
| `/` | Search modules |
| `Enter` | Open the focused menu item or tool / leave search |
| `Shift+Tab` | Previous individual control, including filters and search |
| `Esc` | Leave search / close a popup or dialog; workspace tools continue |
| `Ctrl+P` | Command palette |
| `m` | Toggle decorative motion |
| `?` | Help |
| `Ctrl+Q` | Quit |

Use `Tab` to switch between the sidebar and module list, then `↑` / `↓` to move within that area. In the sidebar, `Enter` opens the selected page; arrow keys alone do not change pages. Each page remembers its last focused tool. The cyan focus highlight shows which area receives the arrows. `Shift+Tab` still visits individual controls in reverse order. Forms, dialogs and pages without module results retain ordinary Tab navigation. Mouse interaction is supported too. Open a module to inspect it, run it, or install it from the Tool Hub. Details and output appear when needed.

List shortcuts automatically scroll the focused tool into view. In search or settings inputs, letters and cursor keys keep their normal editing behavior. Leaving search preserves the query; Clear resets it. Press `?` for the complete keyboard reference. `m` and `--no-animation` stop both ambient effects.

## Included tools

| Tool | Working features |
| --- | --- |
| Hash Lab | Hash UTF-8 text or stream a file; SHA-256, SHA-512, SHA3-256, BLAKE2b; compare an expected checksum. |
| API Workbench | Send HTTP(S) requests with method, headers and body; inspect status, timing, response headers and JSON. |
| System Lens | CPU, RAM, uptime and disks; processes by memory; local TCP/UDP connections and port-to-process lookup where permissions allow. |
| Workspace Inspector | Read-only project inventory: file counts, extension-based languages, dependency-file locations and largest files. |

Open a tool → **Open tool** → fill its inputs → **Run**. Tools occupy the available workspace, not small modal dialogs. Forms use normal Tab/Shift+Tab traversal; Enter opens choices and arrow keys select. Text areas accept newlines. Run can also use Ctrl+Enter where the terminal supports it. Text/JSON reports can be explicitly exported to a new file, never over an existing file.

### Two tools at once

![Two independent tools with persistent navigation](docs/assets/workspace-dual.png)

Use **+ Tool** to choose a second tool. Each pane owns its inputs, output, process, **Run/Stop**, **Inputs/Output**, **Export**, **Expand/Split**, and **Close** actions. Wide terminals place the panes side by side; narrower ones stack them with scrolling when needed. One tool or an expanded pane fills the available width. Expanding one never stops the other; the numbered workspace buttons or F7 switch the active pane.

The sidebar remains accessible. F6 focuses it even from an input; choose a page using arrows and Enter, or 1–5. Navigation and Escape do not stop tasks or erase drafts. Return with **5**, **F7**, or the top-bar workspace indicator. A third tool does not replace an occupied slot: close one explicitly first. Stop affects only that pane; Close stops its process and discards its draft/report. Quitting stops all tools. Inputs and reports remain in memory, not a background service after exit.

Hash Lab, System Lens and Workspace Inspector stay local. API Workbench sends real requests only when you run it; modifying methods can change the target system. It verifies TLS, enforces response/time limits, masks header inputs, and only follows same-origin redirects when enabled. Reports may still contain sensitive response or local-system data. See [tool usage and limits](docs/tools.md).

The former Scope Planner, Snippet Vault, Report Forge, Wordlist Lab and Network Map placeholders are no longer shipped or offered in the offline catalogue. Already installed custom modules are not deleted automatically. `asashin new` still supports developing your own extensions outside the shipped tool collection.

## Use it from scripts

```bash
asashin list
asashin run hash-lab --param text=abc --param format=json
asashin run hash-lab --param source=file --param "file=./archive.zip"
asashin run workspace-inspector --param path=.
asashin run system-lens --param view=connections --param port=8080
asashin run api-workbench --describe
# Only contact a target you own or are authorized to test:
asashin run api-workbench --param url=http://127.0.0.1:8000/health
asashin catalog
asashin new my-workflow --output ./my-workflow
asashin new native-demo --language cpp --output ./native-demo
asashin doctor
```

`new` creates a fresh, editable module folder and refuses to overwrite an existing destination. It does not automatically install or publish the new module. `remove` removes downloaded modules; the four bundled tools remain available.

Choose an isolated storage location with the global flag before the command:

```bash
asashin --data-dir ./my-hub list
asashin --data-dir ./my-hub
```

Command output does not require an interactive terminal. Starting the full interface does. Failures return a nonzero exit code, and `--help` documents each command.

Use `asashin run <id> --describe` for available input names/defaults. `--params request.json` reads a JSON object; `--params -` reads it from stdin. Repeated `--param name=value` options override JSON values. Avoid putting credentials on a command line (shell history/process listings); use the masked form or stdin instead. Nothing saves request inputs automatically. Relative file paths resolve from the directory where you launched Asashin. `--param format=json` emits machine-readable JSON without terminal wrapping.

### C++ module starter

After `asashin new native-demo --language cpp`, enter its folder and run:

```bash
cmake -S . -B build
cmake --build build --config Release
cmake --install build --config Release --prefix .
python main.py
```

CMake and a C++17 compiler are needed only for native module development, not for the four bundled tools. The generated README explains how `manifest.json` inputs reach the Python launcher, how it invokes the C++ executable, and how to load/publish the module. [C++ template source](src/asashin/templates/cpp) · [Author guide](docs/modules.md#c-modules).

## Extend the Tool Hub

A module is a folder with a manifest and a Python entry point (which may launch a native executable). Start with `asashin new`, implement your workflow, then distribute it through a registry you control. Declarative manifest inputs automatically get the same keyboard-friendly form as built-in tools. Modules execute with your user permissions and are not sandboxed; install modules from authors you trust.

Configure the URL of a real registry JSON document, then explicitly refresh it:

```bash
asashin registry https://your-domain.example/asashin/registry.json
asashin catalog --refresh
asashin install your-module
```

The URL above is a placeholder. Nothing is fetched until you request a refresh or install a remote module. Remote archives require HTTPS and SHA-256 verification. See [the module author guide](docs/modules.md) for the manifest, registry format, archive structure, and publishing steps.

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check .
```

CI is configured to exercise Python 3.10, 3.12, and 3.13 on both Windows and Linux, including the C++ build test when CMake is available. The app uses [Textual](https://textual.textualize.io/) for the terminal interface, Rich for command output, HTTPX for HTTP requests, and psutil for portable system inspection.

Reproduce the terminal SVG previews with `python scripts/capture_previews.py`. Add `--png` if CairoSVG and a system Cairo library are installed. `python scripts/capture_motion.py` records the animated preview with CairoSVG and Pillow. [DESIGN.md](DESIGN.md) records the visual system; [UX-CONTRACT.md](UX-CONTRACT.md) records shared interaction behavior.

Measure rendering and interaction costs with `python scripts/benchmark_ui.py --output benchmark.json`. It compares motion on/off at 80×24, 140×46 and 200×60 without changing your workspace data. See [performance notes](docs/performance.md) for the before/after results and measurement limits.
