Healthmd CLI Development

Standalone Health.md CLI Development

The public portable CLI does not depend on the Health.md macOS app. Treat the Rust CLI and iPhone direct service as one cross-component product joined by a versioned protocol.

standalone Rust healthmd (`mcp serve`) on macOS / Linux / Windows
  TCP listener :17647
  ← authenticated encrypted Manual IP/Tailscale channel →
foreground Health.md iPhone direct service
  → HealthKit / production exporters / protected spool
  → bounded query pages or durable transfer → MCP/JSON output or explicit destination

The iPhone owns HealthKit permission, protected-data checks, quota, canonical capture, and production file generation. Rust owns pairing identity, native credentials, listener transport, durable receiver state, validation, output, and safe destination commits.

The legacy Swift CLI, Mac loopback backend, encrypted Mac query context, bundled Swift MCP helper, and apps/apple/scripts/healthmd wrapper are compatibility surfaces, not standalone implementation targets. The portable Rust MCP server uses direct iPhone query protocol v3. Never make portable commands depend on Mac app availability or localhost.

Code map

Rust workspaces

packages/healthmd-core-rust and apps/cli are independent Cargo workspaces with independent lockfiles. Run Cargo in the workspace that owns the changed crate; do not regenerate one lockfile while validating the other.

Apple component

Portable logic belongs in Rust; HealthKit/export generation stays on iPhone. Do not implement standalone behavior in apps/apple/HealthMdCLI/ unless explicitly maintaining the legacy Swift client too.

Invariants

• Direct is the only execution path; the CLI has no backend option and never depends on the Mac app or localhost.
• Manual IP/Tailscale is portable. Nearby must return transport_unsupported in Rust.
• Structured outcomes and argument failures share one canonical JSON model. Interactive terminals render it as readable text; pipes and --json emit JSON, while --human forces text. Help/version are text, exact artifacts bypass rendering, and pairing instructions or health-free progress may use stderr.
• Never place health payloads in logs, diagnostics, fixtures, panic text, telemetry, or test reports.
• Direct CLI Access is opt-in. Pairing, idle reconnect, and new work need foreground iPhone. Only an already-connected export gets finite iOS background time; expiration pauses durable work.
• Direct trust is separate from Mac sync trust. Credentials use Keychain, Secret Service, or Windows Credential Manager. Never fall back to plaintext.
• Preserve explicit device and port. Never switch peer, port, or transport silently.
• Peer/install binding, dates, destination, settings, request fingerprint, manifests, partition chain, and committed frontier are immutable across resume.
• Timeout, Ctrl-C, process death, disconnect, background expiry, or local wake-wait cancellation never means phone-side cancellation. Only mobile acknowledgement is terminal.
• RFC-0005 keeps unavailable query/export/resume/cancel requests in one shared 120-second wake window (--wake-timeout; MCP HEALTHMD_WAKE_TIMEOUT) with 250 ms to 2 s retries. It emits only health-free progress. Wake enrollment is reported truthfully per selected device from the stored wake credential: unavailable/wait_only when absent, available/enrolled when the paired phone enrolled.
• Strict raw/extract validate the complete disk spool before exposure. Incomplete extract emits no values without --allow-partial.
• File mode requires an existing absolute destination, production iPhone exporters, bounded transfer, and restart-safe overwrite/append/Markdown merge receipts.
• Protocol v1 destination text is opaque on iPhone. The receiving host validates and binds an existing native absolute non-symlink directory before sending; file mode works on macOS, Linux, and Windows.
• healthmd.health_data is the public source shape. Projections must not masquerade as complete daily documents.
• Before changing exporter/metric/unit/JSON/CSV/Markdown/frontmatter/data-dictionary/schema output, read apps/apple/docs/features/export-schema.md and follow version/signature rules.

Protocol v1

Port 17647 is distinct from old Mac sync/control ports. Preserve deployed bounds unless a negotiated version changes them:

• maximum outer JSON packet: 2 MiB;
• binary chunk body: 512 KiB;
• partitions: 32–64 MiB, 48 MiB preferred;
• bounded in-flight window;
• pairing code lifetime: 10 minutes;
• durable job lifetime: seven days;
• SHA-256 request/partition/result digests;
• ChaCha20-Poly1305 channel with monotonic direction sequences.

Protocol v1 still advertises wire role macos_cli for deployed compatibility even though Rust is portable. Do not rename it casually.

Swift synthesized Codable is not the specification. The normative contract is packages/contracts/direct-protocol/v1/protocol.md plus the Swift-generated fixture in packages/contracts/direct-protocol/v1/fixtures/swift-reference.json. The Rust crate-local copy is a packaging mirror and must remain byte-identical.

These normally require a new negotiated version rather than an additive v1 edit:

• cryptographic transcripts/domain strings;
• canonical JSON/fingerprint rules;
• associated-value enum layout;
• packet/binary-frame encoding;
• UUID, Data, optional, or date encoding;
• unknown discriminators old decoders cannot safely ignore.

Cross-component workflow

1. Classify ownership: CLI grammar/output in Rust; HealthKit/export generation on iPhone; wire behavior in both.
2. Decide if local, additive v1, capability-gated, or protocol v2.
3. Update explicit/normative protocol contracts before implementation accidents become the spec.
4. Implement pure protocol behavior in healthmd-protocol without networking/storage/logging.
5. Put transport, credentials, durable state, validation, and commits in healthmd-client.
6. Keep healthmd-cli to arguments, JSON, progress, artifacts, and exit status.
7. Implement matching Swift and persist immutable scope before capture/transfer.
8. Update conformance fixtures/tests; fixture changes require evidence Swift generated them.
9. Run both automated gates and physical iPhone QA.
10. Update docs, changelogs, compatibility version, and release notes in both repos.

Never update one side of a wire change and call it complete.

Common changes

CLI flag or command

1. Parse/validate in apps/cli/crates/healthmd-cli/src/main.rs.
2. Keep domain/security logic outside the parser.
3. Add explicit Rust/Swift protocol fields when semantics cross the wire.
4. Pin exact request before network work.
5. Treat omitted execution requirements as local discovery where safe: return healthmd.cli_guidance/1 with request_sent: false, requirements, examples, and next actions. Keep malformed/contradictory input and runtime failures nonzero, deterministic, privacy-safe healthmd.cli_error/1; never embed rejected values or escaped Clap output.
6. Update parser/client/protocol/iPhone tests, help, README, operator guidance, and QA.

Do not add --iphone; standalone already means direct iPhone.