healthcloud-cli 0.1.0__py3-none-any.whl

healthcloud_cli/__init__.py

@@ -0,0 +1,4 @@
+"""HealthCloud CLI: `hc mcp <audience> <command>` generated from the shared MCP tool manifest."""
+
+__version__ = "0.1.0"
+

healthcloud_cli/cli.py

@@ -0,0 +1,275 @@
+"""The ``hc`` command line tool.
+
+The entire ``hc mcp <audience> <command>`` tree is built dynamically at
+import time from the bundled MCP tool manifest (see ``manifest.py``) -- there
+is exactly one generated Click command per manifest tool, never hand-written
+per-tool source files.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import click
+
+from . import manifest as manifest_module
+from .context import CliConfig, resolve_config
+from .output import dispatch, dump_rpc_result, read_stdin
+from .params import ParamSpec, build_param_specs, make_click_option, merge_arguments, validate_final
+from .util import parse_json_text
+
+EXIT_VALIDATION_ERROR = 2
+
+
+# --------------------------------------------------------------------------- #
+# Per-tool command (`hc mcp <audience> <cli-command>`)
+# --------------------------------------------------------------------------- #
+
+
+def _resolve_base_object(input_file: Optional[str], use_stdin: bool) -> dict[str, Any]:
+    if input_file and use_stdin:
+        raise click.UsageError("--input and --stdin cannot be used together.")
+    if input_file:
+        text = Path(input_file).read_text(encoding="utf-8")
+        base = parse_json_text(text, source=f"--input file '{input_file}'")
+    elif use_stdin:
+        base = parse_json_text(read_stdin(), source="stdin")
+    else:
+        return {}
+    if not isinstance(base, dict):
+        raise click.UsageError("The --input/--stdin JSON value must be a JSON object.")
+    return base
+
+
+def _tool_callback(
+    audience: dict[str, Any], tool: dict[str, Any], param_specs: list[ParamSpec], **kwargs: Any
+) -> None:
+    ctx = click.get_current_context()
+    cfg: CliConfig = ctx.obj
+
+    input_file = kwargs.pop("input_file")
+    use_stdin = kwargs.pop("use_stdin")
+    base = _resolve_base_object(input_file, use_stdin)
+
+    merged = merge_arguments(tool, param_specs, base, kwargs)
+
+    errors = validate_final(tool, merged)
+    if errors:
+        for error in errors:
+            click.echo(error, err=True)
+        raise SystemExit(EXIT_VALIDATION_ERROR)
+
+    dispatch(cfg, audience["name"], tool["name"], merged)
+
+
+def make_tool_command(audience: dict[str, Any], tool: dict[str, Any]) -> click.Command:
+    param_specs = build_param_specs(tool)
+    params: list[click.Parameter] = [make_click_option(spec) for spec in param_specs]
+    params.append(
+        click.Option(
+            ["--input", "input_file"],
+            type=click.Path(exists=True, dir_okay=False),
+            default=None,
+            help="Path to a JSON file with base arguments (overridden by explicit flags).",
+        )
+    )
+    params.append(
+        click.Option(
+            ["--stdin", "use_stdin"],
+            is_flag=True,
+            default=False,
+            help="Read base arguments as JSON from stdin (overridden by explicit flags).",
+        )
+    )
+
+    callback = functools.partial(_tool_callback, audience, tool, param_specs)
+    return click.Command(
+        name=tool["cliCommand"],
+        params=params,
+        callback=callback,
+        help=tool["description"],
+    )
+
+
+# --------------------------------------------------------------------------- #
+# `hc mcp tools list` / `hc mcp tools show`
+# --------------------------------------------------------------------------- #
+
+
+@click.command("list")
+@click.option("--audience", default=None, help="Filter to a single audience (e.g. patient).")
+@click.option("--remote", is_flag=True, default=False, help="Query the live gateway instead of the bundled manifest.")
+@click.pass_context
+def tools_list(ctx: click.Context, audience: Optional[str], remote: bool) -> None:
+    """List MCP tools. Reads the bundled manifest by default (no network call)."""
+    cfg: CliConfig = ctx.obj
+
+    if audience is not None and manifest_module.get_audience(audience) is None:
+        raise click.UsageError(f"Unknown audience: '{audience}'")
+
+    if remote:
+        if not audience:
+            raise click.UsageError("--remote requires --audience to be specified.")
+        from .output import build_sdk
+        from healthcloud.errors import HealthCloudHTTPError, HealthCloudNetworkError
+
+        sdk = build_sdk(cfg)
+        try:
+            response = sdk.mcp.list_tools(audience)
+        except (HealthCloudHTTPError, HealthCloudNetworkError) as exc:
+            click.echo(str(exc), err=True)
+            raise SystemExit(3)
+        finally:
+            sdk.close()
+        dump_rpc_result(cfg, response)
+        return
+
+    audiences = manifest_module.audiences()
+    if audience is not None:
+        audiences = [a for a in audiences if a["name"] == audience]
+
+    rows = [
+        {
+            "audience": a["name"],
+            "cliCommand": t["cliCommand"],
+            "name": t["name"],
+            "description": t["description"],
+        }
+        for a in audiences
+        for t in a["tools"]
+    ]
+
+    if cfg.output in ("json", "raw"):
+        click.echo(json.dumps(rows, indent=2))
+    else:
+        for row in rows:
+            click.echo(f"{row['audience']} :: {row['cliCommand']} :: {row['description']}")
+
+
+@click.command("show")
+@click.argument("audience")
+@click.argument("tool_name")
+@click.pass_context
+def tools_show(ctx: click.Context, audience: str, tool_name: str) -> None:
+    """Show one tool's full manifest entry (description, inputSchema, method/path)."""
+    cfg: CliConfig = ctx.obj
+
+    tool = manifest_module.get_tool(audience, tool_name)
+    if tool is None:
+        if manifest_module.get_audience(audience) is None:
+            raise click.UsageError(f"Unknown audience: '{audience}'")
+        raise click.UsageError(f"Unknown tool '{tool_name}' in audience '{audience}'.")
+
+    if cfg.output in ("json", "raw"):
+        click.echo(json.dumps(tool, indent=2))
+        return
+
+    click.echo(f"{tool['name']} ({tool['cliCommand']})  [{audience}]")
+    click.echo(tool["description"])
+    click.echo(f"{tool['httpMethod']} {tool['httpPath']}")
+    click.echo(json.dumps(tool["inputSchema"], indent=2))
+
+
+# --------------------------------------------------------------------------- #
+# `hc mcp call <audience> <exact-tool-name>` -- generic escape hatch
+# --------------------------------------------------------------------------- #
+
+
+@click.command("call")
+@click.argument("audience")
+@click.argument("tool_name")
+@click.option("--input", "input_json", default=None, help="Inline JSON *value* for arguments (not a file path).")
+@click.option("--input-file", "input_file", type=click.Path(exists=True, dir_okay=False), default=None, help="Path to a JSON file with arguments.")
+@click.option("--stdin", "use_stdin", is_flag=True, default=False, help="Read arguments as JSON from stdin.")
+@click.pass_context
+def call_cmd(
+    ctx: click.Context,
+    audience: str,
+    tool_name: str,
+    input_json: Optional[str],
+    input_file: Optional[str],
+    use_stdin: bool,
+) -> None:
+    """Call any MCP tool by its exact tool name, even one not in the bundled manifest."""
+    cfg: CliConfig = ctx.obj
+
+    provided = [name for name, value in (("--input", input_json), ("--input-file", input_file), ("--stdin", use_stdin)) if value]
+    if len(provided) > 1:
+        raise click.UsageError(f"Only one of --input, --input-file, --stdin may be given (got {', '.join(provided)}).")
+
+    if input_json is not None:
+        arguments = parse_json_text(input_json, source="--input")
+    elif input_file is not None:
+        arguments = parse_json_text(Path(input_file).read_text(encoding="utf-8"), source=f"--input-file '{input_file}'")
+    elif use_stdin:
+        arguments = parse_json_text(read_stdin(), source="stdin")
+    else:
+        arguments = {}
+
+    if not isinstance(arguments, dict):
+        raise click.UsageError("Arguments must be a JSON object.")
+
+    dispatch(cfg, audience, tool_name, arguments)
+
+
+# --------------------------------------------------------------------------- #
+# Root group assembly
+# --------------------------------------------------------------------------- #
+
+
+@click.group()
+@click.option("--access-token", default=None, envvar="HC_ACCESS_TOKEN", help="Bearer token for the MCP gateway.")
+@click.option("--base-url", default=None, envvar="HC_MCP_BASE_URL", help="Override the MCP gateway base URL.")
+@click.option("--profile", default=None, envvar="HC_PROFILE", help="Named profile from ~/.healthcloud/cli/profiles.json.")
+@click.option("--output", "output_mode", type=click.Choice(["pretty", "json", "raw"]), default=None, help="Output format (default: pretty).")
+@click.option("--raw", "raw_flag", is_flag=True, default=False, help="Shortcut for --output raw.")
+@click.option("--verbose", is_flag=True, default=False, help="Print diagnostics to stderr.")
+@click.version_option(package_name="healthcloud-cli", prog_name="hc")
+@click.pass_context
+def hc(
+    ctx: click.Context,
+    access_token: Optional[str],
+    base_url: Optional[str],
+    profile: Optional[str],
+    output_mode: Optional[str],
+    raw_flag: bool,
+    verbose: bool,
+) -> None:
+    """HealthCloud MCP gateway CLI."""
+    ctx.obj = resolve_config(access_token, base_url, profile, output_mode, raw_flag, verbose)
+
+
+def _build_mcp_group() -> click.Group:
+    mcp_group = click.Group("mcp", help="Interact with the HealthCloud MCP gateway.")
+
+    for audience in manifest_module.audiences():
+        audience_group = click.Group(
+            audience["name"],
+            help=f"Tools for the '{audience['name']}' audience ({audience['toolCount']} tools).",
+        )
+        for tool in audience["tools"]:
+            audience_group.add_command(make_tool_command(audience, tool))
+        mcp_group.add_command(audience_group)
+
+    tools_group = click.Group("tools", help="Inspect the bundled MCP tool manifest.")
+    tools_group.add_command(tools_list)
+    tools_group.add_command(tools_show)
+    mcp_group.add_command(tools_group)
+
+    mcp_group.add_command(call_cmd)
+
+    return mcp_group
+
+
+hc.add_command(_build_mcp_group())
+
+
+def main() -> None:
+    hc()
+
+
+if __name__ == "__main__":
+    main()

healthcloud_cli/context.py

@@ -0,0 +1,80 @@
+"""Global CLI configuration: resolves auth/base-url/output settings.
+
+Precedence (highest wins): explicit CLI flag > environment variable >
+profile file value > built-in default.
+
+``click``'s ``envvar=`` option support already gives us "CLI flag beats
+environment variable" for free; this module only adds the profile-file layer
+underneath that, plus the final built-in defaults.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+import click
+
+PROFILES_PATH = Path.home() / ".healthcloud" / "cli" / "profiles.json"
+
+OutputMode = str  # "pretty" | "json" | "raw"
+
+
+@dataclass
+class CliConfig:
+    access_token: Optional[str]
+    base_url: Optional[str]
+    profile: Optional[str]
+    environment: str
+    output: OutputMode
+    verbose: bool
+
+
+def load_profile(name: Optional[str], path: Path = PROFILES_PATH) -> dict[str, Any]:
+    """Load one named profile from ``~/.healthcloud/cli/profiles.json``.
+
+    A missing profiles file is not an error as long as no profile was
+    requested. If the caller explicitly asked for a profile (``--profile`` /
+    ``HC_PROFILE``), a missing file or missing entry is a clear usage error
+    rather than a silent no-op, since a typo'd profile name should not
+    silently fall back to unauthenticated defaults.
+    """
+    if not name:
+        return {}
+    if not path.exists():
+        raise click.UsageError(f"--profile '{name}' requested but no profiles file exists at {path}")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise click.UsageError(f"Profiles file {path} is not valid JSON: {exc}") from exc
+    if name not in data:
+        raise click.UsageError(f"Profile '{name}' not found in {path}")
+    profile = data[name]
+    if not isinstance(profile, dict):
+        raise click.UsageError(f"Profile '{name}' in {path} must be a JSON object")
+    return profile
+
+
+def resolve_config(
+    access_token: Optional[str],
+    base_url: Optional[str],
+    profile: Optional[str],
+    output: Optional[str],
+    raw: bool,
+    verbose: bool,
+) -> CliConfig:
+    profile_data = load_profile(profile, path=PROFILES_PATH)
+    resolved_access_token = access_token if access_token is not None else profile_data.get("accessToken")
+    resolved_base_url = base_url if base_url is not None else profile_data.get("baseUrl")
+    resolved_environment = profile_data.get("environment", "dev")
+    resolved_output = "raw" if raw else (output or "pretty")
+    return CliConfig(
+        access_token=resolved_access_token,
+        base_url=resolved_base_url,
+        profile=profile,
+        environment=resolved_environment,
+        output=resolved_output,
+        verbose=verbose,
+    )