asher-cli 0.0.2__tar.gz → 0.0.4__tar.gz

asher_cli-0.0.4/.claude/hooks/block-env.ps1

@@ -0,0 +1,9 @@
+$raw = [Console]::In.ReadToEnd()
+try {
+    $j = $raw | ConvertFrom-Json
+    if ($j.file_path -match '\.env$') {
+        Write-Output "Blocked: .env contains real credentials — edit it manually if needed"
+        exit 2
+    }
+} catch {}
+exit 0

asher_cli-0.0.4/.claude/settings.json

@@ -0,0 +1,40 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Bash(git *)",
+      "Bash(python -c ' *)",
+      "Bash(python *)",
+      "mcp__plugin_context7_context7__resolve-library-id",
+      "mcp__plugin_context7_context7__query-docs",
+      "mcp__plugin_github_github__*",
+      "WebSearch",
+      "WebFetch",
+      "Bash(gh api *)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run ruff check --fix . --quiet; uv run ruff format . --quiet"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "powershell -NonInteractive -ExecutionPolicy Bypass -File .claude/hooks/block-env.ps1"
+          }
+        ]
+      }
+    ]
+  }
+}

asher_cli-0.0.4/.claude/skills/pylitterbot-ref/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: pylitterbot-ref
+description: Reference for the confirmed pylitterbot API surface as used in asher-cli. Load before making changes to robot command handling, monitoring, or adapter code. Prevents attribute-name guessing and eliminates runtime inspection commands.
+user-invocable: false
+---
+
+# pylitterbot Confirmed API Surface
+
+Load this skill whenever working on `asher/commands/`, `asher/monitoring/`, `asher/robot_adapters.py`, or anything that touches `robot.*`.
+
+## Robot attributes (LR4 confirmed)
+
+```python
+robot.name                    # str
+robot.serial                  # str
+robot.is_online               # bool
+robot.status                  # LitterBoxStatus enum
+robot.waste_drawer_level      # int, 0–100
+robot.sleep_mode_enabled      # bool — NOT "sleeping"
+robot.panel_lock_enabled      # bool — NOT "panel_lockout"
+robot.night_light_mode_enabled # bool
+robot.last_seen               # datetime | None
+```
+
+## Robot methods (all async, await required)
+
+```python
+await robot.refresh()
+await robot.start_cleaning()
+await robot.set_sleep_mode(enabled: bool)
+await robot.set_panel_lockout(enabled: bool)
+await robot.set_night_light_brightness(brightness: int)   # or:
+await robot.set_night_light_mode(mode: NightLightMode)
+await robot.get_activity_history(limit: int)  # -> list[Activity]
+```
+
+## Activity objects
+
+```python
+activity.timestamp   # datetime
+activity.action      # LitterBoxStatus enum (same as robot.status values)
+```
+
+## Model detection
+
+```python
+model_name = type(robot).__name__  # "LitterRobot4", "LitterRobot3", etc.
+```
+
+### Model-specific behaviour
+
+| Feature | LR3 | LR4 | LR5 |
+|---|---|---|---|
+| `set_sleep_mode()` | Simple on/off | Per-weekday schedule | TBD |
+| Night light | `set_night_light_brightness(int)` | `set_night_light_mode(NightLightMode)` | TBD |
+
+Use `asher/robot_adapters.py` for all model-specific dispatch — do not branch on `type(robot).__name__` inline in command handlers.
+
+## Timing / cloud queuing gotcha
+
+`sendLitterRobot4Command` returns when the cloud **queues** the command, not when the robot applies it.
+- Toggle commands (lock, unlock, night-light): use optimistic UI updates, not `refresh()` after the call.
+- State-unknown commands (sleep, wake): use `asyncio.sleep(2)` + `refresh()` + `_refresh_status()` as best-effort.
+
+## Safe attribute access pattern
+
+```python
+level = getattr(robot, "waste_drawer_level", None)
+if level is not None:
+    ...
+```
+
+Use `getattr(..., default)` or `try/except AttributeError` for any attribute not guaranteed on all models.

asher_cli-0.0.4/.claude/skills/release/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: release
+description: Cut a new asher-cli release. Runs preflight checks, bumps the version with bump-my-version, pushes the tag, and confirms the GitHub Actions release workflow is triggered. Invoke when user says "release", "cut a release", "bump version", "publish", or "ship".
+disable-model-invocation: true
+---
+
+# Release Skill
+
+Walk through the release process in order. Stop and report if any step fails.
+
+## Steps
+
+1. **Check working tree is clean**
+   Run `git status --porcelain`. If there are uncommitted changes, stop and tell the user to commit or stash them first.
+
+2. **Run full CI checks locally**
+   Run `uv run poe check` (lint + format + types + tests). All must pass before bumping.
+
+3. **Confirm the bump level**
+   Ask the user: patch / minor / major? Default to `patch` for bug fixes, `minor` for new features.
+
+4. **Bump the version**
+   Run `uv run bump-my-version bump <level>`.
+   This automatically:
+   - Updates `version` in `pyproject.toml`
+   - Runs `uv lock --no-sync` (pre-commit hook)
+   - Stages `uv.lock` and commits with a version bump message
+   - Creates a git tag `v<new_version>`
+
+5. **Push the commit and tag**
+   Run `git push origin main --tags`.
+   The `release.yml` GitHub Actions workflow triggers on new tags matching `v*`.
+
+6. **Confirm the workflow triggered**
+   Run `gh run list --workflow=release.yml --limit=3` and show the user the latest run status.
+
+7. **Report done**
+   Show the new version number and the expected PyPI URL once the workflow completes.
+
+## Notes
+- The pre-push hook (`.githooks/pre-push`) runs ruff + mypy — it must be active: `git config core.hooksPath .githooks`
+- If bump-my-version fails due to a dirty tree (e.g. uv.lock not staged), check that the `pre_commit_hooks` in `pyproject.toml` ran correctly
+- Never `--skip` the pre-push hook

asher_cli-0.0.4/.env.example

@@ -0,0 +1,3 @@
+LITTER_ROBOT_USER=email
+LITTER_ROBOT_PASSWORD=password
+ASHER_CLI_DEV_MODE=true

{asher_cli-0.0.2 → asher_cli-0.0.4}/.githooks/pre-push

@@ -10,7 +10,4 @@ uv run ruff format --check .
 echo "► mypy"
 uv run mypy asher/ --ignore-missing-imports
 
-echo "► pytest"
-uv run pytest tests/ -v --tb=short
-
 echo "✓ all checks passed"

{asher_cli-0.0.2 → asher_cli-0.0.4}/.github/workflows/ci.yml

@@ -12,13 +12,14 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
       - run: uv sync --dev
       - run: uv run ruff check .
       - run: uv run ruff format --check .
       - run: uv run mypy asher/ --ignore-missing-imports
 
+
   test:
     needs: lint
     strategy:
@@ -27,7 +28,7 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
       - run: uv sync --dev
       - run: uv run pytest tests/ -v --tb=short

asher_cli-0.0.4/.github/workflows/claude-code-review.yml

@@ -0,0 +1,44 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    if: |
+      github.event.pull_request.user.login == 'external-contributor' ||
+      github.event.pull_request.user.login == 'new-developer' ||
+      github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@428971d2ecd6e3a7cb0ee0da2a3a8b33fdb3678d # v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+

asher_cli-0.0.4/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@428971d2ecd6e3a7cb0ee0da2a3a8b33fdb3678d # v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr *)'
+

asher_cli-0.0.4/.github/workflows/coverage.yml

@@ -0,0 +1,24 @@
+name: Coverage
+
+on:
+  schedule:
+    - cron: "0 6 * * *"  # daily at 06:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - run: uv sync --dev
+      - name: Run tests with coverage
+        run: uv run pytest tests/ --cov=asher --cov-report=lcov --cov-report=term-missing
+      - name: Upload to Coveralls
+        uses: coverallsapp/github-action@5cbfd81b66ca5d10c19b062c04de0199c215fb6e # v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path-to-lcov: coverage.lcov

{asher_cli-0.0.2 → asher_cli-0.0.4}/.github/workflows/release.yml

@@ -16,13 +16,13 @@ jobs:
     outputs:
       version: ${{ steps.version.outputs.version }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
       - name: Extract version from branch name
         id: version
         run: echo "version=${GITHUB_REF_NAME#release/}" >> "$GITHUB_OUTPUT"
-      - uses: astral-sh/setup-uv@v3
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
       - run: uv build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: dist
           path: dist/
@@ -33,19 +33,19 @@ jobs:
     runs-on: ubuntu-latest
     environment: pypi
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
         with:
           name: dist
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
 
   github-release:
     name: Create GitHub Release
     needs: [build, publish]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
         with:
           name: dist
           path: dist/

asher_cli-0.0.4/CLAUDE.md

@@ -0,0 +1,193 @@
+# Asher CLI — CLAUDE.md
+
+Terminal dashboard for Litter Robot (LR3/LR4/LR5) via the Whisker cloud API.
+
+## Stack
+
+- **Python 3.10+**
+- **Textual** — async TUI framework (`textual>=0.47`)
+- **pylitterbot** — unofficial Whisker API wrapper (`pylitterbot>=3.0`)
+- **python-dotenv** — credential loading (`.env` fallback)
+- **keyring>=24** — OS credential store (Windows Credential Manager / macOS Keychain / Linux Secret Service)
+
+## Tooling
+
+- **uv** — dependency management and task runner (`uv sync`, `uv run`)
+- **poethepoet** — task aliases via `uv run poe <task>`
+- **ruff** — linter and formatter
+- **mypy** — static type checking
+- **pytest + pytest-asyncio + pytest-cov** — tests
+- **textual-dev** — CSS hot reload devtools
+- **watchfiles** — Python auto-restart on file change
+
+## Entry points
+
+```
+python app.py          # compatibility shim (calls asher/__main__.py)
+python -m asher        # run as module
+asher                  # after: uv sync && uv run asher  OR  pip install -e .
+```
+
+## Package structure
+
+```
+asher/
+  __init__.py
+  app.py            AsherApp class (thin orchestrator — composes mixins)
+  auth.py           LoginScreen modal (ModalScreen[tuple[str,str]]) — available, not primary flow
+  helpers.py        fmt_ago(), drawer_bar(), ts(), robot_model()  (pure, testable)
+  constants.py      STATUS_COLORS, ROBOT_MODELS
+  cats.py           CATS dict (ASCII art)
+  login_flow.py     LoginFlow state machine — inline email/password prompt in command bar
+  robot_protocol.py RobotProtocol structural Protocol for pylitterbot robot objects
+  robot_adapters.py RobotAdapter ABC + LR3/LR4/LR5 subclasses + make_adapter() factory
+  __main__.py       main() entry point
+  commands/
+    base.py         Command ABC, SlashCommand, CommandRegistry
+    __init__.py     CommandsMixin — all command classes + registry + dispatch
+  connection/       ConnectionMixin — keyring auth, _connect_worker, keyring helpers
+  monitoring/       MonitoringMixin — _poll_status_interval, _refresh_status
+  ui/               UIMixin — CSS, compose(), log helpers, cat helpers
+  slash-commands/   Convention doc
+
+tests/
+  testhelpers.py          unit tests for helpers.py
+  test_cats.py            CATS dict structure
+  test_auth.py            LoginScreen CSS / structure
+  test_auth_pilot.py      Textual Pilot integration tests for LoginScreen
+  test_app_pilot.py       Textual Pilot integration tests for AsherApp
+  test_commands_pilot.py  Textual Pilot integration tests for command dispatch
+  test_connection.py      keyring helper functions
+  test_connection_mixin.py ConnectionMixin structure
+  test_monitoring.py      MonitoringMixin async methods
+  test_ui.py              UIMixin constants, CSS, helper existence
+
+.github/workflows/
+  ci.yml            ruff + mypy + pytest on every push/PR
+```
+
+## Credentials
+
+Priority order on startup:
+
+1. **OS keyring** — set automatically after first interactive login
+2. **`.env` file** — fallback for existing users / CI
+3. **Inline login flow** — shown when no credentials found anywhere (email → password prompt in command bar)
+
+`.env` variable names (for fallback):
+```
+LITTER_ROBOT_USER=...
+LITTER_ROBOT_PASSWORD=...
+```
+
+Keyring service name: `asher-cli`, keys `email` and `password`.
+Helper functions in `asher/connection/__init__.py`: `_keyring_load()`, `_keyring_save()`, `_keyring_delete()`.
+
+## Command convention
+
+**Normal commands** (no prefix) — robot actions only:
+`clean`, `status`, `lock`, `unlock`, `sleep`, `wake`, `night-light on|off|auto`, `night-light-brightness <level>`, `history`, `clear`, `help`
+
+**Slash commands** (`/` prefix) — app management only:
+`/login`, `/logout`, `/exit`, `/robots`, `/robot <index|name>`
+
+**Special cases** (accepted both with and without `/`):
+`exit`, `quit`, `q` — exit the app
+
+Do not add robot-control commands as slash commands, and do not add app-management commands as bare commands.
+
+## Architecture
+
+**Status bar philosophy:**
+- **Top row** — ambient/settings info (robot name, online badge, night light mode + brightness). Not time-critical.
+- **Second row** — important operational state and cat data (drawer %, litter %, cat weight, last visit). Could be subject to change
+
+```
+AsherApp (textual.App)
+├── #status-bar          top dock — two rows (top: name/online/night-light/lock; bottom: drawer/litter/weight/visit)
+├── #main-area
+│   ├── #log             RichLog — scrollable event/command output
+│   └── #cat-panel       animated ASCII cat sidebar
+└── #bottom-dock         bottom dock
+    ├── #input-bar / #input-row   command prompt ("> " label + CmdInput)
+    └── #hint-bar        shortcut hints / login flow prompts
+
+LoginScreen (ModalScreen) — available in auth.py but not the primary auth path
+```
+
+## Key methods
+
+| Method | Purpose |
+|---|---|
+| `_connect_worker()` | `@work` — resolve credentials (keyring → .env → inline login), authenticate |
+| `_refresh_status()` | update all header widgets from robot state |
+| `_poll_status_interval()` | `@work` — poll fallback every 300s (5 min); WebSocket is primary |
+| `_tick_cat()` | advances multi-frame cat animation every 0.4s |
+| `_dispatch_command(command, args)` | `@work` — calls `command.run(app, args)` from the registry |
+| `on_input_submitted()` | routes input to login flow or `_dispatch_command` via `CommandRegistry` |
+| `_start_login_flow()` | begin inline email/password prompt in command bar |
+| `_cmd_logout()` | delete creds from keyring, disconnect |
+| `make_adapter(robot)` | factory in `robot_adapters.py` — returns correct `RobotAdapter` subclass |
+| `_log_ok/err/warn/info()` | timestamped log helpers |
+
+## Robot compatibility
+
+pylitterbot auto-detects robot type. Commands that differ per model are handled by `RobotAdapter` subclasses in `robot_adapters.py` — `make_adapter(robot)` returns the right one based on `type(robot).__name__`. Status-bar reads use `getattr(..., default)` for graceful degradation on older models. Tested API surface:
+
+- `robot.name`, `robot.serial`, `robot.is_online`
+- `robot.status` (LitterBoxStatus enum)
+- `robot.waste_drawer_level` (0–100)
+- `robot.sleep_mode_enabled`, `robot.panel_lock_enabled`, `robot.night_light_mode_enabled`
+- `robot.last_seen` (datetime)
+- `robot.refresh()`, `robot.start_cleaning()`
+- `robot.set_sleep_mode(bool)`, `robot.set_panel_lockout(bool)`
+- `robot.set_night_light_brightness(int)` or `robot.set_night_light_mode(NightLightMode)`
+- `robot.get_activity_history(limit=int)` → list of `Activity` objects with `.timestamp` and `.action` (`LitterBoxStatus` enum)
+
+## Development notes
+
+- Textual and pylitterbot are both asyncio-native — compose cleanly with `@work` tasks
+- All command execution runs in `@work` async workers to keep the UI responsive
+- Cat modes: `idle`, `happy`, `cleaning` (animated), `sleeping`, `error`, `full`
+- `VERSION` is read from `importlib.metadata.version("asher-cli")` — falls back to `"dev"` when running from source
+- The primary login path is the inline flow in `login_flow.py` (`LoginFlow` state machine: `IDLE` → `AWAITING_EMAIL` → `AWAITING_PASSWORD`). `LoginScreen` (`auth.py`) still exists as a modal but is not used in the current main flow.
+- `LoginScreen` uses `event.stop()` on `Input.Submitted` and `Button.Pressed` to prevent bubbling to the App's `on_input_submitted` (relevant if re-activating the modal path)
+
+### IoT command timing — optimistic UI updates
+
+`sendLitterRobot4Command` (and equivalents) return as soon as the cloud **queues** the command, not when the robot applies it. Calling `robot.refresh()` immediately after gets stale data. The fix for toggle/mode commands (lock, unlock, night-light on/off/auto) is to **update the status bar widget directly** after a successful API call, without waiting for a refresh — the WebSocket subscription will confirm the final state later. Do **not** add `asyncio.sleep(N)` + `refresh()` + `_refresh_status()` for these commands.
+
+Commands that need a confirmed cloud state before showing a result (e.g. sleep/wake, where the state isn't known from the command arg alone) use `asyncio.sleep(2)` + `refresh()` + `_refresh_status()` as a best-effort workaround, accepting the risk of briefly stale display.
+
+## Common tasks
+
+**Add a robot command:** create a class inheriting `Command` in `asher/commands/__init__.py`, implement `async def run(self, app, args)`, and call `_registry.register(MyCommand())`.
+
+**Add a slash command:** create a class inheriting `SlashCommand` (sets `prefix = "/"`), implement `async def run(self, app, args)`, register it, and document in `asher/slash-commands/__init__.py`.
+
+**Change poll interval:** `self.set_interval(300, ...)` in `on_mount`.
+
+**Add a new cat state:** add entry to `CATS` dict in `asher/cats.py` (str for static, list[str] for animated), then call `_set_cat("name", "label")`.
+
+**File naming convention:** no underscores in filenames (except Python-required `__init__.py` and `__main__.py`).
+
+## Dev workflow
+
+```bash
+uv sync                  # install all deps (including dev group)
+uv run poe dev           # run with CSS hot reload (textual --dev)
+uv run poe watch         # run with Python auto-restart on file change (watchfiles)
+uv run poe test          # run test suite
+uv run poe check         # ruff + mypy + pytest (same as CI)
+uv run poe fix           # auto-fix ruff issues
+```
+
+Pre-push hook (`.githooks/pre-push`) runs: ruff check → ruff format --check → mypy. Tests are not in the hook — run them manually.
+
+## Testing notes
+
+- Pilot-based integration tests use `app.run_test()` with `await pilot.pause()` before querying widgets
+- Helper app wrappers for screens must **not** start with `Test` (pytest will try to collect them); use e.g. `LoginTestApp`
+- Mock external deps with `unittest.mock.AsyncMock` for async robot/account methods
+- `from pylitterbot import Account` is a local import inside `_connect_worker` — patch it at `pylitterbot.Account`, not `asher.connection.Account`
+- Coverage: ~76% overall; main gaps are async exception paths and `_connect_worker` auth flow