Metadata-Version: 2.4
Name: bolok
Version: 0.2.0
Summary: Block websites with per-site daily time limits — hosts-based, daemon-enforced
License-Expression: MIT
Keywords: productivity,distraction-blocker,focus,hosts
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# bolok

Block any website with a daily time limit. One timed session per day, then a
24-hour lockout — enforced at the OS level, survives reboots.

Works on **macOS**, **Linux**, and **Windows**. Pure Python, no dependencies,
no browser extension, no account required.

## How it works

bolok redirects domains to `0.0.0.0` via the system hosts file and keeps it
in sync with a privileged background daemon that runs at boot and every 30
seconds.

- Add any site to your list with a per-site daily limit in minutes.
- `bolok start` opens a timed session — the site unblocks for that window.
- When the session ends (by timeout or `bolok stop`) the site re-blocks for a
  full 24-hour lockout, measured from the moment the session ended.
- Timers use absolute Unix timestamps, so sleep, reboot, or closing the
  terminal cannot extend a session.
- `bolok off <sitename>` is always available as an escape hatch.

Facebook (25 domains) is pre-loaded. Add anything else with `bolok list add`.

## Requirements

| Platform | Hosts file | Daemon | Extra |
|---|---|---|---|
| macOS | `/private/etc/hosts` | launchd | Xcode CLT (`xcode-select --install`) |
| Linux | `/etc/hosts` | systemd | Python 3.8+ |
| Windows | `System32\drivers\etc\hosts` | Task Scheduler | Python 3.8+, elevated terminal |

## Install

```bash
# macOS / Linux
pip install bolok
sudo bolok install

# Windows (elevated terminal)
pip install bolok
bolok install
```

**From source / dev:**
```bash
git clone https://github.com/pdfarhad/bolok.git && cd bolok
pip install -e .
sudo bolok install
```

**Upgrade:** `pip install --upgrade bolok && sudo bolok install`

## Quick start

```bash
# Enable blocking for all sites (Facebook is pre-loaded)
bolok on -a

# See per-site state and time remaining
bolok status

# Start your daily session for the single/default site
bolok start

# Done early? End the session (starts the 24h lockout from now)
bolok stop
```

## Managing your site list

```bash
# Show all sites with limits and current state
bolok list

# Add a site — short name auto-derived from the URL
bolok list add instagram.com 15       # 15 min/day
bolok list add https://twitter.com 20 # 20 min/day

# Update a site's daily limit
bolok list edit instagram 30

# Enable / disable blocking per site
bolok on instagram
bolok off instagram
```

## All commands

```
bolok on <sitename>               enable blocking for one site
bolok on -a                       enable blocking for all sites
bolok off <sitename>              disable blocking for one site
bolok off -a                      disable blocking for all sites
bolok start [<sitename>]          begin the one daily session
bolok stop  [<sitename>] [--yes]  end session early (costs the full 24h lockout)
bolok status                      per-site state, countdowns, daemon health
bolok limit [<sitename>] <min>    set session length (1-1440 minutes)
bolok browsers "Browser Name"     close these browsers when a block starts
bolok browsers off                stop auto-closing browsers
bolok list                        show all sites
bolok list add <url> <minutes>    add a new site
bolok list edit <sitename> <min>  update a site's daily limit
sudo bolok reset                  emergency: unblock hosts and reset all state
sudo bolok uninstall              remove daemon and CLI, keep state files
```

## Known limitations

- **macOS + Safari + iCloud Private Relay** — Private Relay bypasses
  hosts-based blocking. Turn it off in System Settings, or use another browser.
- **Windows Defender / antivirus** may flag hosts file modifications. Allow
  bolok if prompted; it only writes its own marker section.
- **Already-open tabs** keep loading until the browser re-resolves DNS. Use
  `bolok browsers "Firefox"` to close browsers automatically at block time.
- **VPNs and proxies** bypass it. This is friction, not a prison — you have
  admin rights. `bolok off <sitename>` is always available.
- **Domains are explicit.** Adding a site blocks `site.com`, `www.site.com`,
  and `m.site.com`. Other subdomains are not covered unless added manually.
  Facebook's built-in list covers 25 domains across facebook.com, fb.com,
  and messenger.com.
- **Windows enforcement granularity is 1 minute** (Task Scheduler minimum),
  vs 30 seconds on macOS and Linux.

## Reboot persistence

The hosts file is a plain file on disk — block entries survive reboots. A
privileged daemon re-enforces timer transitions that expired while the machine
was off:

| Platform | Daemon | Boot delay | Interval |
|---|---|---|---|
| macOS | launchd (`RunAtLoad = true`) | immediate | 30s |
| Linux | systemd timer | 5s | 30s |
| Windows | Task Scheduler | on startup | 60s |

## Development

```bash
pip install -e .                          # editable install
python3 -m unittest tests.test_bolok -v  # 64 unit tests (pure functions only)
```

Single-file codebase (`bolok.py`). All pure logic is unit-tested; the
imperative layer (file I/O, daemon wiring) is kept thin and verified manually.

## License

MIT — see [LICENSE](LICENSE)
