scaffold: project structure, wire contract, roadmap and agent briefs
Lays out Velox Download Manager (IDM-class download manager for Ubuntu 26.04) as a monorepo ready for parallel lane development. No implementation code by design. - docs/: architecture, roadmap M0-M7, IDM-parity GUI spec, engine design, Firefox extension spec, risks/spikes, packaging - contracts/: wire-contract skeleton (JSON Schema + fixture templates) — the single synchronization point between lanes - docs/agents/: one brief per lane (PROTO, CORE, DAEMON, GUI, EXT, PKG/QA) with owned directories, build order and definition of done - CLAUDE.md: rules of engagement — lane ownership, layering, non-negotiables - CMake scaffolding with dev/tsan/release/ci presets Two environment findings shape the design: Firefox here is the Mozilla snap (native-messaging risk, so the extension carries a loopback-WebSocket fallback), and Wayland forbids passive clipboard monitoring (so clipboard capture is explicit-action-first). Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,62 @@
|
||||
# Agent brief — PKG/QA (build, packaging, test infrastructure)
|
||||
|
||||
**Starts in M0 alongside PROTO. You unblock everyone else and you own the release.**
|
||||
|
||||
## You own
|
||||
```
|
||||
packaging/** .github/workflows/** tools/testserver/** tests/integration/** tests/e2e/**
|
||||
CMakeLists.txt CMakePresets.json .clang-format .clang-tidy .editorconfig .gitignore
|
||||
```
|
||||
Do not write feature code in any lane's directory.
|
||||
|
||||
## M0 — unblock the lanes (do these first, in this order)
|
||||
|
||||
1. **Toolchain script** — `tools/bootstrap.sh` installing the `apt` list in the README,
|
||||
verified on a clean 26.04 VM. The dev machine already has git 2.53, CMake 4.2.3,
|
||||
g++ 15.2, ninja, Qt 6 dev, libcurl, SQLite, nlohmann-json and ffmpeg; only
|
||||
`libqt6svg6-dev`, `libsecret-1-dev`, `nodejs`/`npm` and (optionally) `clang` are
|
||||
missing. The script must still install the full list for clean machines.
|
||||
⚠ CMake 4.x rejects `cmake_minimum_required` below 3.5 — check every dependency.
|
||||
2. **CMake** — top-level `CMakeLists.txt` + `CMakePresets.json` with presets:
|
||||
`dev` (Debug + ASan/UBSan), `tsan`, `release` (RelWithDebInfo + LTO), `ci`.
|
||||
Ninja, C++23, `-Wall -Wextra -Werror`.
|
||||
3. **`tools/testserver`** — the hostile HTTP server every lane tests against. Modes, each
|
||||
toggleable by URL path or flag:
|
||||
`no-range` · `lies-about-accept-ranges` · `etag-changes` · `flaky-reset` ·
|
||||
`slow-loris` · `redirect-chain` · `401-basic` · `401-digest` · `403-without-referer` ·
|
||||
`416-always` · `content-length-mismatch` · `expiring-signed-url` · `throttled` ·
|
||||
`chunked-no-length` · `utf8-content-disposition` · `legacy-content-disposition`.
|
||||
**CORE's definition of done is written in terms of this server, so it must exist first.**
|
||||
4. **CI** — GitHub Actions: build matrix (gcc + clang), unit tests, ASan/UBSan/TSan jobs,
|
||||
`clang-format --dry-run -Werror`, `clang-tidy`, `web-ext lint`, and **conformance as a
|
||||
required check on every PR**.
|
||||
|
||||
## M1–M5 — keep it honest
|
||||
- Nightly integration run: real `veloxd` + `testserver`, 50 concurrent downloads, assert
|
||||
checksums and zero leaked FDs.
|
||||
- `tests/e2e/` with Playwright: real Firefox + real daemon + a real file on disk.
|
||||
- 72-hour soak job (M7 gate): 500 queued tasks, memory and FD graphs must be flat.
|
||||
- `tools/bench` results published per commit so a performance regression is visible the day
|
||||
it lands, not in M7.
|
||||
|
||||
## M6 — packaging
|
||||
|
||||
- **`.deb`** (primary): `veloxd`, `velox-gui`, `velox`, `velox-nmhost`, desktop entry,
|
||||
systemd **user** units, icons, man pages, and native-messaging manifests installed to
|
||||
`/usr/lib/mozilla/native-messaging-hosts/` plus a postinst that also drops the per-user
|
||||
snap and flatpak copies where applicable. `lintian` clean. Publish via PPA.
|
||||
- **Flatpak** (secondary): note that the sandbox changes the native-messaging story again —
|
||||
test it, don't assume it.
|
||||
- **AppImage** (optional): if you bundle Qt, bundle it as shared objects and honour LGPLv3
|
||||
relink requirements (`docs/06` R5).
|
||||
- **AMO**: signed XPI, reproducible build script, permission justification from EXT.
|
||||
- **Uninstall test**: removes manifests, units, and sockets; leaves user data alone unless
|
||||
purged.
|
||||
- **Upgrade test**: install N-1, create tasks, upgrade, confirm the DB migrates and
|
||||
in-flight `.veloxpart` files still resume.
|
||||
|
||||
## Definition of done
|
||||
- One command builds everything from a clean checkout on a clean 26.04 VM.
|
||||
- CI red on: format, tidy, sanitizer failure, conformance failure, `web-ext lint` failure.
|
||||
- A fresh VM can install the `.deb`, install the extension, and complete the M2 vertical
|
||||
slice with **snap Firefox** — no manual steps beyond clicking "Allow" once at pairing.
|
||||
Reference in New Issue
Block a user