0 Fork 0

mirror of https://github.com/ruvnet/RuView.git synced 2026-10-18 21:00:22 -05:00

Files

T

Claudeandclaude-flow 888222277e feat(npm): RuView operator surface — SDK, cross-platform flashing, training, doctor (ADR-369..372)

@ruvnet/ruview 0.6.0 turns the harness into a complete npm operator
surface: one policy-checked tool registry behind the CLI, the MCP server,
and a new typed SDK.

- SDK (ADR-369): `@ruvnet/ruview/sdk` createRuView() with doctor,
  firmware.{ports,plan,flash,monitor}, training.{plan,run,gate,calibrate},
  kernel.{selfTest,load}, guidance/claimCheck/verify/spaces; strict mode
  throws RuViewError; TypeScript declarations in src/sdk.d.ts.
- Firmware (ADR-370): cross-platform `python -m esptool` flashing replaces
  the Windows-only stub. SHA256SUMS verification (mismatch always fatal),
  bundle containment, variant/partition checks, argv-only command, chip_id
  preflight that refuses a mismatched chip, boot-log capture;
  hardwareValidated only when CSI callbacks appear without a panic.
  Read-only ruview_firmware_plan / ruview_firmware_ports.
- Training (ADR-371): ruview_train / ruview_train_plan run pose-smoke,
  pose (MM-Fi), or room training from the trusted checkout with in-repo
  paths only, logs/checkpoints under v2/target/ruview-train, and libtorch
  remedies. ruview_train_gate enforces mean-pose baseline, leakage-free
  splits, subject/time disjointness, and evidence tagging.
- Doctor (ADR-372): structured pass/warn/fail/skip checks with remedies
  across runtime, integrity, hosts, repo, Rust, Python/esptool, firmware
  bundles, serial, sensing server, and the compute kernel; --json/--group;
  hardware probe and network checks are CLI/SDK-only.
- Plan tools cannot take `confirm`; acting tools keep grant+confirm over
  MCP. Policy files and TOOL_POLICY are drift-tested.
- Unpacked budget 160 KiB → 224 KiB in both npm workflows; CI tarball smoke
  now checks the SDK and the training gate.

Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_015H55jmprfz4oHWXSFbX5rf

2026-09-30 16:47:30 +00:00

2.5 KiB

Raw Blame History

ADR-372: Structured debugging doctor

Status: proposed
Date: 2026-09-30
Deciders: RuView maintainers; acceptance pending
Tags: diagnostics, onboarding, support, mcp
Related: ADR-369, ADR-370, ADR-371, docs/TROUBLESHOOTING.md

Context

Most failed RuView setups come down to a missing driver, pyserial, esptool, a wrong port, uninitialized submodules, a missing wasm32 target, or a sensing server that is not running. The old doctor checked only the harness itself, gave no remedies, and had no machine-readable output for agents.

Decision

src/doctor.js returns {ok, summary{pass,warn,fail,skip}, checks[{group,id,status,detail,remedy}], nextSteps}.

Groups:

Group	Checks
`runtime`	Node ≥ 20
`harness`	packaged-file manifest integrity, claim-guardrail self-test, reviewed brain load
`hosts`	`claude` / `codex` on PATH
`repo`	checkout, workspace submodules
`rust`	cargo, wasm32 target (run inside `v2/` so the pinned toolchain is used), `wifi-densepose` binary
`python`	interpreter, pyserial, esptool version
`firmware`	checksum verification of every `release_bins` bundle
`serial`	pyserial port enumeration; optional named port; optional chip probe
`sensing`	optional sensing-server `/health`
`kernel`	optional `@ruvnet/ruview-kernel` WASM/napi status

Rules:

fail is reserved for a requested capability that cannot work. Absent optional tooling is warn. Every non-pass check carries a remedy. The CLI exit code is non-zero only on fail.
The doctor is read-only. Two exceptions exist, both CLI/SDK options that are absent from the MCP schema:
- --probe runs esptool chip_id, which resets the board but writes nothing.
- --url makes an HTTP(S) request.
Output is human-readable by default. --json gives the structured report. --group a,b limits the scope.

Evidence

Development container (Linux x64, Node 22):

Before pip install pyserial esptool, the doctor reported them as warn with the exact pip commands.
After installation it showed esptool 5.4.0 and enumerated /dev/ttyS0.
All four firmware bundles verified.
It caught manifest drift during development, and a missing wasm32 target when run outside v2/. That second case led to the v2/ working-directory rule.

Consequences

Support threads can ask for npx @ruvnet/ruview doctor --json, and agents can act on nextSteps.
Checks run real subprocesses, so a full run takes seconds; --group keeps targeted runs fast.

2.5 KiB Raw Blame History