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,59 @@
|
||||
# Agent brief — DAEMON (`veloxd`)
|
||||
|
||||
**Starts with CORE. You are the only process that owns state.**
|
||||
|
||||
## You own
|
||||
```
|
||||
daemon/** cli/** nmhost/** packaging/nativehost/**
|
||||
```
|
||||
Read `contracts/`, `core/include/`, `docs/`. Never write in `core/`, `gui/`, or `extension/`.
|
||||
|
||||
## Read first
|
||||
`docs/01-architecture.md` §2–§5, `contracts/README.md`, `docs/05-extension-spec.md` §4
|
||||
(you implement the daemon half of pairing).
|
||||
|
||||
## Build order
|
||||
|
||||
1. **RPC server** — `rpc/uds_server` (NDJSON over `$XDG_RUNTIME_DIR/velox/velox.sock`,
|
||||
0600, `SO_PEERCRED` same-UID check) and `rpc/ws_server` (bind `127.0.0.1` only, first
|
||||
free port in 52000–52016, write the chosen port to `ws.port`). One dispatcher, generated
|
||||
from `contracts/`. Never block the RPC loop — disk and network work goes to CORE's pools.
|
||||
2. **Auth & pairing** — `session.pair` triggers a user prompt (GUI dialog if connected,
|
||||
else a desktop notification with actions). Tokens: 256-bit, stored **hashed**,
|
||||
per-install, revocable. Failed-auth rate limit 5/min then 60 s lockout. Enforce
|
||||
`x-transports` and `x-privileged` from the schema: privileged methods are refused over
|
||||
WS with `-32003`.
|
||||
3. **Store** — SQLite WAL. Tables: `tasks`, `segments`, `categories`, `queues`, `rules`,
|
||||
`settings`, `history`, `pairings`. Numbered migrations in `store/migrations/`, applied
|
||||
at startup, with a forward-only test from every released schema version.
|
||||
**Credentials never go in SQLite** — Secret Service via libsecret.
|
||||
4. **Scheduler & queues** — concurrency governor (global max active, per-queue max, per-host
|
||||
caps), time windows, days-of-week, one-shot vs periodic, "when queue completes" actions.
|
||||
5. **Event fan-out** — per-subscription filtering, and **`event.task.progress` batched at
|
||||
≤ 4 Hz into a single array message**. Do not emit one message per task per tick; that is
|
||||
how you turn 20 downloads into a GUI that burns a core.
|
||||
6. **Capture endpoint** — `capture.offer` must answer within **750 ms**, always. Apply the
|
||||
rules table, resolve the category folder, dedupe against active tasks, return
|
||||
`take`/`ignore`. If anything internally is slow, answer `ignore` and let Firefox have
|
||||
it. Never make the browser wait.
|
||||
7. **Integration** — systemd user units (`velox.service` + `velox.socket` for socket
|
||||
activation), single-instance lock, XDG autostart, `org.freedesktop.Notifications`,
|
||||
graceful shutdown that flushes buffers and meta files.
|
||||
8. **`velox` CLI** — `add`, `ls`, `pause`, `resume`, `rm`, `queue`, `settings`, `--json`
|
||||
output. Build this early: it is how you test the daemon before the GUI exists.
|
||||
9. **`velox-nmhost`** — 4-byte-length-prefixed stdio ⇄ Unix socket pump. **Under 300 lines,
|
||||
zero business logic**, and it must exit cleanly when Firefox closes the pipe. Install
|
||||
manifests to all four locations listed in `docs/05` §4.
|
||||
|
||||
## Definition of done (M1)
|
||||
- Passes the full conformance suite as a server, over **both** transports.
|
||||
- Kill and restart the daemon mid-download: all tasks reload with correct state and resume.
|
||||
- 1 000 tasks in the DB: `download.list` with paging under 50 ms.
|
||||
- Pairing flow works from a real Firefox extension; unpair revokes immediately.
|
||||
- `systemctl --user status velox` clean; socket activation verified from cold.
|
||||
- Security review passed: no bind beyond loopback, no path traversal in `saveDir`
|
||||
(canonicalize and check against allowed roots → `-32011`), no plaintext secrets.
|
||||
|
||||
## Do not
|
||||
- Do not put download logic here — that's CORE. You schedule and persist; CORE transfers.
|
||||
- Do not invent protocol fields. File a request with PROTO.
|
||||
Reference in New Issue
Block a user