testsAndMisc/CLAUDE.md

# Copilot Instructions for testsAndMisc

## Project Overview

A mixed-language monorepo containing Python packages, Bash scripts, and misc automation. Actively-developed
components span personal productivity tools: alarm/shutdown scheduling, Linux system configuration, and
Android phone focus enforcement.

Extracted to their own repos:

- [`steam-backlog-enforcer`](https://github.com/kuhyx/steam-backlog-enforcer)
- [`screen-locker`](https://github.com/kuhyx/screen-locker)
- [`diet-guard`](https://github.com/kuhyx/diet-guard)
- [`wake-alarm`](https://github.com/kuhyx/wake-alarm)
- [`dufs-cloud`](https://github.com/kuhyx/dufs-cloud) — self-hosted dufs cloud:
  React web gallery (`web/`), Flutter app (`app/`), and the dufs/media setup
  scripts (`scripts/`). Extracted from `cloud_gallery/` + the
  `linux_configuration` dufs scripts + the standalone `dufs_client` repo. The
  live `media-cloud-sync` systemd units now run the scripts from
  `~/dufs-cloud/scripts/`.
- [`build-your-x`](https://github.com/kuhyx/build-your-x) — build-your-own-x
  difficulty ladder + `byox` progress tracker (crdt_sync-backed) and the builds
  themselves (`builds/`). Extracted from `python_pkg/byox_ladder/` + the
  standalone `~/build_your_x` builds. Lives at `~/build_your_x`.

Archived / unmaintained projects live in the sibling repository
[`testsAndMisc-archive`](https://github.com/kuhyx/testsAndMisc-archive).

## Repository Layout

| Path                   | Description                                                                                   |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| `python_pkg/`          | Python packages — each maintained subpackage lives here                                       |
| `billsplit/`           | Receipt bill-splitting Flutter app (Dart, e-paragon import, 100 % line coverage gate)         |
| `linux_configuration/` | Arch Linux setup, i3 config, system maintenance scripts                                       |
| `phone_focus_mode/`    | GPS-based Android focus enforcer (Bash, ADB, Magisk)                                          |
| `reverse_survivors/`   | Reverse Survivors — React/Vite game, you play the horde (TypeScript, 100 % coverage gate)     |
| `meta/`                | Repo-wide tooling: `pyproject.toml`, `requirements.txt`, `run.sh`, `lint_python.sh`, `.fvmrc` |
| `scripts/`             | Workspace-level helper scripts and pre-commit hooks (moved to `meta/scripts/`)                |
| `docs/`                | Reference docs; `docs/superpowers/` holds AI workflow artifacts                               |
| `third_party/`         | Vendored upstream skills/agents                                                               |

> **Note**: Root-level `pyproject.toml`, `requirements.txt`, `requirements.txt`, `run.sh`, and `.fvmrc`
> are symlinks into `meta/`. Edit files there, not the symlinks.

> **Note**: `billsplit/` is the only Flutter app in this repo, and the only place
> binaries are committed. Its platform launcher icons are build inputs, so they
> get the `.binary-allowlist` exception plus matching `!` overrides at the end of
> `.gitignore` — both are required, since an ignored file fails silently on
> `git add` rather than erroring. Adding another Flutter app here means repeating
> that pair. Icons come from the shared generator in `python_pkg/app_icons/`, and
> there is no local `dart format` / `flutter analyze` hook — Dart style is gated
> by `.github/workflows/billsplit-ci.yml` only. `billsplit/` holds **no Python**:
> its coverage gate lives at `python_pkg/billsplit_coverage/`, because the
> `check-python-location` hook requires every `.py` under `python_pkg/`.

## Architecture

### Python Packages (`python_pkg/`)

- **brother_printer/** — Brother printer status checker via CUPS and USB/network query
  - `check_brother_printer.py` — main status check
  - `cups_queue.py` / `cups_service.py` — CUPS integration
  - `network_query.py` / `usb_query.py` — device discovery
  - `tests/` — pytest tests

- **shared/** — Shared utilities across python_pkg subpackages
- **random_jpg/** — Random JPEG downloader utility
- **geo_cache/** — Geographic coordinate cache helper

### Phone Focus Mode (`phone_focus_mode/`)

Location-based app restriction for rooted Android. Automatically disables non-whitelisted apps within
500 m of home using ADB + Magisk.

- `focus_ctl.sh` / `focus_daemon.sh` — focus enforcement scripts
- `dns_enforcer.sh` — DNS-level blocking (netd cache restart for YouTube)
- `hosts_enforcer.sh` — `/etc/hosts` manipulation
- `launcher_enforcer.sh` — launcher restriction
- `workout_detector.sh` — workout detection integration
- `magisk_service.sh` — Magisk module hook (prevents module self-disabling)
- `config.sh` — configuration constants
- `deploy.sh` — ADB deployment script
- `systemd/` — systemd units for scheduling
- `lib/` — shared shell library functions

### Linux Configuration (`linux_configuration/`)

Arch Linux setup and ongoing system automation.

```
linux_configuration/
├── install_core_system.sh          # Core system installer
├── scripts/
│   ├── single_use/                 # One-time setup scripts
│   │   ├── fresh-install/
│   │   ├── features/
│   │   ├── fixes/
│   │   └── misc/
│   └── periodic_background/        # Ongoing daemons / scheduled scripts
│       ├── digital_wellbeing/      # Compulsive-opening blocker, LeechBlock
│       ├── hosts/                  # DNS/hosts guard and generation
│       ├── i3-configuration/       # i3 window manager config
│       ├── system-maintenance/     # Usage reporting, system checks
│       └── utils/
├── tests/                          # Shell-based test harness
└── test_results.log
```

Key scripts:

- `scripts/periodic_background/hosts/generate_hosts_file.sh` — Generates `/etc/hosts` blocklist
- `scripts/periodic_background/system-maintenance/bin/usage_report.py` — Daily usage report

### `meta/` — Repo-wide Tooling

All root-level config files are symlinks into `meta/`. Edit here:

- `meta/pyproject.toml` — ruff, mypy, pylint, bandit, pytest, coverage config
- `meta/requirements.txt` — runtime + dev dependencies
- `meta/run.sh` — usage report entrypoint + polling script profiler/diagnostics
- `meta/lint_python.sh` — manual lint helper
- `meta/scripts/` — pre-commit hook scripts (`check_no_binaries.sh`, `check_ai_evidence.sh`, etc.)

### `docs/superpowers/` — AI Workflow Artifacts

Pre-commit **requires** an evidence file for every commit that changes source code:

```
docs/superpowers/
├── evidence/         # ← Required: one JSON per commit touching code
│   └── template.json
├── contracts/        # Acceptance criteria / objective contracts per task
├── sessions/         # Append-only session logs (JSONL)
├── specs/            # Task specifications / design docs
├── plans/            # Implementation plans
├── memory/           # Persistent context (CONTEXT.md, etc.)
└── workflows/        # Agent workflow definitions
```

**Rule**: copy `docs/superpowers/evidence/template.json`, fill it in, and stage it with your code changes
before committing. The `ai-evidence-contract` hook will reject commits without it.

## Git Workflow

Work directly on `main` — no need to create branches for this repository. Commit and push straight to `main`.

### Hooks are mandatory

`core.hooksPath` points at the **tracked** directory `linux_configuration/.githooks/`,
so the hooks travel with the repo and cannot be missing on a clone. `.git/hooks/`
is unused and irrelevant — never run `pre-commit install`, which writes there and
is ignored (newer pre-commit refuses outright while `hooksPath` is set).

- `pre-commit` — shfmt + shellcheck + jscpd, then `pre-commit run --hook-stage pre-commit`
- `pre-push` — `pre-commit run --hook-stage pre-push` (prettier, ci-mirror, pytest-coverage)
  over the pushed commit range

Bootstrap a new machine or clone with:

```bash
./meta/scripts/install_hooks.sh          # wire hooks + install missing tools
./meta/scripts/install_hooks.sh --check  # verify, change nothing, exit 1 if incomplete
```

Both hooks **fail closed**: every external binary they invoke (`pre-commit`,
`prettier`, `shellcheck`, `shfmt`, `zsh`, `node`, `npm`, `python3`) is verified on
every run and auto-installed via `pacman` when possible; if it cannot be installed
non-interactively the commit or push aborts with the exact command to run. A missing
tool never means "skip the check" — that failure mode is why `prettier` was absent
for an unknown length of time without anyone noticing. The required-tool list lives
in `REQUIRED_TOOLS` in `linux_configuration/.githooks/lib/common.sh`; extend it when
adding a `language: system` hook.

Each hook also re-asserts `core.hooksPath`, so drift self-heals after one run. The
one gap it cannot close is a fresh clone where the config was never set and no hook
runs at all — that is exactly what `install_hooks.sh` is for.

## Development Workflow

do NOT run tests unless specifically instructed to do so or before committing
If tests fail on the same issue twice in a row, STOP and ask the user how to proceed instead of continuing to fix and retry.
ALWAYS confirm that the feature you add / bug you fixed behaves as it should by running the program after your changes (not tests!) and inspecting output comparing it with what user wanted, after confirming by yourself ask user if the program behaves as they intended
After running tests fix all coverage gaps and issues, do not ignore unless specifically instructed to do so

### AI Evidence Requirement

For every commit that touches `.py`, `.sh`, `.c`, `.go`, `.ts`, etc.:

1. Copy `docs/superpowers/evidence/template.json` → `docs/superpowers/evidence/<task-slug>-<date>.json`
2. Fill in the fields (objective, steps taken, verification result)
3. Stage and include it with your code changes

### Linting Tools (configured in `meta/pyproject.toml`)

- **ruff**: `select = ["ALL"]` — all rules enabled, Google docstrings
- **mypy**: `strict = true` with full type checking
- **pylint**: all checks enabled
- **coverage**: `fail_under = 100`, branch coverage required

## Code Conventions

### Python Style

- Use `from __future__ import annotations` for forward references
- Google docstring convention
- Absolute imports only (`ban-relative-imports = "all"`)
- Type hints required on all functions
- Private functions/modules prefixed with `_` (e.g., `_smart_plug.py`, `_process_game_event`)

### Shell Style

- Always `set -euo pipefail`
- Double-quote all variable expansions
- Avoid fork-heavy patterns: prefer `/proc`, `/sys`, bash builtins over `$(...)` in hot paths
- Use `jq`/`yq` for JSON/YAML, not `grep`/`awk`
- **NEVER embed Python program logic inline in a shell script** — no multi-line
  `python -c "..."` and no `python <<'PY' ... PY` heredocs that contain real logic.
  Put the code in a separate `.py` file so the repo's Python tooling (ruff, mypy,
  pylint, bandit, tests) applies to it, and invoke it as `python3 path/to/file.py "$arg"`.
  Resolve the path relative to the script (e.g. `"${0:A:h}/helper.py"` in zsh,
  `"$(dirname "$0")/helper.py"` in bash). The only permitted inline Python is a
  single-line availability/version probe with no logic, e.g. `python3 -c 'import kasa'`
  or `python3 -c 'import sys; print(sys.version_info[0])'`.

### Test Patterns

```python
# Type aliases for test dicts (keeps mypy happy)
Event = dict[str, Any]

# Mock external calls — never hit real APIs/filesystem
with patch("python_pkg.screen_locker.screen_lock.some_func") as mock:
    ...

# Use PropertyMock for property exceptions
type(mock_obj).property_name = PropertyMock(side_effect=TypeError())
```

### Branch Coverage Tips

- Use explicit `while True` + `try/except StopIteration` instead of `for` loops when iterator
  exhaustion needs coverage
- Mock threads/subprocesses to avoid slow tests
- Every `if`/`else` branch needs a corresponding test

## Key Files

- `meta/pyproject.toml` — All tool configs (ruff, mypy, pylint, pytest, coverage)
- `.pre-commit-config.yaml` — Pre-commit hook definitions
- `meta/requirements.txt` — Runtime + dev dependencies
- `.github/workflows/python-tests.yml` — CI: runs all pytest on `python_pkg/**` changes
- `.github/workflows/pre-commit.yml` — CI: runs pre-commit checks
- `docs/superpowers/evidence/template.json` — Template for AI evidence artifacts

## Per-File Ignores (in `meta/pyproject.toml`)

Test files allow: `S101` (assert), `PLR2004` (magic values), `S310`, `S607`, `PLC0415`