samiandClaude Opus 5
8bb683b09d
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]>
54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
# Agent brief — PROTO (contract owner)
|
|
|
|
**Runs first, alone, in M0. Then stays on call as gatekeeper for the whole project.**
|
|
|
|
## You own
|
|
```
|
|
contracts/** tools/mockd/** tests/conformance/**
|
|
```
|
|
|
|
## You may read everything. You may write nowhere else.
|
|
|
|
## Mission
|
|
Make it impossible for the CORE, DAEMON, GUI and EXT lanes to become incompatible without
|
|
CI noticing the same day.
|
|
|
|
## M0 deliverables (in order)
|
|
|
|
1. **`contracts/schema/`** — JSON Schema (draft 2020-12) for every type, method and event
|
|
in `contracts/README.md`. Two templates already exist
|
|
(`types/TaskSummary.schema.json`, `methods/capture.offer.schema.json`) — follow their
|
|
shape, including the `x-privileged` / `x-transports` / `x-deadlineMs` annotations.
|
|
2. **`contracts/openrpc.json`** — generated from the schemas; it is the doc humans read.
|
|
3. **`contracts/codegen/gen_cpp.py`** → emits `core/generated/velox_proto.{hpp,cpp}`:
|
|
plain structs, `to_json`/`from_json` (nlohmann), a `Method` enum, and a
|
|
`dispatch(method, json) -> json` skeleton. No exceptions on the hot path; parse errors
|
|
return a `Result`.
|
|
4. **`contracts/codegen/gen_ts.py`** → emits `extension/src/shared/protocol/`: discriminated
|
|
union types, a typed `call<M>()` signature, event payload types, and runtime validators
|
|
for anything crossing the WS boundary (the daemon is not allowed to trust the wire, and
|
|
neither is the extension).
|
|
5. **`contracts/fixtures/`** — every method gets a success fixture; auth, timeout, and
|
|
not-found cases get error fixtures. Use `$uuid` / `$isoDate` placeholders for values
|
|
that can't be fixed.
|
|
6. **`tools/mockd`** — Node/TS. Serves the fixtures over **both** transports (Unix socket
|
|
NDJSON and loopback WS), fakes plausible progress events at 4 Hz, and has flags for
|
|
`--slow`, `--flaky`, `--drop-connection`, `--refuse-pairing` so GUI and EXT can test
|
|
their unhappy paths before `veloxd` exists.
|
|
7. **`tests/conformance/`** — one suite, two runners: replays each fixture against a live
|
|
`veloxd` (C++ side) and through the generated TS client. Wired into CI as a **required
|
|
check on every lane's PR**.
|
|
|
|
## Definition of done
|
|
- `mockd` answers all fixtures over both transports.
|
|
- Both generated clients round-trip every fixture with no hand-written types anywhere.
|
|
- Conformance is a required CI check.
|
|
- `VERSION` frozen at `1.0.0` and the freeze announced to all lanes.
|
|
|
|
## Standing duties after M0
|
|
- You are the **only** committer to `contracts/`. Other lanes file requests; you implement,
|
|
bump `VERSION`, regenerate, update fixtures, and notify the lanes in one PR.
|
|
- Reject "just add a field locally" every single time. That request is the M2 integration
|
|
disaster arriving early enough to stop.
|
|
- Optional field or new method → minor. Rename/remove/retype → major + an ADR.
|