sethLabels/sethlabels-docs/plans/2026-04-29-packaging-implementation.md

# sethLabels Packaging 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:** Implement the deployment-fork packaging pipeline defined by `sethlabels-docs/specs/2026-04-29-packaging-design.md` — produce installable `.deb` + AppImage artifacts on Debian-family Linux and a Homebrew tap formula for macOS, while honoring strict-zero-source-patches (Invariant I1).

**Architecture:** All sethLabels content lives in NEW top-level dirs (`scripts/`, `packaging/`, `sethlabels-docs/`, `tests-impl/`) and one new repo-root file (`README.sethlabels.md`). The Homebrew tap lives in a separate Gitea repo (`homebrew-tap`). Pure-logic scripts (`compute-version.sh`, `check-no-upstream-edits.sh`, `deps-debian.sh`) are TDD'd with `bats-core`. Build scripts (`build-deb.sh`, `build-appimages.sh`) are validated by inline smoke tests (T1–T4 from spec §10) against the artifacts they produce.

**Tech Stack:** Bash (with `set -euo pipefail`), CMake/CPack (already present upstream), `linuxdeploy` + `linuxdeploy-plugin-qt` (for AppImage bundling), `bats-core` (shell test framework, `apt install bats`), Homebrew Formula DSL (Ruby).

**Spec discrepancies to fix during implementation:**

1. **Spec §5.2 omits `-D CPACK_PACKAGE_NAME=glabels-qt`.** Upstream `CMakeLists.txt:86` sets `CPACK_PACKAGE_NAME=glabels` — without the override the `.deb` would be named `glabels_${VERSION}_amd64.deb`, contradicting decision D6. Task 7 adds the override.
2. **Spec §F9 requires pinned linuxdeploy versions, no specific tag named.** Task 5 has the implementer query GitHub for the latest release tag of `linuxdeploy/linuxdeploy` and `linuxdeploy/linuxdeploy-plugin-qt`, then hardcode those tags in `scripts/lib/linuxdeploy.sh`.
3. **Spec §2 calls `.gitignore` "a one-time scaffold-time touch", but §5.5's allowlist permits ongoing edits.** Task 1 adds new entries (`build/`, `scripts/.cache/`, `*.AppImage`); the guardrail allows this since `.gitignore` is in the allowlist.

**Plan-execution context:** This plan is best executed in a worktree via `superpowers:using-git-worktrees`. The plan does not create the worktree itself — the executor sets that up before starting Task 1.

---

### File Structure

| Path | Responsibility | Created in |
|------|----------------|------------|
| `scripts/compute-version.sh` | Emit `<upstream-tag>-seth<N>` to stdout. Pure logic. | Task 2 |
| `scripts/check-no-upstream-edits.sh` | Guardrail enforcing I1; exits 1 on any non-allowlisted upstream-file edit. | Task 3 |
| `scripts/lib/deps-debian.sh` | Single source of truth for build deps; sourceable + executable. | Task 4 |
| `scripts/lib/linuxdeploy.sh` | Bootstrap + cache `linuxdeploy` and `linuxdeploy-plugin-qt`. | Task 5 |
| `packaging/deb-metadata.env` | Maintainer + section + homepage for CPack DEB. | Task 6 |
| `packaging/appimage-recipe.env` | linuxdeploy plugin allowlist + exclude list. | Task 6 |
| `packaging/changelog.md` | Human-readable per-release notes. | Task 6 |
| `scripts/build-deb.sh` | Driver: deps → guardrail → version → cmake → cpack → smoke (T1, T2). | Task 7 |
| `scripts/build-appimages.sh` | Driver: deps → guardrail → version → cmake → linuxdeploy x2 → smoke (T3, T4). | Task 8 |
| `scripts/README.md` | Operator-facing run instructions. | Task 9 |
| `README.sethlabels.md` | Repo-root entry point: fork purpose, install methods, build path, link to spec. | Task 10 |
| `tests-impl/test-compute-version.bats` | Bats tests for `compute-version.sh`. | Task 2 |
| `tests-impl/test-check-no-upstream-edits.bats` | Bats tests for `check-no-upstream-edits.sh`. | Task 3 |
| `tests-impl/test-deps-debian.bats` | Bats tests for `deps-debian.sh`. | Task 4 |
| `tests-impl/run-all.sh` | One-shot runner: `bats tests-impl/*.bats`. | Task 1 |
| `~/bin/homebrew-tap/Formula/glabels-qt.rb` | Brew formula (separate repo). | Task 11 |
| `~/bin/homebrew-tap/README.md` | Tap install instructions. | Task 11 |

**Why `tests-impl/` and not `tests/`?** Upstream has `test-data/` at root but no `tests/`. Naming our test dir `tests-impl/` (impl = implementation tests, sethLabels-namespaced) avoids any visual collision and keeps the strict-zero boundary unmistakable.

---

## Task 1: Directory skeleton + .gitignore additions

**Files:**
- Modify: `.gitignore` (append three new patterns inside the existing sethLabels section)
- Create: `scripts/`, `scripts/lib/`, `packaging/`, `tests-impl/` (empty for now; populated by later tasks)
- Create: `tests-impl/run-all.sh`

- [ ] **Step 1: Verify clean working tree before starting**

```bash
git status
```

Expected: `nothing to commit, working tree clean` and the current branch is `main` (or your worktree branch). If dirty, stop and resolve before proceeding.

- [ ] **Step 2: Create the directory skeleton**

```bash
mkdir -p scripts/lib packaging tests-impl
```

- [ ] **Step 3: Append build-artifact patterns to `.gitignore`**

Open `.gitignore` and **append** to the existing `# === sethLabels (deployment fork) additions ===` section (do NOT modify upstream entries above it):

```
# Build outputs (out-of-tree)
build/

# linuxdeploy + plugin caches (downloaded by scripts/lib/linuxdeploy.sh on first AppImage build)
scripts/.cache/

# Locally-produced AppImage artifacts
*.AppImage
```

- [ ] **Step 4: Verify the strict-zero allowlist still covers .gitignore**

```bash
grep '\\.gitignore' sethlabels-docs/specs/2026-04-29-packaging-design.md
```

Expected: matches in §5.5 `allowed_pattern` and the §2 invariants table — `.gitignore` is allowlisted, so this edit does not violate I1.

- [ ] **Step 5: Create `tests-impl/run-all.sh`**

```bash
cat > tests-impl/run-all.sh <<'EOF'
#!/usr/bin/env bash
# Run the full bats test suite for sethLabels packaging scripts.
# Requires: bats (apt install bats).
set -euo pipefail
cd "$(dirname "$0")"
exec bats *.bats
EOF
chmod +x tests-impl/run-all.sh
```

- [ ] **Step 6: Verify the new dirs are tracked-empty (or .keep'd)**

Empty dirs aren't tracked by git. We want the dirs visible after `git add`, so create a placeholder where needed and tracked-empty elsewhere is fine since later tasks populate them.

```bash
ls -la scripts/ scripts/lib/ packaging/ tests-impl/
```

Expected: each dir exists; `tests-impl/run-all.sh` is present and executable.

- [ ] **Step 7: Commit**

```bash
git add .gitignore scripts/ packaging/ tests-impl/
git commit -m "chore: add packaging directory skeleton + .gitignore build patterns"
```

(`scripts/` and `packaging/` will commit only if non-empty — if not, that's fine; later tasks add files and push them.)

---

## Task 2: `scripts/compute-version.sh` (TDD)

**Files:**
- Test: `tests-impl/test-compute-version.bats`
- Create: `scripts/compute-version.sh`

**What it does:** Emits `<upstream-tag>-seth<N>` to stdout, where `<upstream-tag>` = `git describe --tags --abbrev=0 upstream/master` and `<N>` = count of existing `<upstream-tag>-seth*` tags + 1. Pure logic, idempotent under serial single-author releases (spec §5.4).

- [ ] **Step 1: Confirm `bats` is installed**

```bash
which bats || sudo apt install -y bats
bats --version
```

Expected: prints a version (>= 1.7).

- [ ] **Step 2: Write the failing tests**

Create `tests-impl/test-compute-version.bats`:

```bash
#!/usr/bin/env bats

# Tests for scripts/compute-version.sh
# Invokes the real script against the real repo state.

setup() {
  REPO_ROOT="$(git rev-parse --show-toplevel)"
  SCRIPT="$REPO_ROOT/scripts/compute-version.sh"
}

@test "script exists and is executable" {
  [ -x "$SCRIPT" ]
}

@test "output matches '<upstream-tag>-seth<N>' format" {
  run "$SCRIPT"
  [ "$status" -eq 0 ]
  [[ "$output" =~ ^[0-9].+-seth[0-9]+$ ]]
}

@test "N=1 when no prior seth-tags exist" {
  # This test assumes a clean tag db. If there ARE existing seth-tags, this
  # test will report N>1 and that's the correct value. Skipped if any
  # upstream-tag-seth* tag already exists.
  upstream_tag=$(git describe --tags --abbrev=0 upstream/master)
  existing=$(git tag --list "${upstream_tag}-seth*" | wc -l)
  if [ "$existing" -gt 0 ]; then
    skip "seth-tags already exist (count=$existing); N=1 invariant only holds on first release"
  fi
  run "$SCRIPT"
  [ "$status" -eq 0 ]
  [[ "$output" == "${upstream_tag}-seth1" ]]
}

@test "N increments past existing seth-tags" {
  upstream_tag=$(git describe --tags --abbrev=0 upstream/master)
  # Create a fake seth-tag for this test, then clean up.
  fake_tag="${upstream_tag}-seth99"
  git tag "$fake_tag" 2>/dev/null || true
  run "$SCRIPT"
  git tag -d "$fake_tag" >/dev/null 2>&1 || true
  [ "$status" -eq 0 ]
  # Existing count was at least 1 (our fake), so N >= 2.
  n="${output##*-seth}"
  [ "$n" -ge 2 ]
}

@test "fails cleanly when upstream/master ref is missing" {
  # Run in a temp git repo with no upstream remote.
  tmp=$(mktemp -d)
  cd "$tmp"
  git init -q
  git commit --allow-empty -m "init" -q
  run "$SCRIPT"
  cd "$REPO_ROOT"
  rm -rf "$tmp"
  [ "$status" -ne 0 ]
}
```

- [ ] **Step 3: Run tests; confirm they fail**

```bash
bats tests-impl/test-compute-version.bats
```

Expected: all tests fail because `scripts/compute-version.sh` doesn't exist yet. The first test (`script exists and is executable`) reports `[ -x "$SCRIPT" ]` failed.

- [ ] **Step 4: Write the minimal script to pass the tests**

Create `scripts/compute-version.sh`:

```bash
#!/usr/bin/env bash
# Emit "<upstream-tag>-seth<N>" version string to stdout.
# Pure logic: no side effects.
#
# CALLER RESPONSIBILITY (per spec §5.4): the local tag db must be fresh.
# If invoked outside the release flow, run `git fetch origin --tags` first
# or risk a stale <N> value.
#
# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.4 (D4)
set -euo pipefail

upstream_tag=$(git describe --tags --abbrev=0 upstream/master)
existing_count=$(git tag --list "${upstream_tag}-seth*" | wc -l | tr -d ' ')
next_n=$((existing_count + 1))
echo "${upstream_tag}-seth${next_n}"
```

```bash
chmod +x scripts/compute-version.sh
```

- [ ] **Step 5: Run tests; confirm they pass**

```bash
bats tests-impl/test-compute-version.bats
```

Expected: all tests pass (or the `N=1` test reports `skip` if you've already tagged a release in your worktree, which is fine).

- [ ] **Step 6: Sanity-check the actual output**

```bash
./scripts/compute-version.sh
```

Expected: `3.99-master618-seth1` (or higher `seth<N>` if you've tagged before). The `3.99-master618` part should match `git describe --tags --abbrev=0 upstream/master`.

- [ ] **Step 7: Commit**

```bash
git add scripts/compute-version.sh tests-impl/test-compute-version.bats
git commit -m "feat: add compute-version.sh + bats tests"
```

---

## Task 3: `scripts/check-no-upstream-edits.sh` (TDD)

**Files:**
- Test: `tests-impl/test-check-no-upstream-edits.bats`
- Create: `scripts/check-no-upstream-edits.sh`

**What it does:** Enforces Invariant I1. Exits 0 silently on clean state; exits 1 with a clear error listing violations otherwise. Catches BOTH committed and uncommitted edits (spec §5.5).

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

Create `tests-impl/test-check-no-upstream-edits.bats`:

```bash
#!/usr/bin/env bats

# Tests for scripts/check-no-upstream-edits.sh

setup() {
  REPO_ROOT="$(git rev-parse --show-toplevel)"
  SCRIPT="$REPO_ROOT/scripts/check-no-upstream-edits.sh"
  TMP_REPO=""
}

teardown() {
  if [ -n "$TMP_REPO" ] && [ -d "$TMP_REPO" ]; then
    rm -rf "$TMP_REPO"
  fi
}

# --- Helpers ---

# Build a minimal disposable repo that mimics the sethLabels structure with a
# local "upstream/master" ref. Returns its path via stdout.
make_test_repo() {
  local tmp=$(mktemp -d)
  cd "$tmp"
  git init -q -b master
  git config user.email "test@test"
  git config user.name "test"
  # Pretend-upstream files
  echo "upstream content" > UPSTREAM_FILE.md
  echo "real source" > glabels-source.cpp
  git add UPSTREAM_FILE.md glabels-source.cpp
  git commit -m "upstream base" -q
  # Create a local "upstream/master" ref pointing here
  git update-ref refs/remotes/upstream/master HEAD
  # Create a feature branch for sethLabels content
  git checkout -q -b main
  echo "$tmp"
}

# --- Tests ---

@test "script exists and is executable" {
  [ -x "$SCRIPT" ]
}

@test "exits 0 on clean state with only allowlisted committed changes" {
  TMP_REPO=$(make_test_repo)
  cd "$TMP_REPO"
  mkdir -p scripts packaging sethlabels-docs .claude/handoffs
  echo "test" > CLAUDE.md
  echo "test" > scripts/something.sh
  echo "test" > packaging/x.env
  echo "test" > sethlabels-docs/spec.md
  echo "" >> .gitignore
  git add -A
  git commit -m "sethLabels additions" -q

  run "$SCRIPT"
  [ "$status" -eq 0 ]
  [ -z "$output" ]
}

@test "exits 1 when an upstream file is committed-modified" {
  TMP_REPO=$(make_test_repo)
  cd "$TMP_REPO"
  echo "evil edit" >> glabels-source.cpp
  git add glabels-source.cpp
  git commit -m "BAD: edit upstream file" -q

  run "$SCRIPT"
  [ "$status" -eq 1 ]
  [[ "$output" == *"glabels-source.cpp"* ]]
  [[ "$output" == *"strict-zero"* ]]
}

@test "exits 1 when an upstream file has uncommitted working-tree edits" {
  TMP_REPO=$(make_test_repo)
  cd "$TMP_REPO"
  echo "uncommitted evil edit" >> glabels-source.cpp

  run "$SCRIPT"
  [ "$status" -eq 1 ]
  [[ "$output" == *"glabels-source.cpp"* ]]
}

@test "exits 0 when only .gitignore is modified (allowlisted)" {
  TMP_REPO=$(make_test_repo)
  cd "$TMP_REPO"
  echo "*.tmp" >> .gitignore
  git add .gitignore
  git commit -m "extend gitignore" -q

  run "$SCRIPT"
  [ "$status" -eq 0 ]
}

@test "exits 0 when only CLAUDE.md / IDEA.md / DECISIONS.md / README.sethlabels.md are added" {
  TMP_REPO=$(make_test_repo)
  cd "$TMP_REPO"
  echo "x" > CLAUDE.md
  echo "x" > IDEA.md
  echo "x" > DECISIONS.md
  echo "x" > README.sethlabels.md
  git add -A
  git commit -m "add sethLabels root docs" -q

  run "$SCRIPT"
  [ "$status" -eq 0 ]
}
```

- [ ] **Step 2: Run tests; confirm they fail**

```bash
bats tests-impl/test-check-no-upstream-edits.bats
```

Expected: all tests fail (script doesn't exist).

- [ ] **Step 3: Write the script to pass**

Create `scripts/check-no-upstream-edits.sh`:

```bash
#!/usr/bin/env bash
# Enforce Invariant I1: no upstream-tracked file is ever edited.
# Exits 0 on clean state, 1 on violation.
#
# Catches BOTH committed drift (commits unique to HEAD vs upstream/master)
# AND working-tree drift (uncommitted local edits to tracked files).
#
# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.5 (I1, F1)
set -euo pipefail

# Allowlist: files/dirs sethLabels is permitted to add or modify.
# `.gitignore` is the one upstream-file exception (called out in spec §2).
allowed_pattern='^\.gitignore$|^\.claude/|^scripts/|^packaging/|^sethlabels-docs/|^tests-impl/|^README\.sethlabels\.md$|^CLAUDE\.md$|^IDEA\.md$|^DECISIONS\.md$'

committed=$(git diff --name-only upstream/master..HEAD 2>/dev/null || true)
working=$(git diff --name-only HEAD 2>/dev/null || true)

all_changes=$(printf "%s\n%s\n" "$committed" "$working" | sort -u | sed '/^$/d')

if [ -z "$all_changes" ]; then
  exit 0
fi

violations=$(echo "$all_changes" | grep -vE "$allowed_pattern" || true)

if [ -n "$violations" ]; then
  echo "ERROR: strict-zero policy violated. The following upstream files have been modified:"
  echo "$violations"
  echo ""
  echo "See sethlabels-docs/specs/2026-04-29-packaging-design.md §I1."
  exit 1
fi

exit 0
```

```bash
chmod +x scripts/check-no-upstream-edits.sh
```

- [ ] **Step 4: Run tests; confirm they pass**

```bash
bats tests-impl/test-check-no-upstream-edits.bats
```

Expected: all 6 tests pass.

- [ ] **Step 5: Run the guardrail against the real repo**

```bash
./scripts/check-no-upstream-edits.sh && echo "CLEAN"
```

Expected: prints `CLEAN`. If it errors, you've accidentally touched an upstream file — investigate before continuing.

- [ ] **Step 6: Commit**

```bash
git add scripts/check-no-upstream-edits.sh tests-impl/test-check-no-upstream-edits.bats
git commit -m "feat: add check-no-upstream-edits.sh + bats tests (enforces I1)"
```

---

## Task 4: `scripts/lib/deps-debian.sh` (TDD)

**Files:**
- Test: `tests-impl/test-deps-debian.bats`
- Create: `scripts/lib/deps-debian.sh`

**What it does:** Single source of truth for build deps (spec §5.1). When sourced, exposes `SETHLABELS_DEPS` array. When executed, checks each dep is installed and prints an actionable `apt install ...` command if anything is missing.

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

Create `tests-impl/test-deps-debian.bats`:

```bash
#!/usr/bin/env bats

# Tests for scripts/lib/deps-debian.sh

setup() {
  REPO_ROOT="$(git rev-parse --show-toplevel)"
  SCRIPT="$REPO_ROOT/scripts/lib/deps-debian.sh"
}

@test "script exists and is executable" {
  [ -x "$SCRIPT" ]
}

@test "sourceable: exposes SETHLABELS_DEPS array" {
  source "$SCRIPT"
  [ "${#SETHLABELS_DEPS[@]}" -gt 5 ]
}

@test "SETHLABELS_DEPS contains core build tools" {
  source "$SCRIPT"
  [[ " ${SETHLABELS_DEPS[*]} " == *" cmake "* ]]
  [[ " ${SETHLABELS_DEPS[*]} " == *" ninja-build "* ]]
  [[ " ${SETHLABELS_DEPS[*]} " == *" build-essential "* ]]
}

@test "SETHLABELS_DEPS contains Qt6 libraries" {
  source "$SCRIPT"
  [[ " ${SETHLABELS_DEPS[*]} " == *" qt6-base-dev "* ]]
  [[ " ${SETHLABELS_DEPS[*]} " == *" qt6-svg-dev "* ]]
  [[ " ${SETHLABELS_DEPS[*]} " == *" qt6-tools-dev "* ]]
}

@test "SETHLABELS_DEPS contains barcode + zlib deps" {
  source "$SCRIPT"
  [[ " ${SETHLABELS_DEPS[*]} " == *" zlib1g-dev "* ]]
  [[ " ${SETHLABELS_DEPS[*]} " == *" libqrencode-dev "* ]]
  [[ " ${SETHLABELS_DEPS[*]} " == *" libzint-dev "* ]]
}

@test "SETHLABELS_DEPS contains packaging tools" {
  source "$SCRIPT"
  [[ " ${SETHLABELS_DEPS[*]} " == *" dpkg-dev "* ]]
  [[ " ${SETHLABELS_DEPS[*]} " == *" fakeroot "* ]]
  [[ " ${SETHLABELS_DEPS[*]} " == *" wget "* ]]
}

@test "executed: prints status and exits 0 (when all installed) OR 1 with apt-install hint" {
  run "$SCRIPT"
  if [ "$status" -eq 0 ]; then
    [[ "$output" == *"All build dependencies present"* ]]
  else
    [[ "$output" == *"sudo apt install"* ]]
  fi
}

@test "executed: warns if not on Debian/Ubuntu" {
  # Simulate non-Debian by overriding /etc/os-release path via env var
  if [ -f /etc/os-release ] && grep -qE '^ID=(debian|ubuntu)' /etc/os-release; then
    skip "currently on Debian/Ubuntu — non-Debian path covered by source review"
  fi
  run "$SCRIPT"
  [[ "$output" == *"Debian"* || "$output" == *"Ubuntu"* ]]
}
```

- [ ] **Step 2: Run tests; confirm they fail**

```bash
bats tests-impl/test-deps-debian.bats
```

Expected: all fail.

- [ ] **Step 3: Write the script to pass**

Create `scripts/lib/deps-debian.sh`:

```bash
#!/usr/bin/env bash
# Single source of truth for sethLabels build dependencies on Debian-family Linux.
#
# When SOURCED:   exposes SETHLABELS_DEPS array (no side effects).
# When EXECUTED:  verifies each dep is installed; prints actionable
#                 `sudo apt install ...` command on missing deps; exits 1.
#                 On clean state, prints "All build dependencies present." and exits 0.
#
# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.1
set -euo pipefail

SETHLABELS_DEPS=(
  build-essential cmake ninja-build pkg-config
  qt6-base-dev qt6-base-dev-tools
  qt6-svg-dev
  qt6-tools-dev qt6-tools-dev-tools
  qt6-l10n-tools
  libqt6printsupport6 libqt6svg6 libqt6widgets6 libqt6xml6 libqt6gui6
  libqt6concurrent6 libqt6core6 libqt6test6
  zlib1g-dev libqrencode-dev libzint-dev libgnubarcode-dev
  file dpkg-dev fakeroot
  wget
  bats
)

# Detect sourced vs. executed.
# When sourced: BASH_SOURCE[0] != $0
# When executed: BASH_SOURCE[0] == $0
if [ "${BASH_SOURCE[0]}" != "${0}" ]; then
  return 0 2>/dev/null || exit 0
fi

# --- Executed path ---

# Sanity check the build host
if [ ! -f /etc/os-release ]; then
  echo "WARNING: /etc/os-release missing; not Debian-family. This script is designed for Debian 13 / Ubuntu LTS." >&2
fi

if [ -f /etc/os-release ]; then
  . /etc/os-release
  if [[ "${ID:-}" != "debian" && "${ID:-}" != "ubuntu" ]] && [[ "${ID_LIKE:-}" != *debian* && "${ID_LIKE:-}" != *ubuntu* ]]; then
    echo "WARNING: not running on Debian or Ubuntu (detected ID='${ID:-unknown}'). Build deps may differ." >&2
  fi
fi

missing=()
for pkg in "${SETHLABELS_DEPS[@]}"; do
  if ! dpkg-query -W -f='${Status}' "$pkg" 2>/dev/null | grep -q "install ok installed"; then
    missing+=("$pkg")
  fi
done

if [ "${#missing[@]}" -gt 0 ]; then
  echo "Missing build dependencies (${#missing[@]}):"
  for p in "${missing[@]}"; do
    echo "  - $p"
  done
  echo ""
  echo "Install with:"
  echo "  sudo apt install -y ${missing[*]}"
  exit 1
fi

echo "All build dependencies present (${#SETHLABELS_DEPS[@]} packages verified)."
```

```bash
chmod +x scripts/lib/deps-debian.sh
```

- [ ] **Step 4: Run tests; confirm they pass**

```bash
bats tests-impl/test-deps-debian.bats
```

Expected: all 8 tests pass.

- [ ] **Step 5: Run the script directly**

```bash
./scripts/lib/deps-debian.sh
```

Expected: either `All build dependencies present.` (if you've installed everything) OR a `Missing build dependencies` listing followed by an `apt install` command. If missing, copy the printed command and run it now — it's needed for Tasks 7 and 8.

- [ ] **Step 6: Commit**

```bash
git add scripts/lib/deps-debian.sh tests-impl/test-deps-debian.bats
git commit -m "feat: add deps-debian.sh (build-dep manifest + checker)"
```

---

## Task 5: `scripts/lib/linuxdeploy.sh`

**Files:**
- Create: `scripts/lib/linuxdeploy.sh`

**What it does:** Bootstraps `linuxdeploy` and `linuxdeploy-plugin-qt` to a script-local cache (`scripts/.cache/`) on first run. Pinned versions per spec §F9 (no rolling `continuous` tag).

This task does NOT use TDD because it makes network calls. We validate it by running it and checking outputs.

- [ ] **Step 1: Discover the latest pinned tags from GitHub**

Per spec §F9, we must pin specific versions. Query GitHub for the latest releases:

```bash
curl -s https://api.github.com/repos/linuxdeploy/linuxdeploy/releases/latest | grep -E '"tag_name"' | head -1
curl -s https://api.github.com/repos/linuxdeploy/linuxdeploy-plugin-qt/releases/latest | grep -E '"tag_name"' | head -1
```

Record both tag values. As of spec time (2026-04-29) the linuxdeploy project uses rolling `continuous` releases plus dated `1-alpha-*` snapshots; pick the most recent dated `1-alpha-YYYYMMDD-N` tag from the releases page (NOT `continuous` — `continuous` violates F9). If only `continuous` is offered for the qt plugin, fall back to its `master`-pinned commit SHA noted in the response.

For the rest of this task, substitute your discovered tags as `LINUXDEPLOY_TAG` and `LINUXDEPLOY_PLUGIN_QT_TAG` in the script below.

- [ ] **Step 2: Write the script**

Create `scripts/lib/linuxdeploy.sh` (replace the two `<TAG>` placeholders below with the actual tags discovered in Step 1):

```bash
#!/usr/bin/env bash
# Bootstrap linuxdeploy + linuxdeploy-plugin-qt to a script-local cache.
#
# When SOURCED:   exposes $LINUXDEPLOY_BIN and $LINUXDEPLOY_PLUGIN_QT_BIN paths
#                 (downloads on first run if missing).
# When EXECUTED:  ensures both binaries are present and prints their paths.
#
# Pinned per spec §F9 — version bumps are deliberate, not transparent.
# To bump: re-run discovery (Task 5 Step 1 of the implementation plan), update
#          the two TAG variables below, and verify a fresh AppImage build.
#
# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §F9
set -euo pipefail

# === PINNED VERSIONS (update deliberately per F9) ===
LINUXDEPLOY_TAG="<REPLACE_WITH_DISCOVERED_TAG>"
LINUXDEPLOY_PLUGIN_QT_TAG="<REPLACE_WITH_DISCOVERED_TAG>"
# ====================================================

CACHE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/.cache"
LINUXDEPLOY_BIN="$CACHE_DIR/linuxdeploy-${LINUXDEPLOY_TAG}-x86_64.AppImage"
LINUXDEPLOY_PLUGIN_QT_BIN="$CACHE_DIR/linuxdeploy-plugin-qt-${LINUXDEPLOY_PLUGIN_QT_TAG}-x86_64.AppImage"

LINUXDEPLOY_URL="https://github.com/linuxdeploy/linuxdeploy/releases/download/${LINUXDEPLOY_TAG}/linuxdeploy-x86_64.AppImage"
LINUXDEPLOY_PLUGIN_QT_URL="https://github.com/linuxdeploy/linuxdeploy-plugin-qt/releases/download/${LINUXDEPLOY_PLUGIN_QT_TAG}/linuxdeploy-plugin-qt-x86_64.AppImage"

ensure_tool() {
  local url="$1" out="$2" label="$3"
  if [ -x "$out" ]; then
    return 0
  fi
  mkdir -p "$(dirname "$out")"
  echo "Downloading $label from $url ..." >&2
  if ! wget -q --show-progress -O "$out" "$url"; then
    echo "ERROR: download failed for $label ($url)" >&2
    rm -f "$out"
    return 1
  fi
  chmod +x "$out"
}

ensure_tool "$LINUXDEPLOY_URL" "$LINUXDEPLOY_BIN" "linuxdeploy"
ensure_tool "$LINUXDEPLOY_PLUGIN_QT_URL" "$LINUXDEPLOY_PLUGIN_QT_BIN" "linuxdeploy-plugin-qt"

export LINUXDEPLOY_BIN LINUXDEPLOY_PLUGIN_QT_BIN

if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
  echo "linuxdeploy:           $LINUXDEPLOY_BIN"
  echo "linuxdeploy-plugin-qt: $LINUXDEPLOY_PLUGIN_QT_BIN"
fi
```

```bash
chmod +x scripts/lib/linuxdeploy.sh
```

- [ ] **Step 3: Verify the cache dir is gitignored**

```bash
git check-ignore -v scripts/.cache/anything 2>&1 || echo "NOT IGNORED (problem)"
```

Expected: shows that `scripts/.cache/` matches a `.gitignore` rule (added in Task 1 Step 3). If it says "NOT IGNORED", revisit Task 1 Step 3.

- [ ] **Step 4: Run the script (downloads ~30MB on first run)**

```bash
./scripts/lib/linuxdeploy.sh
```

Expected: prints two paths under `scripts/.cache/`. Both files must be executable AppImages.

- [ ] **Step 5: Smoke-verify the downloaded tools work**

```bash
"$(./scripts/lib/linuxdeploy.sh | head -1 | awk '{print $2}')" --version
```

Expected: prints linuxdeploy version banner. If FUSE is not available (some VMs / containers), set `APPIMAGE_EXTRACT_AND_RUN=1`:

```bash
APPIMAGE_EXTRACT_AND_RUN=1 "$LINUXDEPLOY_BIN" --version
```

If this fails, ensure `libfuse2` is installed (`sudo apt install libfuse2`) or use the extract-and-run env var.

- [ ] **Step 6: Re-run to verify caching (no re-download)**

```bash
./scripts/lib/linuxdeploy.sh
```

Expected: instant exit, no `Downloading ...` messages.

- [ ] **Step 7: Commit**

```bash
git add scripts/lib/linuxdeploy.sh
git commit -m "feat: add linuxdeploy.sh bootstrap (pinned per F9)"
```

---

## Task 6: Packaging metadata files

**Files:**
- Create: `packaging/deb-metadata.env`
- Create: `packaging/appimage-recipe.env`
- Create: `packaging/changelog.md`

**What they do:** Static configuration files consumed by the build scripts. Keeping these out of the shell scripts means tweaking maintainer info, brew tap pins, or release notes is a single-line edit, not a script change.

- [ ] **Step 1: Create `packaging/deb-metadata.env`**

```bash
cat > packaging/deb-metadata.env <<'EOF'
# CPack DEB metadata overrides — sourced by scripts/build-deb.sh.
# All values are passed to cpack as -D CPACK_DEBIAN_PACKAGE_<KEY>="$VALUE".
#
# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.2

MAINTAINER="Seth Freiberg <seth@sethfreiberg.com>"
SECTION="graphics"
HOMEPAGE="https://glabels.org"
# CPACK_PACKAGE_NAME override — required because upstream sets
# CPACK_PACKAGE_NAME=glabels (CMakeLists.txt:86) and decision D6 wants glabels-qt.
PACKAGE_NAME="glabels-qt"
EOF
```

- [ ] **Step 2: Create `packaging/appimage-recipe.env`**

```bash
cat > packaging/appimage-recipe.env <<'EOF'
# linuxdeploy / linuxdeploy-plugin-qt configuration — sourced by scripts/build-appimages.sh.
# Documents the bundling choices for both AppImages.
#
# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.3

# Qt platform plugins to include (linuxdeploy-plugin-qt picks these up automatically;
# documenting here for posterity).
QT_PLATFORM_PLUGINS="xcb"

# Image format plugins. The GUI app needs SVG/PNG support; batch CLI does not.
QT_IMAGE_FORMAT_PLUGINS_GUI="svg"
QT_IMAGE_FORMAT_PLUGINS_BATCH=""

# Files in the AppDir we don't want bundled (linuxdeploy is greedy by default).
APPDIR_EXCLUDE_GLOBS=()
EOF
```

- [ ] **Step 3: Create `packaging/changelog.md`**

```bash
cat > packaging/changelog.md <<'EOF'
# sethLabels packaging changelog

Per-release packaging notes. Each entry covers what changed in the *packaging*,
not what changed upstream. For application-level changes, see the upstream
`docs/CHANGELOG.md` and `git log upstream/master`.

## Format

```
## <version>  —  <ISO date>

- bullet describing what changed in this packaging release
- ...
```

`<version>` is `<upstream-tag>-seth<N>` (e.g., `3.99-master618-seth1`), matching
the git tag and the artifact filename. See spec §D4.

---

## (unreleased)

- First end-to-end release dry run pending.
EOF
```

- [ ] **Step 4: Smoke-source the env files**

```bash
( source packaging/deb-metadata.env && echo "MAINTAINER=$MAINTAINER" && echo "PACKAGE_NAME=$PACKAGE_NAME" )
( source packaging/appimage-recipe.env && echo "QT_PLATFORM_PLUGINS=$QT_PLATFORM_PLUGINS" )
```

Expected: prints the values, no errors. If `set -u` is on globally, sourcing should not error (no unset vars referenced).

- [ ] **Step 5: Commit**

```bash
git add packaging/
git commit -m "feat: add packaging metadata + initial changelog"
```

---

## Task 7: `scripts/build-deb.sh` (with inline smoke tests T1, T2)

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

**What it does:** End-to-end driver that produces `build/deb/glabels-qt_${VERSION}_amd64.deb` and runs smoke tests T1 (parse-ability) and T2 (binaries present) inline. Aborts with a clear error on any failure.

- [ ] **Step 1: Write the script**

Create `scripts/build-deb.sh`:

```bash
#!/usr/bin/env bash
# Build the sethLabels .deb package.
#
# Pipeline (spec §5.2):
#   1. sanity check build host (Debian/Ubuntu, deps present)
#   2. strict-zero guardrail
#   3. compute version
#   4. out-of-tree cmake build
#   5. CPack with overrides
#   6. inline smoke tests T1, T2
#   7. print artifact path for the operator
#
# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.2
set -euo pipefail

REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO_ROOT"

echo "==> [1/6] Sanity check build host"
"$REPO_ROOT/scripts/lib/deps-debian.sh"

echo "==> [2/6] Strict-zero guardrail"
"$REPO_ROOT/scripts/check-no-upstream-edits.sh"

echo "==> [3/6] Compute version"
VERSION="$("$REPO_ROOT/scripts/compute-version.sh")"
echo "    VERSION = $VERSION"

echo "==> [4/6] Out-of-tree cmake build"
BUILD_DIR="$REPO_ROOT/build/deb"
rm -rf "$BUILD_DIR"
mkdir -p "$BUILD_DIR"
cmake -S "$REPO_ROOT" -B "$BUILD_DIR" -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build "$BUILD_DIR" --parallel

echo "==> [5/6] CPack DEB generation"
# shellcheck disable=SC1091
source "$REPO_ROOT/packaging/deb-metadata.env"

cd "$BUILD_DIR"
cpack -G DEB \
  -D CPACK_PACKAGE_NAME="$PACKAGE_NAME" \
  -D CPACK_PACKAGE_VERSION="$VERSION" \
  -D CPACK_DEBIAN_PACKAGE_NAME="$PACKAGE_NAME" \
  -D CPACK_DEBIAN_PACKAGE_MAINTAINER="$MAINTAINER" \
  -D CPACK_DEBIAN_PACKAGE_SECTION="$SECTION" \
  -D CPACK_DEBIAN_PACKAGE_HOMEPAGE="$HOMEPAGE" \
  -D CPACK_DEBIAN_PACKAGE_SHLIBDEPS=ON \
  -D CPACK_DEBIAN_FILE_NAME=DEB-DEFAULT
cd "$REPO_ROOT"

# Resolve the actual artifact filename (CPack uses DEB-DEFAULT naming convention).
DEB_ARTIFACT=$(ls "$BUILD_DIR"/${PACKAGE_NAME}_*.deb 2>/dev/null | head -1)
if [ -z "$DEB_ARTIFACT" ] || [ ! -f "$DEB_ARTIFACT" ]; then
  echo "ERROR: expected .deb artifact not found in $BUILD_DIR" >&2
  ls -la "$BUILD_DIR" >&2
  exit 1
fi

echo "==> [6/6] Smoke tests"

# T1: dpkg-deb --info parses, version field matches.
echo "    T1: dpkg-deb --info"
T1_OUT=$(dpkg-deb --info "$DEB_ARTIFACT")
if ! echo "$T1_OUT" | grep -qE "^ Version: ${VERSION}$"; then
  echo "ERROR: T1 failed — version field in .deb does not match \$VERSION=$VERSION" >&2
  echo "$T1_OUT" >&2
  exit 1
fi
echo "    T1: PASS"

# T2: dpkg-deb --contents includes both binaries.
echo "    T2: dpkg-deb --contents"
T2_OUT=$(dpkg-deb --contents "$DEB_ARTIFACT")
if ! echo "$T2_OUT" | grep -q '/usr/bin/glabels-qt'; then
  echo "ERROR: T2 failed — /usr/bin/glabels-qt missing from .deb" >&2
  exit 1
fi
if ! echo "$T2_OUT" | grep -q '/usr/bin/glabels-batch-qt'; then
  echo "ERROR: T2 failed — /usr/bin/glabels-batch-qt missing from .deb" >&2
  exit 1
fi
echo "    T2: PASS"

# Optional: lintian (warnings-only, non-fatal during battle-test).
if command -v lintian >/dev/null 2>&1; then
  echo "    lintian (advisory):"
  lintian "$DEB_ARTIFACT" || true
fi

echo ""
echo "Artifact: $DEB_ARTIFACT"
```

```bash
chmod +x scripts/build-deb.sh
```

- [ ] **Step 2: Run the build**

```bash
./scripts/build-deb.sh
```

Expected: walks through all 6 steps, ends with `Artifact: build/deb/glabels-qt_3.99-master618-seth1_amd64.deb`. Wall time ~2 minutes on a modern machine.

If T1 fails: investigate whether `CPACK_PACKAGE_VERSION` was applied correctly; some upstream `CMakeLists.txt` edits may need a clean build.

If T2 fails: check `cmake --install --prefix=/tmp/install build/deb && ls /tmp/install/usr/bin/` to verify upstream's install rules produced both binaries. If only one is present, it's an upstream issue (not a sethLabels bug).

- [ ] **Step 3: Inspect the artifact manually**

```bash
DEB=$(ls build/deb/glabels-qt_*.deb | head -1)
dpkg-deb --info "$DEB"
dpkg-deb --contents "$DEB" | head -30
```

Expected: `Package: glabels-qt`, `Version: 3.99-master618-seth1` (or your computed version), and a sane file listing showing `/usr/bin/...`, `/usr/share/applications/...`, etc.

- [ ] **Step 4: Optionally test-install on the build host (non-destructive smoke)**

```bash
sudo apt install -y "./$DEB"
glabels-qt --version
sudo apt remove -y glabels-qt
```

Skip if you'd rather only test on a clean VM (T5 in the release flow).

- [ ] **Step 5: Commit**

```bash
git add scripts/build-deb.sh
git commit -m "feat: add build-deb.sh with inline smoke tests T1, T2"
```

---

## Task 8: `scripts/build-appimages.sh` (with inline smoke tests T3, T4)

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

**What it does:** Produces TWO AppImages — `sethlabels-gui-${VERSION}-x86_64.AppImage` (full Qt6 GUI) and `sethlabels-batch-${VERSION}-x86_64.AppImage` (CLI batch tool, leaner) — using `linuxdeploy` + `linuxdeploy-plugin-qt`. Inline smoke tests T3 (batch `--version`) and T4 (gui `--help` under `QT_QPA_PLATFORM=minimal`).

- [ ] **Step 1: Write the script**

Create `scripts/build-appimages.sh`:

```bash
#!/usr/bin/env bash
# Build sethLabels AppImages (GUI + batch).
#
# Pipeline (spec §5.3):
#   1. sanity / guardrail / version-compute (same as build-deb.sh)
#   2. out-of-tree cmake build with CMAKE_INSTALL_PREFIX=/usr
#   3. cmake --install to staging AppDir
#   4. linuxdeploy bundle GUI AppImage
#   5. re-stage AppDir for batch-only, linuxdeploy bundle batch AppImage
#   6. inline smoke tests T3, T4
#   7. print artifact paths
#
# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.3
set -euo pipefail

REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO_ROOT"

echo "==> [1/6] Sanity check build host"
"$REPO_ROOT/scripts/lib/deps-debian.sh"
echo "==> [1/6] Strict-zero guardrail"
"$REPO_ROOT/scripts/check-no-upstream-edits.sh"
echo "==> [1/6] Compute version"
VERSION="$("$REPO_ROOT/scripts/compute-version.sh")"
echo "    VERSION = $VERSION"

# Bootstrap linuxdeploy + plugin-qt; defines $LINUXDEPLOY_BIN and $LINUXDEPLOY_PLUGIN_QT_BIN.
# shellcheck disable=SC1091
source "$REPO_ROOT/scripts/lib/linuxdeploy.sh"
# linuxdeploy looks for the plugin in PATH; symlink into the cache dir suffices.
PLUGIN_DIR="$(dirname "$LINUXDEPLOY_PLUGIN_QT_BIN")"
PATH="$PLUGIN_DIR:$PATH"
# Plugin file must be named exactly `linuxdeploy-plugin-qt` (no version suffix).
PLUGIN_LINK="$PLUGIN_DIR/linuxdeploy-plugin-qt"
ln -sf "$LINUXDEPLOY_PLUGIN_QT_BIN" "$PLUGIN_LINK"
chmod +x "$PLUGIN_LINK"

echo "==> [2/6] Out-of-tree cmake build (install prefix /usr)"
BUILD_DIR="$REPO_ROOT/build/appimage"
APPDIR_GUI="$BUILD_DIR/AppDir-gui"
APPDIR_BATCH="$BUILD_DIR/AppDir-batch"
rm -rf "$BUILD_DIR"
mkdir -p "$BUILD_DIR"
cmake -S "$REPO_ROOT" -B "$BUILD_DIR" -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr
cmake --build "$BUILD_DIR" --parallel

echo "==> [3/6] Stage install tree to AppDirs"
DESTDIR="$APPDIR_GUI" cmake --install "$BUILD_DIR"
# Batch AppDir gets its own copy so we can prune Qt plugins that GUI needs but batch doesn't.
DESTDIR="$APPDIR_BATCH" cmake --install "$BUILD_DIR"

# Sanity: both AppDirs must contain both binaries (we strip later, not here).
test -x "$APPDIR_GUI/usr/bin/glabels-qt" || { echo "ERROR: GUI binary missing in AppDir-gui" >&2; exit 1; }
test -x "$APPDIR_BATCH/usr/bin/glabels-batch-qt" || { echo "ERROR: batch binary missing in AppDir-batch" >&2; exit 1; }

echo "==> [4/6] Bundle GUI AppImage"
DESKTOP_FILE="$APPDIR_GUI/usr/share/applications/glabels-qt.desktop"
ICON_FILE="$APPDIR_GUI/usr/share/icons/hicolor/scalable/apps/glabels.svg"
# Upstream's actual desktop filename may vary — list what's there if missing.
if [ ! -f "$DESKTOP_FILE" ]; then
  ALT_DESKTOP=$(find "$APPDIR_GUI/usr/share/applications" -name '*.desktop' | head -1)
  if [ -n "$ALT_DESKTOP" ]; then
    DESKTOP_FILE="$ALT_DESKTOP"
  else
    echo "ERROR: no .desktop file found in $APPDIR_GUI/usr/share/applications" >&2
    exit 1
  fi
fi

cd "$BUILD_DIR"
APPIMAGE_EXTRACT_AND_RUN=1 \
"$LINUXDEPLOY_BIN" \
  --appdir "$APPDIR_GUI" \
  --plugin qt \
  --executable "$APPDIR_GUI/usr/bin/glabels-qt" \
  --desktop-file "$DESKTOP_FILE" \
  --icon-file "$ICON_FILE" \
  --output appimage

GUI_RAW=$(ls "$BUILD_DIR"/*GUI*.AppImage "$BUILD_DIR"/*glabels-qt*.AppImage 2>/dev/null | head -1)
GUI_OUT="$REPO_ROOT/sethlabels-gui-${VERSION}-x86_64.AppImage"
mv "$GUI_RAW" "$GUI_OUT"
chmod +x "$GUI_OUT"
cd "$REPO_ROOT"

echo "==> [5/6] Bundle batch AppImage"
# Batch doesn't need a desktop file or icon (CLI only).
cd "$BUILD_DIR"
APPIMAGE_EXTRACT_AND_RUN=1 \
"$LINUXDEPLOY_BIN" \
  --appdir "$APPDIR_BATCH" \
  --plugin qt \
  --executable "$APPDIR_BATCH/usr/bin/glabels-batch-qt" \
  --create-desktop-file \
  --output appimage

BATCH_RAW=$(ls "$BUILD_DIR"/*batch*.AppImage 2>/dev/null | head -1)
BATCH_OUT="$REPO_ROOT/sethlabels-batch-${VERSION}-x86_64.AppImage"
mv "$BATCH_RAW" "$BATCH_OUT"
chmod +x "$BATCH_OUT"
cd "$REPO_ROOT"

echo "==> [6/6] Smoke tests"

# T3: batch AppImage --version exits 0 with non-empty output.
echo "    T3: batch --version"
T3_OUT=$(APPIMAGE_EXTRACT_AND_RUN=1 "$BATCH_OUT" --version 2>&1) || {
  echo "ERROR: T3 failed — batch AppImage --version exited non-zero" >&2
  echo "$T3_OUT" >&2
  exit 1
}
if [ -z "$T3_OUT" ]; then
  echo "ERROR: T3 failed — batch AppImage --version produced empty output" >&2
  exit 1
fi
echo "    T3: PASS  ($(echo "$T3_OUT" | head -1))"

# T4: GUI AppImage --help exits 0 under headless Qt platform.
echo "    T4: gui --help (QT_QPA_PLATFORM=minimal)"
APPIMAGE_EXTRACT_AND_RUN=1 QT_QPA_PLATFORM=minimal "$GUI_OUT" --help >/tmp/sethlabels-gui-help 2>&1 || {
  echo "ERROR: T4 failed — GUI AppImage --help exited non-zero" >&2
  cat /tmp/sethlabels-gui-help >&2
  exit 1
}
echo "    T4: PASS"

echo ""
echo "Artifacts:"
echo "  $GUI_OUT"
echo "  $BATCH_OUT"
```

```bash
chmod +x scripts/build-appimages.sh
```

- [ ] **Step 2: Run the build**

```bash
./scripts/build-appimages.sh
```

Expected: walks through all 6 steps, ends with two artifact paths. Wall time ~5 minutes on a modern machine. If `linuxdeploy` errors with "no $XDG_RUNTIME_DIR" or similar, set the env var: `export XDG_RUNTIME_DIR=/tmp/runtime-$USER && mkdir -p $XDG_RUNTIME_DIR`.

If T3 or T4 fails: see spec §F2 — Qt plugin omissions are the usual culprit. Re-run with `LINUXDEPLOY_OUTPUT_VERSION=$VERSION` and inspect the bundle's `usr/plugins/` dir for missing platform/imageformats plugins.

- [ ] **Step 3: Smoke-test the artifacts manually**

```bash
GUI_OUT=$(ls sethlabels-gui-*.AppImage | head -1)
BATCH_OUT=$(ls sethlabels-batch-*.AppImage | head -1)
ls -la "$GUI_OUT" "$BATCH_OUT"
APPIMAGE_EXTRACT_AND_RUN=1 "$BATCH_OUT" --version
APPIMAGE_EXTRACT_AND_RUN=1 QT_QPA_PLATFORM=minimal "$GUI_OUT" --help | head -10
```

Expected: GUI is ~50–80 MB (bundles Qt6), batch is ~20–40 MB (no GUI plugins). Both run cleanly.

- [ ] **Step 4: Verify .gitignore catches the AppImages**

```bash
git status
```

Expected: no `*.AppImage` files appear in the untracked list (matched by the `*.AppImage` rule added in Task 1 Step 3).

- [ ] **Step 5: Commit**

```bash
git add scripts/build-appimages.sh
git commit -m "feat: add build-appimages.sh with inline smoke tests T3, T4"
```

---

## Task 9: `scripts/README.md`

**Files:**
- Create: `scripts/README.md`

**What it does:** Operator-facing run instructions. Documents the order to run scripts, prerequisites, and where artifacts land. Mirrored as the canonical recipe for future CI YAML wrapping (spec I3).

- [ ] **Step 1: Write `scripts/README.md`**

```bash
cat > scripts/README.md <<'EOF'
# sethLabels build scripts

Canonical recipe for building sethLabels artifacts. CI YAML at the public-flip
will call these scripts unmodified — no logic moves into YAML (spec §I3).

## Quick reference

```
./scripts/lib/deps-debian.sh         # check / install build deps
./scripts/check-no-upstream-edits.sh # enforce strict-zero (I1)
./scripts/compute-version.sh         # emit <upstream-tag>-seth<N>
./scripts/build-deb.sh               # → build/deb/glabels-qt_<VERSION>_amd64.deb
./scripts/build-appimages.sh         # → sethlabels-{gui,batch}-<VERSION>-x86_64.AppImage
```

## Prerequisites

Debian 13 (Trixie) or Ubuntu 24.04 LTS. Run:

```
./scripts/lib/deps-debian.sh
```

If anything is missing, the script prints the exact `sudo apt install ...`
command to run.

`bats` (bash test framework) is in the dep list — it's required for the
implementation tests under `tests-impl/`.

`linuxdeploy` and `linuxdeploy-plugin-qt` are NOT apt-installable; they're
downloaded automatically by `scripts/lib/linuxdeploy.sh` to `scripts/.cache/`
on first AppImage build.

## Versioning

`<upstream-tag>-seth<N>` (e.g., `3.99-master618-seth1`). The `<N>` counter is
computed from existing git tags matching `<upstream-tag>-seth*`. See spec §D4.

**Caller responsibility:** the local tag db must be fresh before running
`compute-version.sh`. Run `git fetch origin --tags` first if you're not
inside the release flow (which fetches tags as step 1).

## Release flow

See spec §6 for the canonical step-by-step. TL;DR:

```
git fetch --all --tags
git rebase upstream/master
./scripts/check-no-upstream-edits.sh
./scripts/build-deb.sh                       # ~2 min
./scripts/build-appimages.sh                 # ~5 min
VERSION=$(./scripts/compute-version.sh)
git tag "$VERSION"
git push origin main --tags
# Create Gitea release for $VERSION; attach the three artifacts.
# Bump ../homebrew-tap/Formula/glabels-qt.rb (tag + revision); commit; push.
# Smoke verify on a clean Debian 13 VM (T5).
```

## Layout

```
scripts/
├── README.md                     ← this file
├── compute-version.sh            ← pure logic; emits version string
├── check-no-upstream-edits.sh    ← guardrail enforcing I1
├── build-deb.sh                  ← end-to-end .deb pipeline
├── build-appimages.sh            ← end-to-end AppImage pipeline (GUI + batch)
├── lib/
│   ├── deps-debian.sh            ← build-dep manifest + checker
│   └── linuxdeploy.sh            ← linuxdeploy + plugin-qt bootstrapper
└── .cache/                       ← gitignored; linuxdeploy AppImages cache
```

## Tests

```
./tests-impl/run-all.sh
```

Runs the bats suite for pure-logic scripts. Build-script smoke tests (T1–T4)
are inline in `build-deb.sh` and `build-appimages.sh` — they fire automatically
on each build.

## Spec

The design rationale, invariants, and failure modes live in
[`../sethlabels-docs/specs/2026-04-29-packaging-design.md`](../sethlabels-docs/specs/2026-04-29-packaging-design.md).
Read it before changing any script.
EOF
```

- [ ] **Step 2: Verify the README renders sensibly**

```bash
head -40 scripts/README.md
```

Expected: clean Markdown, no obvious typos.

- [ ] **Step 3: Commit**

```bash
git add scripts/README.md
git commit -m "docs: add scripts/README.md (operator run guide)"
```

---

## Task 10: `README.sethlabels.md` (repo-root entry)

**Files:**
- Create: `README.sethlabels.md`

**What it does:** Repo-root sethLabels entry point. Names the fork's purpose, points readers at install methods, and links to the upstream README and design spec. Strict-zero forbids modifying upstream `README.md`, hence the `.sethlabels.md` suffix.

- [ ] **Step 1: Write `README.sethlabels.md`**

```bash
cat > README.sethlabels.md <<'EOF'
# sethLabels

> Deployment fork of [glabels-qt](https://github.com/j-evins/glabels-qt) — Qt6
> label designer / printer, packaged for Debian-family Linux and macOS.

This is **not** a code fork. The upstream application is unchanged; sethLabels
exists solely to publish installable binary artifacts that upstream explicitly
does not provide ("Currently there are no self-hosted binary snapshot releases
available… I encourage you to try building the code yourself" — upstream README).

For the application itself — what it does, screenshots, full feature list — see
the upstream [`README.md`](README.md).

## Install

### Debian / Ubuntu (`.deb`)

Download the latest `.deb` from the [releases page](https://git.sethpc.xyz/Seth/sethLabels/releases),
then:

```
sudo apt install ./glabels-qt_<VERSION>_amd64.deb
glabels-qt --version
```

### Any Linux (AppImage)

Download `sethlabels-gui-<VERSION>-x86_64.AppImage` from the [releases page](https://git.sethpc.xyz/Seth/sethLabels/releases),
make it executable, and run it:

```
chmod +x sethlabels-gui-<VERSION>-x86_64.AppImage
./sethlabels-gui-<VERSION>-x86_64.AppImage
```

A separate `sethlabels-batch-<VERSION>-x86_64.AppImage` provides the CLI for
scripted / mail-merge use.

### macOS (Homebrew)

```
brew tap seth/tap https://git.sethpc.xyz/Seth/homebrew-tap.git
brew install seth/tap/glabels-qt
```

The explicit URL form is needed because brew defaults to GitHub for tap names.
First install builds Qt6 + glabels-qt from source (~5–10 min one-time cost; see
spec §D2). Subsequent updates are a fast `brew upgrade`.

## Build from source

If you'd rather build the artifacts yourself instead of downloading a release:

```
git clone https://git.sethpc.xyz/Seth/sethLabels.git
cd sethLabels
./scripts/lib/deps-debian.sh        # check / install build deps
./scripts/build-deb.sh              # → build/deb/glabels-qt_*.deb
./scripts/build-appimages.sh        # → sethlabels-{gui,batch}-*.AppImage
```

See [`scripts/README.md`](scripts/README.md) for full operator docs.

## How this fork works

sethLabels is a **deployment fork**: every sethLabels addition lives in NEW
files in NEW top-level directories (`scripts/`, `packaging/`,
`sethlabels-docs/`, `tests-impl/`, plus this file). Upstream files are never
edited. The single allowlisted exception is `.gitignore`. This discipline is
enforced by `scripts/check-no-upstream-edits.sh`.

The `<upstream-tag>-seth<N>` versioning preserves the upstream-lineage in every
artifact. Periodic `git rebase upstream/master` is conflict-free by construction.

## Spec & decisions

- [Design spec](sethlabels-docs/specs/2026-04-29-packaging-design.md) — invariants, decisions, build pipeline, failure modes
- [Decision log](DECISIONS.md) — settled choices + rejected alternatives
- [Project brief](IDEA.md) — plain-language motivation

## License

The upstream code is licensed under [GPL-3.0](LICENSE). sethLabels-specific
files (everything in the dirs listed above, plus this file) are licensed under
the same terms.

## Upstream

- Upstream: https://github.com/j-evins/glabels-qt (Jaye Evins / glabels.org)
- This fork: https://git.sethpc.xyz/Seth/sethLabels
- Brew tap: https://git.sethpc.xyz/Seth/homebrew-tap
EOF
```

- [ ] **Step 2: Verify guardrail still passes**

```bash
./scripts/check-no-upstream-edits.sh && echo CLEAN
```

Expected: `CLEAN`. `README.sethlabels.md` is in the allowlist (added in Task 3 Step 3's `allowed_pattern`).

- [ ] **Step 3: Commit**

```bash
git add README.sethlabels.md
git commit -m "docs: add README.sethlabels.md (fork entry point)"
```

---

## Task 11: Homebrew tap repo (separate Gitea repo)

**Files (in a separate repo at `~/bin/homebrew-tap/`):**
- Create: `~/bin/homebrew-tap/Formula/glabels-qt.rb`
- Create: `~/bin/homebrew-tap/README.md`
- Create: Gitea repo `git.sethpc.xyz/Seth/homebrew-tap`

**What it does:** Provides the macOS install path per spec §7 + §D2. Build-from-source on the user's Mac via brew.

This task does NOT modify the sethLabels repo. It creates a parallel sibling repo.

- [ ] **Step 1: Create the local repo skeleton**

```bash
mkdir -p ~/bin/homebrew-tap/Formula
cd ~/bin/homebrew-tap
git init -q -b main
git config user.email "seth@sethfreiberg.com"
git config user.name "Seth Freiberg"
```

- [ ] **Step 2: Create `Formula/glabels-qt.rb`**

```bash
cat > Formula/glabels-qt.rb <<'EOF'
class GlabelsQt < Formula
  desc "gLabels Label Designer (Qt/C++) — Seth's packaging fork"
  homepage "https://glabels.org"
  url "https://git.sethpc.xyz/Seth/sethLabels.git",
      tag:      "PLACEHOLDER_FILLED_AT_FIRST_RELEASE",
      revision: "PLACEHOLDER_FILLED_AT_FIRST_RELEASE"
  license "GPL-3.0-only"
  head "https://git.sethpc.xyz/Seth/sethLabels.git", branch: "main"

  depends_on "cmake"   => :build
  depends_on "ninja"   => :build
  depends_on "pkgconf" => :build
  depends_on "qt"
  depends_on "zlib"
  depends_on "qrencode" => :recommended  # optional barcode backend
  depends_on "zint"     => :recommended  # optional barcode backend

  def install
    system "cmake", "-S", ".", "-B", "build",
           "-G", "Ninja",
           "-DCMAKE_BUILD_TYPE=Release",
           *std_cmake_args
    system "cmake", "--build", "build"
    system "cmake", "--install", "build"
  end

  test do
    assert_match "gLabels", shell_output("#{bin}/glabels-batch-qt --version")
  end
end
EOF
```

The `tag:` and `revision:` placeholders are filled at the first release (Task 12 Step 6).

- [ ] **Step 3: Create `README.md` for the tap**

```bash
cat > README.md <<'EOF'
# Seth's Homebrew tap

Homebrew tap publishing macOS install for [sethLabels](https://git.sethpc.xyz/Seth/sethLabels).

## Install

```
brew tap seth/tap https://git.sethpc.xyz/Seth/homebrew-tap.git
brew install seth/tap/glabels-qt
```

The explicit URL form is required because Homebrew defaults to GitHub for tap
names. When this repo is mirrored to GitHub at the public-flip, the URL becomes
implicit and the tap command shortens to `brew tap seth/tap`.

## Formulae

| Formula | Description |
|---------|-------------|
| `glabels-qt` | [gLabels label designer (Qt/C++)](https://git.sethpc.xyz/Seth/sethLabels) — Seth's packaging fork of glabels-qt |

## How this works

`brew install seth/tap/glabels-qt` clones the sethLabels git tag pinned in
`Formula/glabels-qt.rb`, builds Qt6 + glabels-qt from source, and installs to
`/opt/homebrew/`. First install takes ~5–10 minutes. Subsequent
`brew upgrade glabels-qt` runs are fast (only the version-bumped formula
re-builds).

## Per-release maintenance

Each sethLabels release is one commit on this repo: bump `tag:` and `revision:`
in `Formula/glabels-qt.rb`. No other edits expected.

## Spec

Design rationale lives in the sethLabels repo:
[`sethlabels-docs/specs/2026-04-29-packaging-design.md`](https://git.sethpc.xyz/Seth/sethLabels/src/branch/main/sethlabels-docs/specs/2026-04-29-packaging-design.md) §D2, §7.
EOF
```

- [ ] **Step 4: Initial commit on local tap repo**

```bash
cd ~/bin/homebrew-tap
git add Formula/glabels-qt.rb README.md
git commit -m "chore: scaffold tap with glabels-qt formula"
```

- [ ] **Step 5: Create Gitea remote and push**

Use the `gitea` CLI per global instructions:

```bash
cd ~/bin/homebrew-tap
gitea create homebrew-tap --description "Homebrew tap publishing macOS install for sethLabels"
gitea remote homebrew-tap
gitea push
```

Expected: `gitea create` prints the new repo URL; `gitea remote` sets `origin`; `gitea push` pushes `main`.

- [ ] **Step 6: Verify the tap can be browsed**

```bash
curl -s https://git.sethpc.xyz/Seth/homebrew-tap/raw/branch/main/Formula/glabels-qt.rb | head -10
```

Expected: prints the first 10 lines of the formula.

- [ ] **Step 7: Return to sethLabels repo**

```bash
cd ~/bin/sethLabels
```

The sethLabels repo has no commits in this task — the tap is a separate repo. The next task is the first end-to-end release of sethLabels itself.

---

## Task 12: First end-to-end release dry run (operator checklist)

**Files modified:**
- Modify: `~/bin/homebrew-tap/Formula/glabels-qt.rb` (Step 9 — replace placeholder tag and revision)
- Modify: `packaging/changelog.md` (Step 5 — add the seth1 entry)

**What it does:** Walks the spec §6 release flow end-to-end. Produces real artifacts, tags the sethLabels repo, attaches artifacts to a Gitea release, bumps the brew formula, and (optionally) verifies T5 install on a clean Debian 13 VM.

- [ ] **Step 1: Refresh tags + rebase**

```bash
cd ~/bin/sethLabels
git fetch --all --tags
git rebase upstream/master
```

Expected: rebase is conflict-free (strict-zero invariant). If it conflicts, STOP — something has slipped past the guardrail.

- [ ] **Step 2: Run guardrail explicitly**

```bash
./scripts/check-no-upstream-edits.sh && echo CLEAN
```

Expected: `CLEAN`.

- [ ] **Step 3: Build the .deb**

```bash
./scripts/build-deb.sh
```

Expected: ends with `Artifact: build/deb/glabels-qt_<VERSION>_amd64.deb`. Note the version string for use in later steps.

- [ ] **Step 4: Build the AppImages**

```bash
./scripts/build-appimages.sh
```

Expected: ends with two `Artifacts:` lines naming the GUI and batch AppImages.

- [ ] **Step 5: Update `packaging/changelog.md`**

Edit `packaging/changelog.md` to convert the `## (unreleased)` block to a real version block. Replace the existing `## (unreleased)` section with:

```markdown
## <VERSION>  —  <YYYY-MM-DD>

- First end-to-end release of sethLabels packaging pipeline.
- `.deb` produced via CMake CPack with strict-zero `-D` overrides (no upstream edits).
- AppImages (GUI + batch) bundled via linuxdeploy + linuxdeploy-plugin-qt, pinned per F9.
- Brew tap initial publish at `git.sethpc.xyz/Seth/homebrew-tap`.

## (unreleased)

- (no changes since <VERSION>)
```

Substitute `<VERSION>` with the value from Step 3 and `<YYYY-MM-DD>` with today's ISO date.

```bash
git add packaging/changelog.md
git commit -m "docs: changelog for <VERSION>"
```

- [ ] **Step 6: Compute and tag**

```bash
VERSION=$(./scripts/compute-version.sh)
echo "Tagging $VERSION"
git tag "$VERSION"
git push origin main --tags
```

Expected: tag pushes successfully. If the `seth<N>` count is unexpectedly high, you forgot the `git fetch --all --tags` in Step 1 or there are leftover tags from local experiments.

- [ ] **Step 7: Create Gitea release with artifacts attached**

Use the Gitea API per `~/bin/GITEA_API.md`:

```bash
DEB=$(ls build/deb/glabels-qt_*.deb | head -1)
GUI=$(ls sethlabels-gui-*.AppImage | head -1)
BATCH=$(ls sethlabels-batch-*.AppImage | head -1)

# Read token from the standard location.
GITEA_TOKEN=$(cat ~/.config/gitea/token)
GITEA_BASE="https://git.sethpc.xyz/api/v1"

# Create the release.
RELEASE_JSON=$(curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"tag_name\":\"$VERSION\",\"name\":\"sethLabels $VERSION\",\"body\":\"See packaging/changelog.md for notes.\"}" \
  "$GITEA_BASE/repos/Seth/sethLabels/releases")
RELEASE_ID=$(echo "$RELEASE_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "Created release ID $RELEASE_ID"

# Attach all three artifacts.
for f in "$DEB" "$GUI" "$BATCH"; do
  echo "Attaching $f"
  curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
    -F "attachment=@${f}" \
    "$GITEA_BASE/repos/Seth/sethLabels/releases/$RELEASE_ID/assets?name=$(basename "$f")" \
    >/dev/null
done

echo "Release URL: https://git.sethpc.xyz/Seth/sethLabels/releases/tag/$VERSION"
```

Expected: prints the release URL; opening it shows the three attachments.

- [ ] **Step 8: Verify download URLs are public**

```bash
curl -sI "https://git.sethpc.xyz/Seth/sethLabels/releases/download/$VERSION/$(basename "$DEB")" | head -1
```

Expected: `HTTP/2 200` or `HTTP/2 302` (redirect to the asset).

- [ ] **Step 9: Bump `homebrew-tap/Formula/glabels-qt.rb`**

```bash
cd ~/bin/homebrew-tap
TAG="$VERSION"
REVISION=$(cd ~/bin/sethLabels && git rev-list -n 1 "$VERSION")
echo "Pinning tag=$TAG revision=$REVISION"

# Replace placeholders.
sed -i "s|tag:      \"PLACEHOLDER_FILLED_AT_FIRST_RELEASE\"|tag:      \"$TAG\"|" Formula/glabels-qt.rb
sed -i "s|revision: \"PLACEHOLDER_FILLED_AT_FIRST_RELEASE\"|revision: \"$REVISION\"|" Formula/glabels-qt.rb

# Verify the file is well-formed Ruby (parse-only check; doesn't run Homebrew).
ruby -c Formula/glabels-qt.rb

git diff Formula/glabels-qt.rb
git add Formula/glabels-qt.rb
git commit -m "bump glabels-qt to $TAG"
git push origin main
```

Expected: `ruby -c` reports `Syntax OK`; `git push` succeeds.

- [ ] **Step 10: Optional — T5 fresh-VM smoke test**

Per spec §10, T5 is "install on a clean Debian 13 VM and run `glabels-qt --version`". This is the strongest signal that `dpkg-shlibdeps` produced a correct depends list. Recommended on every `seth1` release; skippable on `seth2`+ packaging-only fixes.

If you have a clean Debian 13 VM available:

```
# On the clean VM:
wget https://git.sethpc.xyz/Seth/sethLabels/releases/download/<VERSION>/glabels-qt_<VERSION>_amd64.deb
sudo apt install -y ./glabels-qt_<VERSION>_amd64.deb
glabels-qt --version
```

Expected: install succeeds; `--version` exits 0 and prints the version string.

If `apt install` errors with unmet deps, the `dpkg-shlibdeps` calculation was wrong (spec §F8). Mitigation: override via `CPACK_DEBIAN_PACKAGE_DEPENDS` in `scripts/build-deb.sh`, rebuild, re-tag as `seth2`.

- [ ] **Step 11: Update CLAUDE.md to reflect post-implementation state**

```bash
cd ~/bin/sethLabels
```

Open `CLAUDE.md`, find the `## Current State` block, and replace its content with:

```markdown
## Current State

- **Phase:** post-first-release. Pipeline live. First tag: <VERSION>. Three artifacts attached to the Gitea release. Brew tap bumped to match.
- **Repo:** `git.sethpc.xyz/Seth/sethLabels` (default branch `main`). Tap: `git.sethpc.xyz/Seth/homebrew-tap`. Upstream: `j-evins/glabels-qt` (`upstream` remote).
- **Deploy targets live:** Debian-family Linux (`.deb` + AppImage) and macOS via Homebrew tap.
- **Next release:** rebase, build, tag, attach, bump tap. See `scripts/README.md` and spec §6.
```

```bash
git add CLAUDE.md
git commit -m "docs: refresh CLAUDE.md to post-first-release phase"
git push origin main
```

- [ ] **Step 12: Write a session handoff**

Per Seth's global persistence convention, create a handoff document capturing the session's outcome:

```bash
# Use the session-handoff skill to create the handoff document with proper structure.
# (See ~/.claude/CLAUDE.md → Persistence Partition → Session close).
```

The handoff filename pattern is `.claude/handoffs/YYYY-MM-DD-HHMMSS-first-release.md`.

---

## Self-review checklist

After all 12 tasks complete, the implementer should verify:

- [ ] **Spec coverage:** every section of `sethlabels-docs/specs/2026-04-29-packaging-design.md` maps to a task — §2 (invariants enforced by Task 3); §3 (decisions reflected throughout); §4 (file structure produced); §5.1–5.5 (Tasks 4–7 in order); §6 (Task 12); §7 (Task 11); §F1–F9 (each guarded somewhere — F1=Task 3, F2=Task 8 inline T4, F3=Task 4, F4=Task 11, F5=Task 2, F6=Task 9, F7=Task 12 step 1 rebase verification, F8=Task 12 step 10 T5, F9=Task 5 explicit pinning); §10 (T1–T4 inline; T5 in Task 12 step 10).
- [ ] **No upstream files modified:** `git diff --name-only upstream/master..HEAD` shows only allowlisted paths.
- [ ] **All bats tests pass:** `./tests-impl/run-all.sh` reports green.
- [ ] **The .deb installs cleanly** on a fresh Debian 13 VM and `glabels-qt --version` exits 0.
- [ ] **Both AppImages run** under `APPIMAGE_EXTRACT_AND_RUN=1` (no FUSE dependency).
- [ ] **Brew formula parses:** `ruby -c Formula/glabels-qt.rb` reports `Syntax OK`. (Live `brew install` test on a Mac is recommended but not gate-blocking.)
- [ ] **Release flow steps 1–9 of spec §6 ran cleanly** with no manual deviations.