# Build Deb Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a local script that builds a Debian `.deb` package for throttled.

**Architecture:** The script stages a native Debian filesystem tree under a temporary directory, writes package metadata and maintainer scripts under `DEBIAN/`, installs the existing Python sources under `/usr/lib/throttled/`, installs `/etc/throttled.conf`, and creates a systemd unit that runs the system Python interpreter directly. It uses `dpkg-deb` only and does not run `pip` or create a virtualenv. On install, the package reloads systemd, enables `throttled.service`, and restarts it when systemd is active. Generated `.deb` files are release artifacts and are ignored by Git.

**Tech Stack:** POSIX shell, `dpkg-deb`, Python `unittest` for script verification.

---

### Task 1: Build Script Tests

**Files:**
- Create: `tests/test_build_deb.py`

- [x] **Step 1: Write failing tests**

Create `tests/test_build_deb.py` with tests that expect `scripts/build-deb.sh` to exist, print help, build a `.deb` into a temporary directory, and produce expected package metadata, file paths, and systemd maintainer scripts.

- [x] **Step 2: Verify red**

Run: `python3 -m unittest tests/test_build_deb.py`

Expected: fails because `scripts/build-deb.sh` does not exist.

### Task 2: Build Script

**Files:**
- Create: `scripts/build-deb.sh`

- [x] **Step 1: Implement script**

Create `scripts/build-deb.sh` that accepts `--output-dir`, `--version`, `--maintainer`, and `--help`. It should default to output directory `dist`, version `0.11+git.<short-sha>` when Git metadata exists, and maintainer `throttled maintainers <noreply@example.com>`. It should also include `postinst`, `prerm`, and `postrm` scripts for systemd service management.

- [x] **Step 2: Make script executable**

Run: `chmod +x scripts/build-deb.sh`.

### Task 3: README

**Files:**
- Modify: `README.md`
- Modify: `.gitignore`

- [x] **Step 1: Document build command**

Add a short section showing `./scripts/build-deb.sh`, where the `.deb` is written, the install command `sudo apt install ./dist/throttled_*.deb`, and the systemd service behavior.

- [x] **Step 2: Keep release artifacts out of Git**

Ignore generated `.deb` files so local builds and release artifacts are not committed to the repository.

### Task 4: Verification

**Files:**
- Test: `tests/test_build_deb.py`

- [x] **Step 1: Run tests**

Run: `python3 -m unittest tests/test_build_deb.py tests/test_dbus_helpers.py`

Expected: all tests pass.

- [x] **Step 2: Build package**

Run: `./scripts/build-deb.sh --output-dir /tmp/throttled-deb-test --version 0.11+test`

Expected: writes `/tmp/throttled-deb-test/throttled_0.11+test_all.deb`.

- [x] **Step 3: Inspect package**

Run: `dpkg-deb --info /tmp/throttled-deb-test/throttled_0.11+test_all.deb` and `dpkg-deb --contents /tmp/throttled-deb-test/throttled_0.11+test_all.deb`.

Expected: metadata includes `Depends: python3 (>= 3.9), python3-dbus-next, pciutils, kmod, upower, systemd`; the control archive includes executable `postinst`, `prerm`, and `postrm`; and contents include `/usr/lib/throttled/throttled.py`, `/usr/lib/throttled/mmio.py`, `/etc/throttled.conf`, and `/lib/systemd/system/throttled.service`.
