SellPL
af8b28f6c6
ci.yml calls `scripts/ci.sh` rather than restating the checks: a workflow that reimplements them becomes a second definition of "done", and the two drift. Android runs as a separate job. It fails when the SDK is absent while ci.sh skips it — a developer should not be blocked by a missing toolchain, but a silently skipped Android build in CI means regressions ship unnoticed. Every action is pinned to an exact version. LICENSE.md records that no licence is chosen yet, and why it is not a formality: the choice is upstream of the UI toolkit decision, since Slint is GPL-3.0. Co-Authored-By: Claude Code <noreply@anthropic.com>
122 lines
5.1 KiB
Markdown
122 lines
5.1 KiB
Markdown
# Blocker
|
|
|
|
A cross-platform app and website blocker for **Android, Windows and Linux**.
|
|
|
|
One shared Rust core owns every decision. Platform code observes the OS and
|
|
enforces what the core decides. That is what makes the same schedule behave
|
|
identically on all three, and it is testable rather than aspirational — the golden
|
|
decision tables in `tests/` are the parity contract, so a platform disagreeing
|
|
with the core fails the build instead of producing a bug report.
|
|
|
|
## Status
|
|
|
|
**M0 — repository bootstrap.** The core engine exists and is tested; nothing
|
|
enforces anything yet. No platform has a working build.
|
|
|
|
| Milestone | State |
|
|
|---|---|
|
|
| M0 repo bootstrap | in progress |
|
|
| M1 core engine | engine, lock timers and safety guarantees written and tested; storage has no I/O yet |
|
|
| M2-Linux | not started — daemon is a placeholder |
|
|
| M3-Android | not started |
|
|
| M4 conditions | not started |
|
|
| M5 websites | not started |
|
|
| M6 Strict Mode + friction | not started |
|
|
| M7 statistics, settings, releases | not started |
|
|
|
|
Milestone order is Linux-first rather than Android-first. See ADR-15.
|
|
|
|
## What it will do
|
|
|
|
- Schedules of apps, websites and keywords, with time windows, usage limits,
|
|
launch counts, Wi-Fi and location conditions
|
|
- Blocklist and allowlist modes, with strictest-wins when schedules overlap
|
|
- QuickBlock: block a chosen set for a chosen duration
|
|
- Strict Mode and a configurable friction ladder, so turning blocking off takes
|
|
deliberate effort in a weak moment while remaining always possible
|
|
- Local usage statistics
|
|
|
|
## What it will not do
|
|
|
|
This is a friction tool, not a wall. A user with root, ADB, safe mode, a factory
|
|
reset, or desktop admin rights can always remove it, and that is intended. Factory
|
|
reset, safe mode and OS recovery are never interfered with. The goal is to outlast
|
|
an impulse, not to defeat a determined decision.
|
|
|
|
There is also a hardcoded list of things that can never be blocked — the phone and
|
|
dialler, emergency calls and alerts, and on desktop the OS shell and the Settings
|
|
basics needed to keep the machine usable. There is no setting that changes it.
|
|
|
|
See [`docs/LIMITATIONS.md`](docs/LIMITATIONS.md) for all eight platform limits,
|
|
stated plainly, plus the shortfalls in the current code.
|
|
|
|
## Build and test
|
|
|
|
Requires a stable Rust toolchain. The toolchain is pinned in `rust-toolchain.toml`.
|
|
|
|
```sh
|
|
scripts/ci.sh # everything, stops at the first failure
|
|
scripts/ci.sh --keep-going # everything, summarises all failures
|
|
cargo test --workspace # tests only
|
|
cargo build --workspace # build only
|
|
scripts/size-check.sh # the 5 MB stripped daemon gate
|
|
```
|
|
|
|
Build artifacts go to `$HOME/.blocker-target`, outside the repository, so `target/`
|
|
never shows up in `git status` and can be deleted in one command. Override with
|
|
`CARGO_TARGET_DIR`.
|
|
|
|
Two checks skip on a machine without the relevant toolchain — Android without an
|
|
SDK, the secret scan without gitleaks. Both **skip loudly** and are listed in the
|
|
summary as not-passes. A skip is never reported as a pass.
|
|
|
|
## Layout
|
|
|
|
```
|
|
core/ the decision engine — pure, no OS calls, no dependencies
|
|
tests/ golden decision tables, and the engine purity check
|
|
desktop/daemon/ long-lived observer and enforcer (5 MB budget)
|
|
desktop/ui/ block-screen window, launched on demand
|
|
desktop/platform-linux/ ForegroundWatcher backends, enforcement
|
|
desktop/platform-windows/ same, Windows
|
|
android/ not started
|
|
docs/ architecture, ADRs, limitations, permissions, perf, testing
|
|
scripts/ ci.sh, size-check.sh
|
|
```
|
|
|
|
## Documentation
|
|
|
|
| Document | What it is for |
|
|
|---|---|
|
|
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | The purity contract, `next_wakeup`, and why the engine has no dependencies |
|
|
| [`docs/DECISIONS.md`](docs/DECISIONS.md) | 17 ADRs, including the two still awaiting a decision |
|
|
| [`docs/LIMITATIONS.md`](docs/LIMITATIONS.md) | What the OS will not let us do, and what is not built yet |
|
|
| [`docs/PERMISSIONS.md`](docs/PERMISSIONS.md) | Every permission, and what degrades without it |
|
|
| [`docs/PERF.md`](docs/PERF.md) | Section 5 budgets, and the measurements taken so far |
|
|
| [`docs/TESTING.md`](docs/TESTING.md) | The golden-table contract and the manual checklists |
|
|
| [`CLAUDE.md`](CLAUDE.md) | The project specification. It governs. |
|
|
|
|
## Performance budgets
|
|
|
|
| Metric | Target |
|
|
|---|---|
|
|
| Idle CPU | ~0%, no wakeups without events |
|
|
| Idle RAM (daemon) | ≤ 15 MB RSS |
|
|
| Block latency | ≤ 150 ms |
|
|
| Daemon binary | ≤ 5 MB stripped |
|
|
| APK size | ≤ 10 MB |
|
|
|
|
Currently measured: **0.279 MB** stripped daemon — a placeholder that prints two
|
|
lines. The meaningful number comes in M2-Linux. Enforced in CI from the first
|
|
commit by `scripts/size-check.sh`.
|
|
|
|
## Licence
|
|
|
|
**Not yet chosen.** See ADR-17. Choosing a licence is the owner's decision, and it
|
|
interacts with the UI toolkit choice in ADR-6 (Slint is GPL-3.0 or commercial), so
|
|
it is not something to settle by accident.
|
|
|
|
## A note on origin
|
|
|
|
Blocker is a functional reimplementation of the behaviour of existing app blockers.
|
|
It reuses no third-party name, logo, icon, copy, or screenshot — only behaviour. |