#+TITLE: DUET Developer Guide
#+AUTHOR: Craig Jennings

* Status

Stub. Fills out across the implementation phases; the backend API and
transfer-spec contract land with Phase 2/3, the full release checklist with
Phase 10. The authoritative design is [[file:design/duet-spec.org][docs/design/duet-spec.org]].

* Repository layout

- =duet.el= — the package. Public =duet-= commands and pure =duet--= helpers.
  The only file that ships (Eask =package-file=).
- =tests/= — ERT suites, one =test-duet-<area>.el= per source area, plus the
  shared harness (=test-bootstrap.el=, =check-deps.el=, =run-coverage-file.el=).
- =scripts/= — developer tooling, not part of the package: =coverage-summary.el=
  (terminal coverage report) and =duet-complexity.el= (the McCabe gate).
- =docs/= — this guide and the design spec.

* Building and testing

DUET uses [[https://emacs-eask.github.io/][Eask]] for dependency management and a Makefile for the common
loops. From the project root:

#+begin_src shell
make deps          # Emacs Lisp deps (eask) + transport CLIs (rsync/rclone/lftp/unison)
make setup         # Emacs Lisp deps only
make test          # full ERT suite (excludes :slow)
make test-file FILE=complexity   # one file
make test-name TEST=pattern      # ERT name selector
make compile       # byte-compile, warnings-as-errors
make lint          # elisp-lint
make coverage      # undercover + simplecov JSON, then a terminal summary
make complexity    # cyclomatic-complexity report, gated on the soft budget
make doctor        # transport executables present + duet loads
make test-live     # env-gated live remote tests (DUET_LIVE_TESTS)
#+end_src

* Complexity budget

=make complexity= runs =scripts/duet-complexity.el=, a homegrown McCabe branch
counter (no off-the-shelf tool measures Emacs Lisp). The budget is soft: a
function above the threshold (default 10) is split or carries a written
justification. The target is advisory — run it on demand; it is not part of
=make test=.

* Backend API

To be written with Phase 2. The published seam is =duet-register-backend=; the
stable surface is the classified-endpoint plist, the =duet-backend= struct, the
=duet-transfer-spec= plist, and the transfer-event payload. See the spec's
"Backend extension API and developer contract".