hastty 0.1.1__tar.gz

hastty-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jmleclercq
+
+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.

hastty-0.1.1/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: hastty
+Version: 0.1.1
+Summary: A terminal (TUI) viewer for your Home Assistant dashboards, with keyboard shortcuts to trigger commands.
+Author: jmleclercq
+License: MIT
+Project-URL: Homepage, https://github.com/jmleclercq/hastty
+Project-URL: Repository, https://github.com/jmleclercq/hastty
+Project-URL: Issues, https://github.com/jmleclercq/hastty/issues
+Project-URL: Changelog, https://github.com/jmleclercq/hastty/releases
+Keywords: home-assistant,homeassistant,tui,terminal,lovelace,dashboard,textual,smart-home
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=0.58.0
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: python-dotenv>=1.0
+Dynamic: license-file
+
+# hastty
+
+[![Version](https://img.shields.io/badge/version-0.1.1-blue)](https://github.com/jmleclercq/hastty/releases/tag/v0.1.1)
+[![License: MIT](https://img.shields.io/github/license/jmleclercq/hastty)](LICENSE)
+
+**A terminal (TUI) viewer for your Home Assistant dashboards — with keyboard
+shortcuts to trigger commands, no browser required.**
+
+`hastty` mirrors your existing Lovelace views (same views, same entities, same
+order) and lets you fire commands with the keyboard: toggle a light, run a
+scene, trigger a script or an automation — all from the terminal, with live
+state updates.
+
+<p align="center">
+  <img src="assets/screenshots/01-view-living-room.svg" width="820" alt="hastty showing the Living Room view, mirrored from Lovelace">
+</p>
+
+## Features
+
+- **Mirrors your Lovelace dashboards** — reuses the views and entities you
+  already defined in Home Assistant, no separate dashboard to maintain.
+- **Live state updates** — subscribes to `state_changed` events, no polling,
+  no manual refresh needed.
+- **Keyboard-first** — jump between views, move the selection, and fire
+  commands, all without touching the mouse.
+- **Custom global shortcuts** — bind any key to a specific service call
+  (e.g. a scene or script) directly from a config file.
+- **Single dependency on your side**: a Home Assistant Long-Lived Access
+  Token. No add-on, no extra integration to install on the HA side.
+
+## Screenshots
+
+**Activating an entity** — toggling `switch.tv` with <kbd>Enter</kbd>, state updates live:
+
+<img src="assets/screenshots/02-activate-entity.svg" width="820" alt="Activating an entity: toggling switch.tv with Enter, live state update">
+
+**Scenes view** — a second Lovelace dashboard, switched to with the <kbd>2</kbd> key:
+
+<img src="assets/screenshots/03-view-scenes.svg" width="820" alt="Scenes view, reached with the 2 key">
+
+**Help screen** — generic bindings plus the custom shortcuts from `config.yaml`:
+
+<img src="assets/screenshots/04-help.svg" width="820" alt="Help screen listing generic bindings and custom shortcuts">
+
+*(Captured against a local mock Home Assistant server, see
+[`tests/mock_ha_server.py`](tests/mock_ha_server.py) — no real HA instance
+required to try it out.)*
+
+## Installation
+
+```bash
+git clone https://github.com/jmleclercq/hastty.git
+cd hastty
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Configuration
+
+You need two things: the URL of your Home Assistant instance, and a
+**Long-Lived Access Token** (Home Assistant → your profile, bottom left →
+Security tab → "Long-lived access tokens" → Create Token).
+
+The simplest option — environment variables:
+
+```bash
+cp .env.example .env
+# edit .env: HA_URL=http://homeassistant.local:8123  and  HA_TOKEN=...
+```
+
+Or generate a config file with custom keyboard shortcuts:
+
+```bash
+hastty --init-config
+# edit ~/.config/hastty/config.yaml
+```
+
+The token can stay in `.env` (recommended, never committed) even if you use
+the YAML file for shortcuts.
+
+By default, only your **default** Lovelace dashboard is mirrored. If you use
+several dashboards and want all of them, set `include_extra_dashboards: true`
+under `homeassistant:` in `config.yaml`.
+
+## Run
+
+```bash
+hastty
+```
+
+## Usage
+
+| Key | Action |
+|---|---|
+| `1`–`9` | Jump directly to view N (in the order of your HA dashboards) |
+| `←` / `→` | Previous / next view |
+| `↑` / `↓` | Move the selection in the table |
+| `Enter` / `Space` | Activate the selected entity (toggle light/switch, run a scene/script, trigger an automation...) |
+| `r` | Refresh (re-syncs views and states) |
+| `?` | Help (also lists your custom shortcuts) |
+| `q` | Quit |
+
+### Custom shortcuts
+
+In `config.yaml`, under `keybindings`, you can define global keys (active
+from any view) that call a service directly — for example a scene or a
+script — without navigating to the entity first:
+
+```yaml
+keybindings:
+  - key: "g"
+    description: "Good night (scene)"
+    service: "scene.turn_on"
+    target:
+      entity_id: scene.good_night
+
+  - key: "a"
+    description: "Turn everything off (script)"
+    service: "script.turn_on"
+    target:
+      entity_id: script.turn_everything_off
+```
+
+## How it works
+
+- **Connection**: Home Assistant WebSocket API (`/api/websocket`),
+  authenticated with a Long-Lived Access Token (`hastty/client.py`).
+- **Dashboard mirroring**: calls `lovelace/config` for your default
+  dashboard (and, if `include_extra_dashboards` is enabled, every dashboard
+  from `lovelace/dashboards/list` too). Cards (`entities`, `glance`, `light`,
+  `vertical-stack`, `grid`, etc.) — whether under a classic top-level
+  `cards` list or under the newer per-section `sections` layout used by the
+  default dashboard editor since Home Assistant 2024.9 — are flattened into
+  per-view lists of `entity_id` (`hastty/lovelace.py`). The app doesn't try
+  to reproduce the visual layout of the cards, only the view → entities
+  organization.
+- **Commands**: `call_service` over WebSocket, either through the generic
+  per-domain action (Enter/Space on a selected entity) or through custom
+  shortcuts (`keybindings` in the config).
+
+## Known limitations
+
+- `area` cards (without an explicit entity list) aren't resolved into
+  individual entities yet.
+- The generic action (Enter/Space) calls a default service based on the
+  entity's domain (toggle for light/switch/fan..., turn_on for
+  scene/script, trigger for automation...); for a precise command with
+  parameters (color, brightness, cover position...), use a custom shortcut
+  with `service_data`.
+
+## Development
+
+```bash
+pip install -e .
+python tests/test_integration.py     # end-to-end test against a mock HA server
+python tests/capture_screenshots.py  # regenerate the SVG screenshots in assets/screenshots
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines before opening a PR.
+
+## License
+
+[MIT](LICENSE)

hastty-0.1.1/README.md

@@ -0,0 +1,164 @@
+# hastty
+
+[![Version](https://img.shields.io/badge/version-0.1.1-blue)](https://github.com/jmleclercq/hastty/releases/tag/v0.1.1)
+[![License: MIT](https://img.shields.io/github/license/jmleclercq/hastty)](LICENSE)
+
+**A terminal (TUI) viewer for your Home Assistant dashboards — with keyboard
+shortcuts to trigger commands, no browser required.**
+
+`hastty` mirrors your existing Lovelace views (same views, same entities, same
+order) and lets you fire commands with the keyboard: toggle a light, run a
+scene, trigger a script or an automation — all from the terminal, with live
+state updates.
+
+<p align="center">
+  <img src="assets/screenshots/01-view-living-room.svg" width="820" alt="hastty showing the Living Room view, mirrored from Lovelace">
+</p>
+
+## Features
+
+- **Mirrors your Lovelace dashboards** — reuses the views and entities you
+  already defined in Home Assistant, no separate dashboard to maintain.
+- **Live state updates** — subscribes to `state_changed` events, no polling,
+  no manual refresh needed.
+- **Keyboard-first** — jump between views, move the selection, and fire
+  commands, all without touching the mouse.
+- **Custom global shortcuts** — bind any key to a specific service call
+  (e.g. a scene or script) directly from a config file.
+- **Single dependency on your side**: a Home Assistant Long-Lived Access
+  Token. No add-on, no extra integration to install on the HA side.
+
+## Screenshots
+
+**Activating an entity** — toggling `switch.tv` with <kbd>Enter</kbd>, state updates live:
+
+<img src="assets/screenshots/02-activate-entity.svg" width="820" alt="Activating an entity: toggling switch.tv with Enter, live state update">
+
+**Scenes view** — a second Lovelace dashboard, switched to with the <kbd>2</kbd> key:
+
+<img src="assets/screenshots/03-view-scenes.svg" width="820" alt="Scenes view, reached with the 2 key">
+
+**Help screen** — generic bindings plus the custom shortcuts from `config.yaml`:
+
+<img src="assets/screenshots/04-help.svg" width="820" alt="Help screen listing generic bindings and custom shortcuts">
+
+*(Captured against a local mock Home Assistant server, see
+[`tests/mock_ha_server.py`](tests/mock_ha_server.py) — no real HA instance
+required to try it out.)*
+
+## Installation
+
+```bash
+git clone https://github.com/jmleclercq/hastty.git
+cd hastty
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Configuration
+
+You need two things: the URL of your Home Assistant instance, and a
+**Long-Lived Access Token** (Home Assistant → your profile, bottom left →
+Security tab → "Long-lived access tokens" → Create Token).
+
+The simplest option — environment variables:
+
+```bash
+cp .env.example .env
+# edit .env: HA_URL=http://homeassistant.local:8123  and  HA_TOKEN=...
+```
+
+Or generate a config file with custom keyboard shortcuts:
+
+```bash
+hastty --init-config
+# edit ~/.config/hastty/config.yaml
+```
+
+The token can stay in `.env` (recommended, never committed) even if you use
+the YAML file for shortcuts.
+
+By default, only your **default** Lovelace dashboard is mirrored. If you use
+several dashboards and want all of them, set `include_extra_dashboards: true`
+under `homeassistant:` in `config.yaml`.
+
+## Run
+
+```bash
+hastty
+```
+
+## Usage
+
+| Key | Action |
+|---|---|
+| `1`–`9` | Jump directly to view N (in the order of your HA dashboards) |
+| `←` / `→` | Previous / next view |
+| `↑` / `↓` | Move the selection in the table |
+| `Enter` / `Space` | Activate the selected entity (toggle light/switch, run a scene/script, trigger an automation...) |
+| `r` | Refresh (re-syncs views and states) |
+| `?` | Help (also lists your custom shortcuts) |
+| `q` | Quit |
+
+### Custom shortcuts
+
+In `config.yaml`, under `keybindings`, you can define global keys (active
+from any view) that call a service directly — for example a scene or a
+script — without navigating to the entity first:
+
+```yaml
+keybindings:
+  - key: "g"
+    description: "Good night (scene)"
+    service: "scene.turn_on"
+    target:
+      entity_id: scene.good_night
+
+  - key: "a"
+    description: "Turn everything off (script)"
+    service: "script.turn_on"
+    target:
+      entity_id: script.turn_everything_off
+```
+
+## How it works
+
+- **Connection**: Home Assistant WebSocket API (`/api/websocket`),
+  authenticated with a Long-Lived Access Token (`hastty/client.py`).
+- **Dashboard mirroring**: calls `lovelace/config` for your default
+  dashboard (and, if `include_extra_dashboards` is enabled, every dashboard
+  from `lovelace/dashboards/list` too). Cards (`entities`, `glance`, `light`,
+  `vertical-stack`, `grid`, etc.) — whether under a classic top-level
+  `cards` list or under the newer per-section `sections` layout used by the
+  default dashboard editor since Home Assistant 2024.9 — are flattened into
+  per-view lists of `entity_id` (`hastty/lovelace.py`). The app doesn't try
+  to reproduce the visual layout of the cards, only the view → entities
+  organization.
+- **Commands**: `call_service` over WebSocket, either through the generic
+  per-domain action (Enter/Space on a selected entity) or through custom
+  shortcuts (`keybindings` in the config).
+
+## Known limitations
+
+- `area` cards (without an explicit entity list) aren't resolved into
+  individual entities yet.
+- The generic action (Enter/Space) calls a default service based on the
+  entity's domain (toggle for light/switch/fan..., turn_on for
+  scene/script, trigger for automation...); for a precise command with
+  parameters (color, brightness, cover position...), use a custom shortcut
+  with `service_data`.
+
+## Development
+
+```bash
+pip install -e .
+python tests/test_integration.py     # end-to-end test against a mock HA server
+python tests/capture_screenshots.py  # regenerate the SVG screenshots in assets/screenshots
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines before opening a PR.
+
+## License
+
+[MIT](LICENSE)

hastty-0.1.1/hastty/__init__.py

@@ -0,0 +1,3 @@
+"""Home Assistant dashboard viewer for the terminal."""
+
+__version__ = "0.1.1"

hastty-0.1.1/hastty/__main__.py

@@ -0,0 +1,51 @@
+"""CLI entry point: `hastty` or `python -m hastty`."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from .app import HasttyApp
+from .config import DEFAULT_CONFIG_PATH, load_config, write_example_config
+
+
+def run() -> None:
+    parser = argparse.ArgumentParser(prog="hastty", description=__doc__)
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=None,
+        help=f"Path to the config file (default: {DEFAULT_CONFIG_PATH})",
+    )
+    parser.add_argument(
+        "--init-config",
+        action="store_true",
+        help="Generate an example config file and exit.",
+    )
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging to hastty.log")
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.basicConfig(filename="hastty.log", level=logging.DEBUG)
+
+    if args.init_config:
+        path = write_example_config(args.config)
+        print(f"Example config created: {path}")
+        print("Edit this file (or set HA_URL / HA_TOKEN) then run `hastty` again.")
+        return
+
+    try:
+        config = load_config(args.config)
+    except RuntimeError as exc:
+        print(f"Configuration error: {exc}", file=sys.stderr)
+        print("\nTip: run `hastty --init-config` to generate a starter config file.", file=sys.stderr)
+        sys.exit(1)
+
+    app = HasttyApp(config)
+    app.run()
+
+
+if __name__ == "__main__":
+    run()