erpl-rev setup / doctor: close the gap between uvx erpl-rev and a working system

[jrosskopf]

What

Two new verbs. doctor diagnoses the SAP side and never writes to it; setup
diagnoses, prints the change set, asks, executes, and then proves a round trip
before claiming anything.

uvx erpl-rev doctor
uvx erpl-rev setup --dry-run
uvx erpl-rev setup

Why

Installing was already one command. Getting SAP ready was an afternoon spread
across README.md, docs/INSTALL.md, docs/security.md and
docs/enable-rfc-registration.md: a type-T destination, a function group, eight
Z_DUCKDB_* modules, fourteen ABAP objects, a reginfo line, a comm user.
scripts/deploy-abap.sh already encoded most of the sequence — but only as bash
needing a git checkout.

How

• The ABAP ships inside the binary (cmake/embed_abap.cmake, 14 production
  objects — no test drivers, no fixtures). setup has no checkout to read from.
• sapgw00 and the PROGRAM_ID are templated at deploy time. The shipped
  literal is wrong on every instance that is not 00, and it fails much later as
  an empty SYSTEM_FAILURE that names nothing.
• Honest about what a client cannot do. The gateway reginfo allow-list and
  the gw/acl_mode profile parameters are an OS file and an instance restart.
  setup writes erpl-rev-basis-handout.md, filled in for the system it just
  diagnosed, with nothing left to compose.

Decisions worth arguing about

• Every write needs consent. A terminal confirmation, or an explicit --yes.
  --non-interactive means "do not prompt" — not "yes, change my ERP system".
• Success means a proved round trip, never "the objects exist". Both classruns
  are judged by their output, not their exit code: ZCL_ERPL_REV_SETUP swallows
  RFC_MODIFY_TCPIP_DESTINATION behind EXCEPTIONS OTHERS = 9 and
  ZCL_ERPL_REV_MKFM catches cx_root, so both exit 0 having achieved nothing.
  The destination is verified out of RFCDES (registration mode, PROGRAM_ID and
  gateway service each checked) and the modules out of TFDIR (fmode=R).
• Unknown flags are now a hard error (exit 2). A server silently running with
  a typo'd flag is worse than one that refuses to start. This is an intentional
  behaviour change; the no-verb serve path is unaffected.
• The password reaches erpl-adt through the environment, never argv.

Verification

Live against A4H:

Scenario	Result
--dry-run	correct change set, nothing written
bare system (all 14 objects deleted from A4H)	doctor names what is missing and skips the round trip with a reason, exit 1; setup deploys all 14 in dependency order, creates the function group, both classruns verified, round trip proved, exit 0
e2e after a bare rebuild	all 13 stages pass — setup alone is sufficient to provision a wiped system
re-run	nothing — the SAP side is already set up., exit 0, no writes
server down	reports "the round trip did NOT complete yet", exit 1 — does not claim success
interactive TTY	prompts for user/password (no echo), offers to save, writes 0600, no password stored
--save-password	stores it, warns about clear text; a stale password is dropped on any save that does not re-consent
doctor wrong password	HTTP 401 diagnosed; dependent checks skipped, not cascaded
doctor unreachable gateway	named as the blocker with the remedy
--print-runbook	handout only, SAP untouched
doctor --json	valid JSON, 6 checks
unknown verb / unknown flag	exit 2
Windows	missing _isatty/getaddrinfo headers and a missing WSAStartup fixed — the latter would have built cleanly and then reported a healthy gateway as unreachable

Unit: 16567 assertions, 14 of them over the planner, the handout and the
classrun parsers.

Review

Two codex passes (gpt-5.5, medium), the second one specifically against the
result of the first — so the fixes were reviewed, not just the original.

Pass 1 (five findings, all addressed): the consent gate, verifying classruns by
output rather than exit code, a Windows quoting path that could silently mangle
%, --save-password/WriteConfig advertised but dead, and a doc point about
what --dry-run guarantees.

Pass 2 found four real defects in the fixes, each now rejected with a test:

• N=ERPL_REV2 satisfied an expected ERPL_REV; g=sapgw00 satisfied an
  expected sapgw0 — prefix matches on what should be exact tokens.
• Expected values appearing anywhere in the output counted, so
  opts=[] plus a diagnostic echo passed on a destination with no options.
• Eight identical Z_DUCKDB_QUERY tfdir subrc=0 fmode=R lines passed as "all
  eight modules present" while seven were missing.
• A password stored once by --save-password survived every later save that did
  not ask for it, and WriteConfig chmod'ed to 0600 only after writing the
  content under the umask.

One bug the dry run itself caught: checking a single representative object made a
system deployed before ZCL_ERPL_REV_DIAG existed look complete, so setup
planned to prove a round trip with a class it had never deployed. Regression test
included.

Also corrects docs/INSTALL.md, which claimed the setup classrun "verifies the
ZERPL_REV FMs exist; prints the exact reginfo line to add". It did neither.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}