healthcloud-cli 3.2.4__tar.gz → 3.3.0__tar.gz

{healthcloud_cli-3.2.4 → healthcloud_cli-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.2.4
+Version: 3.3.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
@@ -56,6 +56,24 @@ uv run --frozen hc mcp tools list --audience patient
 uv run --frozen hc mcp patient get-patient --help
 ```
 
+AMS help and shell-completion discovery are credential-free and offline: they
+do not resolve root profiles, read target files, create SDK clients, or log in.
+You can inspect the group, a leaf command, and completion candidates before
+configuring credentials or a target:
+
+```bash
+uv run --frozen hc ams --help
+uv run --frozen hc ams inspect --help
+_HC_COMPLETE=bash_complete COMP_WORDS="hc ams in" COMP_CWORD=2 uv run --frozen hc
+_HC_COMPLETE=bash_complete COMP_WORDS="hc ams inspect --o" COMP_CWORD=3 uv run --frozen hc
+```
+
+Operational validation starts only when Click invokes an AMS leaf callback.
+`discover` then validates its explicit environment and tenant arguments; the
+other leaves require `--target-file` and apply the existing root, target, and
+authentication checks described below. Deferring preflight does not relax
+those safety requirements.
+
 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:
@@ -269,6 +287,54 @@ required; no MCP defaults, admin login, or automatic candidate selection are use
 uv run --frozen hc ams discover --environment dev --tenant-id TENANT_ID
 ```
 
+Read-only agent listing, inspection and export also take explicit flags instead
+of a target file, and log in as tenant admin (`HC_AMS_ADMIN_EMAIL` /
+`HC_AMS_ADMIN_PASSWORD`). Stdout carries bounded metadata only; `adapter` shows
+whether an agent runs from the `file` or `db` config adapter (`unknown` when the
+server does not say). `export` first re-checks the agent/tenant identity, then
+saves the server's own JSON/YAML export byte-for-byte to a new owner-only `--out`
+file, refusing (and leaving no file) when the body is not valid UTF-8. `export`
+needs an AMS build that serves `/agents/{agent_id}/configuration/export`; that
+route is not yet deployed to dev:
+
+```bash
+uv run --frozen hc ams agents list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams agents get --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID
+uv run --frozen hc ams agents export --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
+  --format yaml --out agent.yaml
+```
+
+Read-only department listing and inspection use the same explicit tenant-admin
+targeting. They emit one versioned JSON result on stdout; failures emit one
+categorized JSON result on stderr. Department descriptions, creator identities,
+and evaluation-suite content are never included in the projection:
+
+```bash
+uv run --frozen hc ams departments list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams departments get --environment dev --tenant-id TENANT_ID \
+  --department-id DEPARTMENT_ID
+```
+
+Department reads are complete and unpaged. The CLI does not expose department
+create, update, delete, activate, or deactivate operations.
+
+Read-only team listing and inspection are also complete and unpaged. The bounded
+projection omits descriptions and creator identities; it includes evaluation-suite
+IDs but never suite content. The CLI does not expose team mutations:
+
+```bash
+uv run --frozen hc ams teams list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams teams get --environment dev --tenant-id TENANT_ID --team-id TEAM_ID
+```
+
+The organization hierarchy is the backend-built department/team/agent tree. The
+CLI preserves its order and nesting without issuing entity reads, joining records,
+or inferring missing relationships:
+
+```bash
+uv run --frozen hc ams organization hierarchy --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
@@ -441,3 +507,44 @@ then GET plan and GET agent. Restart the stateful simulation before repeating;
 stop it with Ctrl+C afterward. This is a source-backed synthetic failure fixture,
 not the deployed service. The required CI tests exercise both pre-commit and
 post-commit 503 over loopback HTTP without requiring a Postman login or installation.
+
+
+### Installed CLI integration
+
+From the repository root, with Python 3.14, uv 0.12.5 and Node.js available:
+
+```bash
+python -m unittest discover -s tooling/cli-integration -p 'test_*.py' -v
+python tooling/cli-integration/run.py --output /tmp/hc-cli-integration
+```
+
+The runner installs the SDK, tenant-admin SDK and CLI from the frozen CLI lock
+with `uv sync --no-editable` into a fresh temporary environment outside the
+checkout. It verifies installed module ownership, version, help for every AMS
+command, native shell completion, discovery and the
+inspect/plan/show/apply/restore journey. Negative
+journeys exercise denied login, identity/qualification/plan rejection, malformed
+responses, failed readback and uncertain writes without mutation replay.
+
+The `Installed CLI integration` workflow selects its uv-installed Linux job at
+job level for `packages/cli/**`, `packages/pip/**`,
+`packages/pip-tenantadmin/**`, its own tooling/workflow, docs compiler inputs
+(`tooling/docs-compiler/**`, `docs-src/**`, `docs/sdk/**`), MCP contracts
+(`contracts/mcp/**`), and root package/lock, Python/lock and Ruff inputs. Backend-only changes skip the install job;
+the small `CLI integration` result check still runs and verifies applicability.
+Invalid selection or an applicable failed/cancelled/skipped job fails it.
+The job retains only sanitized consumer/JUnit results for seven days.
+
+All scenario records and credentials are synthetic. A test-only Python startup
+adapter preserves the canonical DEV AMS/tenant-admin origins for product
+validation while routing only those exact origins over real HTTP to an owned
+loopback fixture; other origins are refused before network access. Child
+processes use an isolated home and an allowlisted environment. The adapter is
+outside all shipped distributions. This boundary does not verify TLS or deployed
+service conformance. A verified save still exits 1 with `outcome="saved"` and
+`publication="unknown"`; publication and runtime acceptance remain unverified.
+
+Required-check activation is tracked separately in
+[services #724](https://github.com/healthcloudservices/healthcloud-services/issues/724).
+Require `CLI integration` only after the workflow is merged and both relevant
+and unrelated-change Actions results and effective settings are verified.

{healthcloud_cli-3.2.4 → healthcloud_cli-3.3.0}/README.md

@@ -38,6 +38,24 @@ uv run --frozen hc mcp tools list --audience patient
 uv run --frozen hc mcp patient get-patient --help
 ```
 
+AMS help and shell-completion discovery are credential-free and offline: they
+do not resolve root profiles, read target files, create SDK clients, or log in.
+You can inspect the group, a leaf command, and completion candidates before
+configuring credentials or a target:
+
+```bash
+uv run --frozen hc ams --help
+uv run --frozen hc ams inspect --help
+_HC_COMPLETE=bash_complete COMP_WORDS="hc ams in" COMP_CWORD=2 uv run --frozen hc
+_HC_COMPLETE=bash_complete COMP_WORDS="hc ams inspect --o" COMP_CWORD=3 uv run --frozen hc
+```
+
+Operational validation starts only when Click invokes an AMS leaf callback.
+`discover` then validates its explicit environment and tenant arguments; the
+other leaves require `--target-file` and apply the existing root, target, and
+authentication checks described below. Deferring preflight does not relax
+those safety requirements.
+
 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:
@@ -251,6 +269,54 @@ required; no MCP defaults, admin login, or automatic candidate selection are use
 uv run --frozen hc ams discover --environment dev --tenant-id TENANT_ID
 ```
 
+Read-only agent listing, inspection and export also take explicit flags instead
+of a target file, and log in as tenant admin (`HC_AMS_ADMIN_EMAIL` /
+`HC_AMS_ADMIN_PASSWORD`). Stdout carries bounded metadata only; `adapter` shows
+whether an agent runs from the `file` or `db` config adapter (`unknown` when the
+server does not say). `export` first re-checks the agent/tenant identity, then
+saves the server's own JSON/YAML export byte-for-byte to a new owner-only `--out`
+file, refusing (and leaving no file) when the body is not valid UTF-8. `export`
+needs an AMS build that serves `/agents/{agent_id}/configuration/export`; that
+route is not yet deployed to dev:
+
+```bash
+uv run --frozen hc ams agents list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams agents get --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID
+uv run --frozen hc ams agents export --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
+  --format yaml --out agent.yaml
+```
+
+Read-only department listing and inspection use the same explicit tenant-admin
+targeting. They emit one versioned JSON result on stdout; failures emit one
+categorized JSON result on stderr. Department descriptions, creator identities,
+and evaluation-suite content are never included in the projection:
+
+```bash
+uv run --frozen hc ams departments list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams departments get --environment dev --tenant-id TENANT_ID \
+  --department-id DEPARTMENT_ID
+```
+
+Department reads are complete and unpaged. The CLI does not expose department
+create, update, delete, activate, or deactivate operations.
+
+Read-only team listing and inspection are also complete and unpaged. The bounded
+projection omits descriptions and creator identities; it includes evaluation-suite
+IDs but never suite content. The CLI does not expose team mutations:
+
+```bash
+uv run --frozen hc ams teams list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams teams get --environment dev --tenant-id TENANT_ID --team-id TEAM_ID
+```
+
+The organization hierarchy is the backend-built department/team/agent tree. The
+CLI preserves its order and nesting without issuing entity reads, joining records,
+or inferring missing relationships:
+
+```bash
+uv run --frozen hc ams organization hierarchy --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
@@ -423,3 +489,44 @@ then GET plan and GET agent. Restart the stateful simulation before repeating;
 stop it with Ctrl+C afterward. This is a source-backed synthetic failure fixture,
 not the deployed service. The required CI tests exercise both pre-commit and
 post-commit 503 over loopback HTTP without requiring a Postman login or installation.
+
+
+### Installed CLI integration
+
+From the repository root, with Python 3.14, uv 0.12.5 and Node.js available:
+
+```bash
+python -m unittest discover -s tooling/cli-integration -p 'test_*.py' -v
+python tooling/cli-integration/run.py --output /tmp/hc-cli-integration
+```
+
+The runner installs the SDK, tenant-admin SDK and CLI from the frozen CLI lock
+with `uv sync --no-editable` into a fresh temporary environment outside the
+checkout. It verifies installed module ownership, version, help for every AMS
+command, native shell completion, discovery and the
+inspect/plan/show/apply/restore journey. Negative
+journeys exercise denied login, identity/qualification/plan rejection, malformed
+responses, failed readback and uncertain writes without mutation replay.
+
+The `Installed CLI integration` workflow selects its uv-installed Linux job at
+job level for `packages/cli/**`, `packages/pip/**`,
+`packages/pip-tenantadmin/**`, its own tooling/workflow, docs compiler inputs
+(`tooling/docs-compiler/**`, `docs-src/**`, `docs/sdk/**`), MCP contracts
+(`contracts/mcp/**`), and root package/lock, Python/lock and Ruff inputs. Backend-only changes skip the install job;
+the small `CLI integration` result check still runs and verifies applicability.
+Invalid selection or an applicable failed/cancelled/skipped job fails it.
+The job retains only sanitized consumer/JUnit results for seven days.
+
+All scenario records and credentials are synthetic. A test-only Python startup
+adapter preserves the canonical DEV AMS/tenant-admin origins for product
+validation while routing only those exact origins over real HTTP to an owned
+loopback fixture; other origins are refused before network access. Child
+processes use an isolated home and an allowlisted environment. The adapter is
+outside all shipped distributions. This boundary does not verify TLS or deployed
+service conformance. A verified save still exits 1 with `outcome="saved"` and
+`publication="unknown"`; publication and runtime acceptance remain unverified.
+
+Required-check activation is tracked separately in
+[services #724](https://github.com/healthcloudservices/healthcloud-services/issues/724).
+Require `CLI integration` only after the workflow is merged and both relevant
+and unrelated-change Actions results and effective settings are verified.

healthcloud_cli-3.3.0/healthcloud_cli/ams/agents/__init__.py

@@ -0,0 +1,5 @@
+"""Read-only AMS agent command domain."""
+
+from .group import create_agents_group
+
+__all__ = ["create_agents_group"]

healthcloud_cli-3.3.0/healthcloud_cli/ams/agents/commands.py

@@ -0,0 +1,83 @@
+"""Fresh Click adapters for read-only agent operations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ..compatibility import safe_errors
+from ..context import AmsDependencies, pass_ams, preflight_agents
+from ..output import metadata
+from ..target import TenantTarget
+from .operations import AgentReadRefused, export_agent, get_agent, list_agents
+
+
+def _environment(function):
+    return click.option("--environment", type=click.Choice(["dev", "uat", "prod"]), required=True)(function)
+
+
+def _tenant(function):
+    return click.option("--tenant-id", required=True)(function)
+
+
+def _agent(function):
+    return click.option("--agent-id", required=True)(function)
+
+
+def _run(operation, *args):
+    try:
+        return operation(*args)
+    except AgentReadRefused as exc:
+        raise click.ClickException(str(exc)) from None
+
+
+def create_list_command(dependencies: AmsDependencies) -> click.Command:
+    @click.command("list")
+    @_environment
+    @_tenant
+    @pass_ams
+    @safe_errors
+    def command(invocation, environment: str, tenant_id: str) -> None:
+        preflight_agents(invocation)
+        metadata(_run(list_agents, dependencies, TenantTarget(environment, tenant_id)))
+
+    return command
+
+
+def create_get_command(dependencies: AmsDependencies) -> click.Command:
+    @click.command("get")
+    @_environment
+    @_tenant
+    @_agent
+    @pass_ams
+    @safe_errors
+    def command(invocation, environment: str, tenant_id: str, agent_id: str) -> None:
+        preflight_agents(invocation)
+        metadata(_run(get_agent, dependencies, TenantTarget(environment, tenant_id), agent_id))
+
+    return command
+
+
+def create_export_command(dependencies: AmsDependencies) -> click.Command:
+    @click.command("export")
+    @_environment
+    @_tenant
+    @_agent
+    @click.option("--out", required=True, type=click.Path(path_type=Path, dir_okay=False))
+    @click.option("--format", "export_format", type=click.Choice(["json", "yaml"]), default="json", show_default=True)
+    @pass_ams
+    @safe_errors
+    def command(
+        invocation,
+        environment: str,
+        tenant_id: str,
+        agent_id: str,
+        out: Path,
+        export_format: str,
+    ) -> None:
+        preflight_agents(invocation)
+        target = TenantTarget(environment, tenant_id)
+        metadata(_run(export_agent, dependencies, target, agent_id, out, export_format))
+
+    return command

healthcloud_cli-3.3.0/healthcloud_cli/ams/agents/group.py

@@ -0,0 +1,18 @@
+"""Fresh agent-domain group assembly."""
+
+from __future__ import annotations
+
+import click
+
+from ..context import AmsDependencies
+from .commands import create_export_command, create_get_command, create_list_command
+
+
+def create_agents_group(dependencies: AmsDependencies) -> click.Group:
+    @click.group("agents")
+    def group() -> None:
+        """Read-only agent listing, inspection and export for one explicit tenant."""
+
+    for factory in (create_list_command, create_get_command, create_export_command):
+        group.add_command(factory(dependencies))
+    return group

healthcloud_cli-3.3.0/healthcloud_cli/ams/agents/operations.py

@@ -0,0 +1,72 @@
+"""Click-free orchestration for agent list, get, and exact-text export."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Literal
+
+from ..context import AmsDependencies
+from ..output import private_text_output
+from ..target import TenantTarget
+from .projections import detail, summary
+
+
+class AgentReadRefused(ValueError):
+    """A stable refusal safe for the CLI adapter to expose."""
+
+
+def _agent_id(value: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise AgentReadRefused("Explicit agent ID required.")
+    return value
+
+
+def list_agents(dependencies: AmsDependencies, target: TenantTarget) -> dict:
+    with dependencies.authenticated_sdk_factory(target) as sdk:
+        agents = sdk.ams_admin.list_agents()
+    if any(agent.tenant_id != target.tenant_id for agent in agents):
+        raise AgentReadRefused("Agent/tenant identity mismatch; stopped.")
+    return {
+        "environment": target.environment,
+        "tenant_id": target.tenant_id,
+        "agents": [summary(agent) for agent in agents],
+    }
+
+
+def _verified_agent(sdk, target: TenantTarget, agent_id: str):
+    agent = sdk.ams_admin.get_agent(agent_id)
+    if agent is None or agent.id != agent_id or agent.tenant_id != target.tenant_id:
+        raise AgentReadRefused("Agent/tenant identity mismatch; stopped.")
+    return agent
+
+
+def get_agent(dependencies: AmsDependencies, target: TenantTarget, agent_id: str) -> dict:
+    agent_id = _agent_id(agent_id)
+    with dependencies.authenticated_sdk_factory(target) as sdk:
+        agent = _verified_agent(sdk, target, agent_id)
+    return {"environment": target.environment, "tenant_id": target.tenant_id} | detail(agent)
+
+
+def export_agent(
+    dependencies: AmsDependencies,
+    target: TenantTarget,
+    agent_id: str,
+    output: Path,
+    export_format: Literal["json", "yaml"],
+) -> dict:
+    agent_id = _agent_id(agent_id)
+    if export_format not in ("json", "yaml"):
+        raise AgentReadRefused("Export format must be json or yaml.")
+    with private_text_output(output) as write, dependencies.authenticated_sdk_factory(target) as sdk:
+        _verified_agent(sdk, target, agent_id)
+        text = sdk.ams_admin.export_agent_configuration(agent_id, format=export_format)
+        write(text)
+    return {
+        "environment": target.environment,
+        "tenant_id": target.tenant_id,
+        "agent_id": agent_id,
+        "path": str(output),
+        "format": export_format,
+        "sha256": hashlib.sha256(text.encode("utf-8")).hexdigest(),
+    }

healthcloud_cli-3.3.0/healthcloud_cli/ams/agents/projections.py

@@ -0,0 +1,37 @@
+"""Explicit bounded projections for agent reads."""
+
+from __future__ import annotations
+
+from healthcloud.models.ams_tuning import AgentConfig
+
+from ..output import digest
+
+ASSIGNED_REFERENCES = ("tool_ids", "skill_ids", "guardrail_ids", "policy_ids", "data_source_ids")
+
+
+def _metadata_string(value: object) -> str:
+    return value if isinstance(value, str) and value.strip() else "unknown"
+
+
+def summary(agent: AgentConfig) -> dict:
+    runtime = agent.runtime_configuration if isinstance(agent.runtime_configuration, dict) else {}
+    return {
+        "id": agent.id,
+        "name": agent.name,
+        "key": agent.key,
+        "type": agent.type,
+        "status": agent.status,
+        "active": agent.active,
+        "config_version": agent.config_version,
+        "adapter": _metadata_string(runtime.get("adapter")),
+        "runtime": _metadata_string(runtime.get("runtime")),
+    }
+
+
+def detail(agent: AgentConfig) -> dict:
+    values = {"instructions": agent.instructions, "greetings": agent.greetings}
+    return summary(agent) | {
+        "fields": sorted(values),
+        "field_hashes": {key: digest(value) for key, value in values.items()},
+        "assigned_references": {key: getattr(agent, key) for key in ASSIGNED_REFERENCES},
+    }

{healthcloud_cli-3.2.4 → healthcloud_cli-3.3.0}/healthcloud_cli/ams/auth.py

@@ -8,17 +8,21 @@ import click
 from healthcloud import HCSDK
 from healthcloud_tenantadmin import HCTenantAdminSDK
 
-from .target import AmsTarget
+from .target import AmsTarget, TenantTarget
 
 
 @contextmanager
-def authenticated_sdk(target: AmsTarget):
+def authenticated_sdk(target: AmsTarget | TenantTarget):
     sdk = HCSDK(environment=target.environment, tenant_id=target.tenant_id)
     try:
         if not hasattr(sdk, "ams_admin"):
             raise click.ClickException(
                 "SDK missing ams_admin; use the reviewed local editable SDK checkout (see CLI README)."
             )
+        if isinstance(target, TenantTarget) and not hasattr(sdk.ams_admin, "list_agents"):
+            raise click.ClickException(
+                "SDK missing ams_admin agent listing; use the reviewed local editable SDK checkout (see CLI README)."
+            )
         email = os.environ.get("HC_AMS_ADMIN_EMAIL")
         password = os.environ.get("HC_AMS_ADMIN_PASSWORD")
         if not email or not password:

healthcloud_cli-3.3.0/healthcloud_cli/ams/commands.py

@@ -0,0 +1,28 @@
+"""Legacy AMS command imports backed by one compatibility assembly."""
+
+from .compatibility import safe_errors
+from .group import create_ams_group
+
+ams = create_ams_group()
+agents = ams.commands["agents"]
+discover = ams.commands["discover"]
+inspect = ams.commands["inspect"]
+plan = ams.commands["plan"]
+show = ams.commands["show"]
+apply = ams.commands["apply"]
+restore = ams.commands["restore"]
+ui = ams.commands["ui"]
+
+__all__ = [
+    "ams",
+    "agents",
+    "apply",
+    "create_ams_group",
+    "discover",
+    "inspect",
+    "plan",
+    "restore",
+    "safe_errors",
+    "show",
+    "ui",
+]