healthcloud-cli 3.1.1__tar.gz → 3.2.0__tar.gz

healthcloud_cli-3.2.0/PKG-INFO

@@ -0,0 +1,405 @@
+Metadata-Version: 2.5
+Name: healthcloud-cli
+Version: 3.2.0
+Summary: Command-line interface for the HealthCloud MCP gateway, generated from the shared MCP tool manifest.
+Project-URL: Issues, https://github.com/healthcloudservices/healthcloud-services/issues
+Project-URL: Repository, https://github.com/healthcloudservices/healthcloud-services
+Author: Healthcheck Systems Inc
+License-Expression: MIT
+Keywords: cli,health-cloud,healthcare,healthcloud,mcp
+Requires-Python: >=3.14
+Requires-Dist: click>=8.1
+Requires-Dist: healthcloud-sdk>=0.9.0
+Requires-Dist: healthcloud-tenantadmin>=1.1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# healthcloud-cli
+
+Requires **Python 3.14 or newer**.
+
+`hc` provides the HealthCloud MCP gateway and bounded deployed AMS administration.
+The `hc mcp` subtree has exactly one subcommand per
+MCP tool -- generated dynamically at startup from a shared manifest across
+audiences such as `patient`, `fieldagent`, `ehr`, `vitals`, `diagnostics`,
+`appointments`, `graph`, `person`, `provider`, `tenantadmin`, `connectors`,
+and `telehealth`. Run `hc mcp tools list` to see the exact, current set for
+your installed version. Nothing here is hand-written per tool: the same
+manifest also drives the sibling NPM CLI (`@healthcloud CLI` in
+`packages/cli/npm`), so command names match exactly between the two.
+
+## Install
+
+```bash
+pip install healthcloud-cli
+```
+
+This installs the `hc` console script plus its dependency, the
+[`healthcloud-sdk`](../../pip) package, which does the actual HTTP/JSON-RPC
+work against the MCP gateway.
+
+## Local development
+
+Use uv 0.12.5 and Python 3.14. The package's uv source override installs the
+SDK checkout in editable mode; its committed lock includes the test and build
+tools. Released package consumers can still use pip.
+
+```bash
+cd packages/cli/pip
+uv lock --check
+uv sync --frozen --extra dev
+uv run --frozen --extra dev python -m pytest
+uv run --frozen hc --help
+uv run --frozen hc mcp tools list --audience patient
+uv run --frozen hc mcp patient get-patient --help
+```
+
+The bundled tool manifest (`healthcloud_cli/contracts/mcp-tools.manifest.json`)
+is a copy of `packages/cli/contracts/mcp-tools.manifest.json`. Re-sync it
+after pulling manifest changes with:
+
+```bash
+python scripts/bundle_manifest.py
+```
+
+This also runs automatically as a hatchling build hook whenever you `python
+-m build`, so a built wheel/sdist is always self-contained and never depends
+on a relative path outside the installed package.
+
+## Authentication & configuration
+
+Every command accepts these global options (place them before the `mcp`
+subcommand):
+
+| Flag              | Env var           | Meaning                                      |
+|-------------------|--------------------|-----------------------------------------------|
+| `--access-token`  | `HC_ACCESS_TOKEN`  | Bearer token sent to the MCP gateway          |
+| `--base-url`      | `HC_MCP_BASE_URL`  | Override the MCP gateway base URL             |
+| `--profile`       | `HC_PROFILE`       | Named profile (see below)                     |
+| `--output`        | --                  | `pretty` (default) \| `json` \| `raw`         |
+| `--raw`           | --                  | Shortcut for `--output raw`                   |
+| `--verbose`       | --                  | Print request diagnostics to stderr           |
+
+Precedence, highest wins: **explicit CLI flag > environment variable >
+profile file value > built-in default** (`environment` defaults to `"dev"`;
+`accessToken`/`baseUrl` default to unset). The resolved access token is never
+written to logs, generated files, or test snapshots.
+
+### Optional profile file
+
+`~/.healthcloud/cli/profiles.json`:
+
+```json
+{
+  "dev-mia": {
+    "baseUrl": "https://dev-api-mcp.health.cloud",
+    "accessToken": "eyJ...",
+    "environment": "dev"
+  }
+}
+```
+
+A missing profiles file is not an error -- profiles are entirely optional. If
+`--profile`/`HC_PROFILE` names a profile and the file (or that entry) is
+missing, `hc` exits with a clear usage error rather than silently ignoring
+it.
+
+```bash
+# get-patient is self-service — the patient is resolved from the access
+# token, so no --patient-id flag exists.
+hc --profile dev-mia mcp patient get-patient
+```
+
+## Listing and inspecting tools
+
+```bash
+# Local (bundled manifest, no network call)
+hc mcp tools list
+hc mcp tools list --audience patient
+
+# Live gateway (requires --audience)
+hc mcp tools list --audience patient --remote
+
+# Full manifest entry for one tool (description, inputSchema, method/path)
+hc mcp tools show patient add_insurance --output json
+```
+
+## Calling a tool
+
+Every manifest tool is its own subcommand, grouped by audience:
+
+```bash
+hc mcp patient get-patient
+hc mcp appointments book-appointment --patient-id patient-123 --slot-id slot-456
+
+# Every Diagnostics tool takes an explicit --patient-id — providers and
+# field agents legitimately look up or record diagnostics for a patient
+# other than themselves. When the caller holds a patient token, the backend
+# enforces server-side that --patient-id must be their own (403 otherwise).
+hc mcp diagnostics create-rapid-test --patient-id patient-123 --test-type covid-19 --result negative
+```
+
+Run `--help` on any generated command to see its real manifest description
+and arguments:
+
+```bash
+hc mcp patient get-patient --help
+```
+
+### Argument flags
+
+- **Primitive properties** (`string`/`number`/`integer`/`boolean`) become a
+  normal flag in kebab-case, e.g. `patient_id` -> `--patient-id`.
+  - `enum` values are validated; invalid values are rejected before any
+    network call.
+  - `minimum`/`maximum`/`exclusiveMinimum`/`exclusiveMaximum` are enforced
+    the same way.
+  - Boolean properties are a tri-state flag pair: `--flag/--no-flag`.
+    Passing neither leaves the value unset (falls back to the manifest
+    default or an `--input`/`--stdin` value, if any); passing one sets it
+    explicitly to `true`/`false`.
+- **Object/array properties are never flattened.** They get a single
+  `--<prop>-json` flag that takes a raw JSON string, e.g.:
+
+  ```bash
+  # create-medication is self-service — no --patient-id flag; the patient is
+  # resolved server-side from the access token.
+  hc mcp patient create-medication \
+    --name "Metformin" \
+    --dosage-json '{"value":10,"unit":"mg","frequency":"once_daily"}'
+  ```
+- Path parameters (from `{placeholders}` in the tool's HTTP path) are always
+  required, in addition to whatever `inputSchema.required` lists.
+
+### Bulk input: `--input` / `--stdin`
+
+```bash
+hc mcp appointments book-appointment --input request.json
+cat request.json | hc mcp appointments book-appointment --stdin
+```
+
+`--input <file>` and `--stdin` both supply a *base* JSON object of
+arguments. `--input` and `--stdin` cannot be combined. Merge precedence
+(highest wins): **manifest defaults < `--input`/`--stdin` object < explicit
+flags** -- i.e. an explicit flag you actually pass always overrides the same
+key coming from a file or stdin, which in turn overrides the schema default.
+
+After merging, the final object is validated against the tool's
+`inputSchema` (required fields present, correct types, enum membership,
+numeric bounds). Any validation failure prints a clear message to stderr and
+exits **2**, without making a network call.
+
+### `hc mcp call` -- generic escape hatch
+
+`hc mcp call` dispatches to any MCP tool by its exact snake_case tool name --
+including one not yet present in the bundled manifest (the tool name itself
+is never validated against the manifest, it's just forwarded):
+
+```bash
+# get_patient is self-service and takes no arguments — {} is a complete,
+# valid call.
+hc mcp call patient get_patient --input '{}'
+hc mcp call patient get_patient --input-file request.json
+cat request.json | hc mcp call patient get_patient --stdin
+```
+
+Note the deliberate inconsistency versus named commands: here `--input` takes
+an inline JSON **value**, not a file path -- use `--input-file` for a file.
+Exactly one of `--input` / `--input-file` / `--stdin` may be given (or none,
+meaning `{}`).
+
+## Output modes
+
+The MCP tool-call result is `{ content: [{type:"text", text: "..."}],
+is_error: bool }` from the JSON-RPC response's `.result`, or the JSON-RPC
+`.error` object if the gateway returned one.
+
+- **`pretty`** (default): if `content[0].text` parses as JSON, pretty-prints
+  the parsed value; otherwise prints the raw text. On a JSON-RPC error,
+  prints `error.message` (and `error.code` with `--verbose`) to stderr.
+- **`json`**: prints the tool result's parsed JSON (or raw text if
+  unparseable) to stdout, with no envelope.
+- **`raw`**: prints the complete JSON-RPC envelope (`id`, `jsonrpc`,
+  `result`, `error`) as returned by the gateway.
+
+Diagnostics and `--verbose` logs always go to stderr -- stdout stays
+pipeable in every mode.
+
+## Exit codes
+
+| Code | Meaning                                                              |
+|------|-----------------------------------------------------------------------|
+| `0`  | Success                                                                |
+| `2`  | Local input validation failure (bad JSON, missing required field, invalid enum/number, `--input`+`--stdin` both given, unknown option) -- no network call made |
+| `3`  | HTTP/network failure talking to the MCP gateway                       |
+| `4`  | JSON-RPC error response (`.error` is not `None`)                      |
+| `5`  | MCP tool result reported `is_error: true`                             |
+
+## Building
+
+```bash
+uv lock --check
+uv run --frozen python -m build --no-isolation
+uv run --frozen python -m zipfile -l dist/*.whl   # confirm the bundled manifest is included
+```
+
+## Deployed AMS administration (source checkout)
+
+The reviewed AMS administration SDK is not published yet. Use this checkout's
+editable SDK and tenant-admin sources; no released SDK version is claimed to
+contain `ams_admin`. An installed SDK missing that capability is refused before
+login. Ordinary MCP commands keep their existing behavior.
+
+Prepare ignored SDK build READMEs from tracked inputs, then install the locked
+editable packages (the CLI README itself is tracked):
+
+```bash
+node tooling/docs-compiler/prepare-package-readmes.mjs
+cd packages/cli/pip
+uv sync --frozen --extra dev
+uv run --frozen hc ams --help
+```
+
+Bootstrap candidate IDs with the public SDK discovery endpoint. Both flags are
+required; no MCP defaults, admin login, or automatic candidate selection are used:
+
+```bash
+uv run --frozen hc ams discover --environment dev --tenant-id TENANT_ID
+```
+
+Every other command requires an explicit local, non-secret target JSON file.
+Only the canonical HTTPS AMS origin for that environment is accepted; custom
+origins require separately verified support. Target and nested qualification keys
+are strict. Unknown/unavailable qualification may be represented by omitted
+records or empty qualification `{}` for inspection/UI, but blocks planning.
+
+The following is a **schema example**, not evidence of deployed CareCo eligibility.
+Replace its assertions only after an operator has established the corresponding
+proof. `deployed_build` and `proof_ref` are references, never credentials:
+
+```json
+{
+  "schema_version": 1,
+  "environment": "dev",
+  "tenant_id": "TENANT_ID",
+  "agent_id": "EXPLICIT_SELECTED_AGENT_ID",
+  "api_origin": "https://dev-amsservices.health.cloud",
+  "qualification": {
+    "runtime": {"source": "OPERATOR_VERIFIED_RUNTIME", "proof_ref": "RUNTIME_PROOF"},
+    "instructions": {"source": "agent.instructions", "proof_ref": "INSTRUCTION_SOURCE_PROOF"},
+    "greetings": {"source": "agent.greetings", "proof_ref": "GREETING_SOURCE_PROOF"},
+    "backend_model_context": {
+      "deployed_build": "OPERATOR_VERIFIED_DEPLOYED_REVISION",
+      "config_version": 7,
+      "proof_ref": "FULL_INPUT_AND_WRITER_COVERAGE_REVIEW_PROOF",
+      "current_build_confirmed": true,
+      "fresh_session": true,
+      "no_attachments_or_history": true,
+      "full_inputs_approved": true,
+      "change_path_without_logs": true
+    }
+  }
+}
+```
+
+Qualification is an operator assertion with evidence, never authorization.
+Server-side tenant-admin authorization remains mandatory. No current-build API is
+established: the CLI cannot automatically detect an unreported deployment, verify
+actual runtime consumption, attest deployed all-writer coverage, or audit model
+inputs. A changed/unavailable build or agent configuration invalidates the review;
+the operator must refresh the record. The recorded config version must equal the
+inspected version before planning/apply/restore.
+`full_inputs_approved` means an operator approved non-sensitive **full planner and
+reviewer inputs**, including custom_tools, catalogs, all agent fields, and all other
+server context. Output projection does not sanitize server-side model context.
+`change_path_without_logs` requires evidence that the exact deterministic modify
+request uses the change path, avoiding the direct-answer branch's recent logs.
+Unknown effective sources and file-backed/ignored instructions block tuning.
+
+Before `plan`, `apply` or selected-field `restore`, the operator must review evidence
+that the actual serving build includes **all writer version coverage**: ordinary
+agent updates and startup/migration repair writers advance `config_version`
+atomically with their changes, and tuning apply uses transactional compare-and-set
+against the expected version. Bind this coverage evidence and the full-input
+review together in the existing `qualification.backend_model_context.proof_ref`
+review bundle for its `deployed_build`, inspected `config_version` and
+`current_build_confirmed` assertion. AMS source prerequisites
+[#488](https://github.com/healthcloudservices/healthcloud-ams-services/pull/488) and
+[#497](https://github.com/healthcloudservices/healthcloud-ams-services/pull/497)
+are evidence leads; source tests, PR merges, or a numeric `config_version` alone
+cannot prove coverage in the serving build. If deployed identity or any writer's
+coverage is unknown, or a writer still bypasses version advancement, stop
+`plan`/`apply`/`restore`; bounded read-only inspection/UI may continue under their
+existing limits. Refresh this evidence after a changed/unknown build or agent
+configuration and recheck it before apply and selected-field restore. This is an
+operator prerequisite: the current CLI does not automatically attest deployment
+or all-writer coverage, and the record adds no server authorization boundary.
+
+Credentials enter only through `HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD`
+in the current process, intended for composition with the existing
+`onepassword-env` wrapper. Each invocation logs in through `HCTenantAdminSDK`;
+tokens remain private in memory. There is no token cache, fallback identity,
+secret argument, resolved env file, or browser credential bridge. Root MCP
+`--access-token`, `--base-url`, their environment equivalents, and token/base-URL
+profiles are refused for AMS. Root profile environment values do not select AMS.
+
+```bash
+uv run --frozen hc ams --target-file TARGET.json inspect
+uv run --frozen hc ams --target-file TARGET.json inspect --out PRIVATE_INSPECTION.json
+uv run --frozen hc ams --target-file TARGET.json plan --changes-file PRIVATE_CHANGES.json --out PRIVATE_RECEIPT.json
+uv run --frozen hc ams --target-file TARGET.json show --receipt PRIVATE_RECEIPT.json --out PRIVATE_DIFF.json
+uv run --frozen hc ams --target-file TARGET.json apply --receipt PRIVATE_RECEIPT.json --confirm-plan-hash DISPLAYED_HASH
+uv run --frozen hc ams --target-file TARGET.json restore --receipt PRIVATE_RECEIPT.json --out PRIVATE_RESTORE_RECEIPT.json
+uv run --frozen hc ams --target-file TARGET.json ui --repo EXISTING_AMS_WORKTREE
+```
+
+Changes JSON accepts only nonempty subsets of `instructions` (string) and
+`greetings` (language-key to string map). Input changes/receipts must be regular,
+owner-only files (for example create under `umask 077`). Outputs use exclusive
+0600 creation and refuse overwrite/symlinks; failed operations remove unfinished
+outputs. No whole-agent snapshot is saved. Free text appears only in explicitly
+requested private files for human review before any AI use. Default output in
+pretty/json/verbose modes contains bounded metadata and hashes; AMS refuses raw.
+
+The planner receives `Update the agent configuration to exactly these field
+values: ` followed by sorted, compact requested JSON. Extra fields, files,
+validation errors, warnings/skipped references, blocking or unknown review
+findings, and approximate wording are refused. Each immutable field change must
+include `before` and exact `after` values so a modified receipt cannot redefine a
+restore. A server plan omitting `before` cannot safely support this workflow;
+review/replan rather than synthesizing server provenance. `show`/`apply` reload the
+immutable backend plan/hash. Before apply, recheck the deployed coverage and
+full-input qualification above. Apply requires the displayed hash, matching
+version and selected before-values, and sends `confirm=True` once. HTTP 401/403
+and 409 never trigger identity fallback or mutation replay.
+
+On transport failure, apply records an unknown outcome and reconciles through GET
+plan/agent without retrying the mutation. Confirmed saves require applied status,
+selected-field readback and exactly the next config version. The current public
+response omits publication_status: **saved/readback confirmed is reported separately
+from publication unknown and runtime unverified**, with nonzero exit status for
+complete success. `publish_failed` is reported separately. Do not replay a saved
+apply to resolve publication. A fresh invocation refuses an already consumed plan.
+
+Restore creates a new reviewed plan from only the selected fields' authoritative
+before-values against the latest config version. Unrelated edits are preserved;
+a current same-field mismatch blocks restore. There is no force restore. Refresh
+operator qualification, including deployed all-writer coverage and full-input
+evidence, for the latest build/version first, then review the new
+restore receipt with `show` and confirm its new hash with `apply`.
+
+UI launch validates the existing `test-client-ui/package.json` Vite script,
+refuses lifecycle hooks, and invokes `npm run dev -- --host 127.0.0.1` by argv
+with `shell=False`. It installs nothing and launches no backend. The allowlisted
+child environment includes toolchain essentials plus only these public target
+variables: `VITE_API_URL`, `VITE_HEALTHCLOUD_ENVIRONMENT`, `VITE_TUNING_TENANT_ID`,
+`VITE_TUNING_AGENT_ID`. Injected HC/OP credentials and other VITE/NODE/NPM options
+are excluded. It prints `/app/agents/{agent_id}`; browser login remains separate.
+The supplied existing worktree and its local frontend configuration remain
+operator-controlled.
+
+AMS failures exit nonzero with safe categories, never backend exception bodies.
+In particular, apply may exit nonzero after a confirmed save because publication
+is unknown: inspect the emitted outcome before any next action.