sami/vdm

Files

T

samiandClaude Opus 5 8bb683b09d 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]>

2026-09-09 18:21:11 +04:00

2.8 KiB

Raw Blame History

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)

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.
contracts/openrpc.json — generated from the schemas; it is the doc humans read.
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.
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).
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.
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.
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.

2.8 KiB Raw Blame History