# AGENTS.md

BAL — Bitcoin After Life, an Electrum plugin (inheritance / dead-man's-switch).
Source-of-truth docs: `README.md`, `HANDOFF.md`, `COMPATIBILITY.md`.

## Environments (critical)

Two separate venvs; using the wrong one is the #1 mistake.

- **Runtime env** (Electrum + PyQt6, has `electrum` importable):
  `source /home/steal/devel/bal/electrum/env/bin/activate`
  This is an editable install of the Electrum 4.8.0 checkout at
  `/home/steal/devel/bal/electrum`. Use it for anything that imports
  `electrum`, runs GUI code, or runs tests.
- **Lint venv** (repo-local `venv/`): ruff, black, flake8 only. It cannot
  import `electrum` or `PyQt6`. Do NOT use it to run tests.

The plugin's `bal/` directory is symlinked into
`electrum/electrum/plugins/bal` (internal-plugin install used during dev).

## Test & verify

Tests work **both** as standalone scripts and via pytest (tests use `def test_*`
naming and also have `if __name__ == "__main__"` blocks). Run a single file
directly:

```bash
source /home/steal/devel/bal/electrum/env/bin/activate
python3 tests/test_core_heirs.py        # core, no Qt needed
QT_QPA_PLATFORM=offscreen python3 tests/test_gui_common.py   # GUI tests need offscreen
```

Or run a batch with pytest (as `make-release.sh` does):

```bash
source /home/steal/devel/bal/electrum/env/bin/activate
QT_QPA_PLATFORM=offscreen python3 -m pytest tests/test_core_*.py -q
```

- Most core tests run offline (no wallet/network). Some files
  (`test_group_*.py`, `test_no_willexecutor_karen7.py`, `parallel_ping_test.py`)
  exercise will-executor/network flows and need the live servers — don't rely on
  them for quick verification.
- `tests/smoke_test.py` proves clean import under real Electrum:
  `QT_QPA_PLATFORM=offscreen python3 tests/smoke_test.py electrum.plugins.bal`
- `tests/external_zip_test.py` loads the built zip the way Electrum's plugin
  dialog does (`electrum_external_plugins.bal`); run it after `build_zip.py`.

## Lint / typecheck

- **Ruff is NOT clean** (hundreds of pre-existing errors in `bal/` and
  `tests/`). Do not run `--fix` wholesale and do not try to silence everything;
  just avoid adding new violations. Config: `pyproject.toml` (line-length 88,
  E501 ignored). Per-file ignores suppress `F403`/`F405` for the intentional
  `from .common import *` hub pattern in `bal/gui/qt/`.
- Lint via the repo venv: `/home/steal/devel/bal/bal-electrum-plugin/venv/bin/ruff`
- Typecheck: `pyright` (npm, `node_modules/`), config `pyrightconfig.json`
  (`extraPaths: ["../electrum"]`). Pyright reports many false positives on
  dynamically-attached attrs (e.g. `self.window`, `BalPlugin.*`); don't chase
  them.

## Architecture

- `bal/core/` = GUI-free logic (`heirs.py`, `will.py`, `willexecutors.py`,
  `plugin_base.py`, `util.py`, `checkalive.py`, `reminders.py`,
  `input_rules.py`).
  Must never import Qt.
- `bal/gui/qt/` = PyQt6 layer. `window.py` is the per-wallet controller,
  `plugin.py` is the Electrum `@hooks` entry. `qt.py` is a zipimport shim.
  `common.py` uses `import *` intentionally (ruff suppresses F403/F405 here);
  `bal/gui/qt/*.py` all import from it.
- `bal/cli/` = headless command-line layer (no Qt). `plugin.py` is the daemon
  entry point, `commands.py` registers `bal_*` commands with Electrum.
- `bal/wallet_util/` = wallet helper utilities for Qt and core.
- `bal/qt.py` and `bal/cmdline.py` are thin shims that Electrum discovers
  via `manifest.json`; they import the real `Plugin` class via `importlib`.
- `bal/manifest.json` = version source of truth (Electrum reads it; also read by
  `make-release.sh`).
- Compatibility constraint: must support Electrum **4.7.2 and 4.8.0**; the DB
  registration API differs between them (`json_db.register_dict` vs
  `stored_dict.register_name`).

## Build / release

```bash
python3 build_zip.py   # -> bal-electrum-plugin.zip (deterministic, prints sha256)
./make-release.sh [v0.x.y]   # bump manifest version, tag, sign, push Gitea release
```

- `make-release.sh` requires gpg and Gitea credentials (`~/.git-credentials`
  or `GITEA_USER`/`GITEA_TOKEN`). It bumps `bal/manifest.json` — bump the
  version there, never invent a new source of truth.
- Remote is Gitea (`origin` = bitcoin-after.life). `.env` holds a Gitea token
  (gitignored, never commit it).