cwms-tools 0.1.0__py3-none-any.whl

cwms_tools/__init__.py

@@ -0,0 +1,12 @@
+"""cwms-tools — agent-friendly tools for the USACE CWMS Data API."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cwms-tools")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

cwms_tools/cli/__init__.py

@@ -0,0 +1 @@
+"""Typer CLI adapter over the core."""

cwms_tools/cli/app.py

@@ -0,0 +1,127 @@
+"""Main Typer application. Subcommands are registered in `commands/`."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from cwms_tools import __version__
+from cwms_tools.cli.commands import config as config_cmd
+from cwms_tools.cli.commands import env as env_cmd
+from cwms_tools.cli.commands import fingerprint as fingerprint_cmd
+from cwms_tools.cli.commands import mcp as mcp_cmd
+from cwms_tools.cli.commands import place as place_cmd
+from cwms_tools.cli.commands import publisher as publisher_cmd
+from cwms_tools.cli.commands import region as region_cmd
+from cwms_tools.cli.commands import schema as schema_cmd
+from cwms_tools.cli.commands import value as value_cmd
+from cwms_tools.cli.commands import whoami as whoami_cmd
+from cwms_tools.cli.render import set_isolated, set_machine, set_no_cache
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"cwms-tools {__version__}")
+        raise typer.Exit(code=0)
+
+
+app = typer.Typer(
+    name="cwms-tools",
+    help=(
+        "Read-only CLI and MCP server for the USACE CWMS Data API. "
+        "Task-completing commands (search a place, get current value with "
+        "status context, browse an office's catalog) and an MCP server "
+        "(`cwms-tools mcp serve`) share one behavioral core."
+    ),
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+
+@app.callback(invoke_without_command=True)
+def _root(
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Print the cwms-tools version and exit.",
+            is_eager=True,
+            callback=_version_callback,
+        ),
+    ] = False,
+    machine: Annotated[
+        bool,
+        typer.Option(
+            "--machine",
+            help=(
+                "Machine-readable output: compact JSON on stdout, no color, "
+                "no progress indicators, no interactive prompts. "
+                "Auto-enabled when stdout is not a terminal."
+            ),
+        ),
+    ] = False,
+    json_flag: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help=(
+                "Alias for --machine. Provided so callers used to the convention "
+                "of passing --json can use it without learning a new flag."
+            ),
+        ),
+    ] = False,
+    no_cache: Annotated[
+        bool,
+        typer.Option(
+            "--no-cache",
+            help=(
+                "Bypass the on-disk catalog cache for this invocation. "
+                "Environment variables and resolved session config still apply."
+            ),
+        ),
+    ] = False,
+    isolated: Annotated[
+        bool,
+        typer.Option(
+            "--isolated",
+            help=(
+                "Bypass on-disk cache and ignore CWMS_TOOLS_* environment "
+                "variables. Useful for reproducibility checks."
+            ),
+        ),
+    ] = False,
+) -> None:
+    """Root command. Subcommands listed below; -h on any subcommand for details."""
+    if machine or json_flag:
+        set_machine(True)
+    if no_cache:
+        set_no_cache(True)
+    if isolated:
+        set_isolated(True)
+
+
+# Inspection affordances required by agent-friendly-cli when ambient state is read.
+app.add_typer(whoami_cmd.app, name="whoami")
+app.add_typer(env_cmd.app, name="env")
+app.add_typer(config_cmd.app, name="config")
+app.add_typer(fingerprint_cmd.app, name="fingerprint")
+app.add_typer(schema_cmd.app, name="schema")
+
+# Place / region task tools (M4).
+app.add_typer(place_cmd.app, name="place")
+app.add_typer(region_cmd.app, name="region")
+
+# Value task tools (M5).
+app.add_typer(value_cmd.app, name="value")
+
+# Publisher index helper (M6).
+app.add_typer(publisher_cmd.app, name="publisher")
+
+# MCP server (M7).
+app.add_typer(mcp_cmd.app, name="mcp")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

cwms_tools/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI subcommand modules. Each noun (place, value, region, ...) lives in its own module."""

cwms_tools/cli/commands/config.py

@@ -0,0 +1,73 @@
+"""`cwms-tools config show --resolved` — emit effective config after precedence merge."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from cwms_tools.cli.commands.env import READ_VARS, SECRET_VARS
+from cwms_tools.cli.render import emit
+from cwms_tools.core.cache import resolve_cache_dir
+from cwms_tools.core.concurrency import MAX_WORKERS
+from cwms_tools.core.session import resolve_session_config
+
+app = typer.Typer(
+    name="config",
+    help=(
+        "Inspect the cwms-tools configuration after the flag > env > default "
+        "precedence merge has been applied."
+    ),
+)
+
+
+def _redacted(name: str, value: str | None) -> str | None:
+    if value is None or name not in SECRET_VARS:
+        return value
+    return f"***{value[-4:]}" if len(value) > 8 else "***"
+
+
+@app.command("show")
+def show(
+    resolved: Annotated[
+        bool,
+        typer.Option(
+            "--resolved",
+            help=(
+                "Show the merged effective configuration after flags, "
+                "environment variables, and defaults are applied."
+            ),
+        ),
+    ] = False,
+) -> None:
+    """Print the resolved CLI configuration.
+
+    Precedence: explicit flags > CWMS_TOOLS_* environment variables >
+    built-in defaults. The `--resolved` flag is required so this
+    command can later grow a separate raw-config mode without changing
+    its contract.
+    """
+    if not resolved:
+        emit(
+            {
+                "error": "usage_error",
+                "message": "Run `cwms-tools config show --resolved`.",
+                "hint": "Pass --resolved to print the merged effective configuration.",
+            }
+        )
+        raise typer.Exit(code=2)
+
+    cfg = resolve_session_config()
+    payload = {
+        "api_root": cfg.api_root,
+        "cache_dir": str(resolve_cache_dir()),
+        "workers": MAX_WORKERS,
+        "user_agent": cfg.user_agent,
+        "operator_email": cfg.operator_email,
+        "env_inputs_read": list(READ_VARS),
+    }
+    # Redact any secret env vars surfaced inline (none today, but defensive).
+    for k in SECRET_VARS & set(payload.keys()):
+        raw = payload[k]
+        payload[k] = _redacted(k, raw if isinstance(raw, str) else None)
+    emit(payload)

cwms_tools/cli/commands/env.py

@@ -0,0 +1,62 @@
+"""`cwms-tools env` — print the CWMS_TOOLS_* env vars the CLI reads."""
+
+from __future__ import annotations
+
+import os
+
+import typer
+
+from cwms_tools.cli.render import emit
+
+app = typer.Typer(
+    name="env",
+    help=(
+        "List the CWMS_TOOLS_* environment variables the CLI reads, their "
+        "resolved values, and which are secret (redacted in output)."
+    ),
+)
+
+# Single source of truth for which env vars we read. Used both here and by the
+# `config show --resolved` command (M3) and (eventually) `cwms-tools schema`.
+READ_VARS: tuple[str, ...] = (
+    "CWMS_TOOLS_API_ROOT",
+    "CWMS_TOOLS_CACHE_DIR",
+    "CWMS_TOOLS_WORKERS",
+    "CWMS_TOOLS_REPO_URL",
+    "CWMS_TOOLS_USER_AGENT_EXTRA",
+    "CWMS_TOOLS_OPERATOR_EMAIL",
+    "CWMS_TOOLS_MAX_RPS",  # declared, not enforced in v0.1.0
+    "CWMS_API_KEY",  # declared, unused in v0.1.0
+    "CWMS_TOKEN",  # declared, unused in v0.1.0
+)
+
+# Vars whose values must be redacted in output (tail-only preserved).
+SECRET_VARS: frozenset[str] = frozenset({"CWMS_API_KEY", "CWMS_TOKEN"})
+
+
+def _redacted(name: str, value: str) -> str:
+    if name not in SECRET_VARS:
+        return value
+    if len(value) <= 8:
+        return "***"
+    return f"***{value[-4:]}"
+
+
+@app.callback(invoke_without_command=True)
+def env_cmd() -> None:
+    """Print each tracked env var, whether it is set, and its (redacted) value."""
+    rows: list[dict[str, str | None]] = []
+    for name in READ_VARS:
+        raw = os.environ.get(name)
+        rows.append(
+            {
+                "name": name,
+                "value": _redacted(name, raw) if raw is not None else None,
+                "set": str(raw is not None).lower(),
+                "secret": str(name in SECRET_VARS).lower(),
+            }
+        )
+    emit({"variables": rows})
+
+
+__all__ = ["READ_VARS", "SECRET_VARS"]

cwms_tools/cli/commands/fingerprint.py

@@ -0,0 +1,35 @@
+"""`cwms-tools fingerprint` — emit the capability fingerprint alone."""
+
+from __future__ import annotations
+
+import typer
+
+from cwms_tools.cli.render import emit
+from cwms_tools.core import fingerprint as fp
+from cwms_tools.mcp.resources import RESOURCE_INVENTORY, TOOL_INVENTORY
+
+app = typer.Typer(
+    name="fingerprint",
+    help=(
+        "Print the capability fingerprint — a SHA-256 over the tool list, "
+        "schemas, resource catalog, error codes, bundled overview, and "
+        "configured CDA root. Clients cache by this value to detect when "
+        "anything in the agent-visible surface has changed."
+    ),
+)
+
+
+@app.callback(invoke_without_command=True)
+def fingerprint_cmd() -> None:
+    """Compute and print the capability fingerprint."""
+    # We pass the tool inventory as a stable list of names (no per-tool schema
+    # introspection on the CLI side) — that matches what the MCP server sees
+    # because the tool surface in v0.1.0 is statically registered.
+    tools = {name: {"name": name} for name in TOOL_INVENTORY}
+    digest = fp.compute(tools=tools, resources=RESOURCE_INVENTORY)
+    emit(
+        {
+            "fingerprint": digest,
+            "scope": fp.FINGERPRINT_SCOPE,
+        }
+    )

cwms_tools/cli/commands/mcp.py

@@ -0,0 +1,129 @@
+"""`cwms-tools mcp serve` — launch the FastMCP server over stdio or streamable HTTP.
+
+stdio is the only transport where stdout is reserved for the JSON-RPC stream
+(agent-friendly-mcp §1). The subcommand suppresses every Typer / rich / log
+write to stdout and routes them to stderr, and installs a `sys.stdout` guard
+that errors loudly if anything outside FastMCP writes to stdout during the
+serve loop.
+
+streamable HTTP is the network-deployment transport; output rules don't
+apply because there's no shared stdout channel with the client.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Annotated, Any
+
+import typer
+
+from cwms_tools.cli.render import diagnostic
+from cwms_tools.mcp.server import build_server
+
+app = typer.Typer(
+    name="mcp",
+    help=(
+        "Run the cwms-tools MCP server. Exposes the same task tools as "
+        "the CLI to MCP-aware agent runtimes (Claude Code, Codex, etc.)."
+    ),
+    no_args_is_help=True,
+)
+
+
+class _StdoutGuard:
+    """Wraps `sys.stdout` and forbids non-FastMCP writes during stdio serve."""
+
+    def __init__(self, real: Any) -> None:
+        self._real = real
+        self._warned = False
+
+    def write(self, s: str) -> int:
+        if not s:
+            return 0
+        sys.stderr.write(s)
+        if not self._warned and s.strip():
+            sys.stderr.write(
+                "\n[cwms-tools mcp serve] non-FastMCP stdout write redirected to stderr\n"
+            )
+            self._warned = True
+        return len(s)
+
+    def flush(self) -> None:
+        sys.stderr.flush()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._real, name)
+
+
+@app.command("serve")
+def serve(
+    transport: Annotated[
+        str,
+        typer.Option(
+            "--transport",
+            help=(
+                "MCP transport. 'stdio' speaks JSON-RPC over stdin/stdout "
+                "and is the right choice for local agent runtimes. "
+                "'streamable-http' binds an HTTP listener for shared/remote use."
+            ),
+            case_sensitive=False,
+        ),
+    ] = "stdio",
+    host: Annotated[
+        str,
+        typer.Option(
+            "--host",
+            help="HTTP bind host. Only used when --transport is streamable-http.",
+        ),
+    ] = "127.0.0.1",
+    port: Annotated[
+        int,
+        typer.Option(
+            "--port",
+            help="HTTP bind port. Only used when --transport is streamable-http.",
+        ),
+    ] = 8765,
+) -> None:
+    """Launch the cwms-tools MCP server.
+
+    Local example:    cwms-tools mcp serve --transport stdio
+    Remote example:   cwms-tools mcp serve --transport streamable-http --port 8765
+    """
+    transport_norm = transport.lower().strip()
+    server: Any = build_server()
+
+    if transport_norm in {"stdio", "stdin/stdout"}:
+        _serve_stdio(server)
+    elif transport_norm in {"http", "streamable-http", "streamable_http"}:
+        _serve_http(server, host=host, port=port)
+    else:
+        diagnostic(f"unknown transport {transport!r}; use stdio or streamable-http.")
+        raise typer.Exit(code=2)
+
+
+def _serve_stdio(server: Any) -> None:
+    """Install the stdout guard, route Typer/rich/log to stderr, then run."""
+    os.environ.setdefault("NO_COLOR", "1")
+    os.environ.setdefault("CLICOLOR", "0")
+    os.environ.setdefault("TYPER_DEFAULT_FORCE_TERMINAL_WIDTH", "200")
+
+    logging.basicConfig(level=logging.WARNING, stream=sys.stderr, force=True)
+
+    sys.stdout = _StdoutGuard(sys.__stdout__)
+    try:
+        server.run(transport="stdio", show_banner=False)
+    finally:
+        sys.stdout = sys.__stdout__
+
+
+def _serve_http(server: Any, *, host: str, port: int) -> None:
+    """Run streamable-http transport."""
+    logging.basicConfig(level=logging.INFO, stream=sys.stderr, force=True)
+    server.run(
+        transport="streamable-http",
+        host=host,
+        port=port,
+        show_banner=False,
+    )

cwms_tools/cli/commands/place.py

@@ -0,0 +1,232 @@
+"""`cwms-tools place ...` — place/location commands.
+
+Subcommands:
+- `cwms-tools place search <query> --office <O>`
+- `cwms-tools place describe <office>/<name>`
+- `cwms-tools place parameters <office>/<name>`
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from cwms_tools.cli.exit_codes import from_error_code
+from cwms_tools.cli.render import emit
+from cwms_tools.core import places
+from cwms_tools.core.errors import CwmsToolsError, ErrorCode
+from cwms_tools.core.models import Detail
+
+app = typer.Typer(
+    name="place",
+    help=(
+        "Resolve and describe CWMS locations: name search, full place "
+        "description (location + project + publishers + freshness), and "
+        "per-location parameter listing."
+    ),
+    no_args_is_help=True,
+)
+
+
+def _parse_office_slash_name(spec: str) -> tuple[str, str]:
+    """Split `OFFICE/NAME` into (office, name); raises typer.Exit(2) on bad shape."""
+    if "/" not in spec:
+        emit(
+            {
+                "ok": False,
+                "error": {
+                    "code": ErrorCode.USAGE_ERROR.value,
+                    "message": "Expected `OFFICE/NAME` form, e.g. `NWDM/FTPK`.",
+                    "field": "spec",
+                    "offending_value": spec,
+                },
+            }
+        )
+        raise typer.Exit(code=2)
+    office, name = spec.split("/", 1)
+    return office.strip(), name.strip()
+
+
+@app.command("search")
+def search(
+    query: Annotated[
+        str,
+        typer.Argument(help="Name fragment to match, case-insensitive."),
+    ],
+    office: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--office",
+            "-o",
+            help=(
+                "USACE office code. Repeat to fan out across multiple "
+                "offices (e.g. `-o NWDP -o NWDM`). Omit to use offices "
+                "already cached this session; unbounded discovery is "
+                "intentionally avoided. Overflow beyond the per-call "
+                "budget lands in `offices_skipped_for_budget`."
+            ),
+        ),
+    ] = None,
+    parameter: Annotated[
+        str | None,
+        typer.Option(
+            "--parameter",
+            "-p",
+            help=(
+                "Filter to locations publishing this parameter "
+                "(e.g. Temp-Water, Elev, Flow-In). When set, non-publishing "
+                "rows are dropped — except barren parents whose `data_at` "
+                "siblings publish it. `nearby_non_matching_count` reflects "
+                "what was filtered out."
+            ),
+        ),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option(
+            "--limit",
+            "-n",
+            help=(
+                "Cap on the number of results (default 50). Broad searches "
+                "like 'Temp String' on a big office can match hundreds of "
+                "rows; the cap keeps responses small. Pass `0` to return "
+                "every match (no cap). When the cap kicks in the response "
+                "carries `truncated: true` and `total_count`."
+            ),
+        ),
+    ] = places.DEFAULT_SEARCH_LIMIT,
+    detail: Annotated[
+        Detail,
+        typer.Option(
+            "--detail",
+            help="Response density. 'summary' drops verbose upstream fields; 'full' keeps them.",
+        ),
+    ] = Detail.SUMMARY,
+) -> None:
+    """Search for places by name in one office.
+
+    Each result is enriched with parameter_count (0 = ghost record),
+    active publishers, last data timestamp, co-located variants, and
+    `data_at` — when a barren parent has a co-located sibling that
+    publishes data (e.g. the Lake Washington `UBLW_S1` parent has no
+    ts ids but `UBLW_S1-D21,0ft` does), `data_at` names that sibling
+    so the agent doesn't have to walk the co_located list to find it.
+    Data-bearing records sort first.
+    """
+    if limit < 0:
+        emit(
+            {
+                "ok": False,
+                "error": {
+                    "code": ErrorCode.USAGE_ERROR.value,
+                    "message": "--limit must be a non-negative integer.",
+                    "field": "limit",
+                    "offending_value": limit,
+                },
+            }
+        )
+        raise typer.Exit(code=2)
+    effective_limit = None if limit == 0 else limit
+    # Typer passes repeatable Options as a list[str] (even when one value
+    # was given). Collapse to a single string when only one office is
+    # present, so the response's `office` field echoes the simpler shape.
+    office_arg: str | list[str] | None
+    if not office:
+        office_arg = None
+    elif len(office) == 1:
+        office_arg = office[0]
+    else:
+        office_arg = list(office)
+    try:
+        payload = places.search_places(
+            query,
+            office=office_arg,
+            parameter=parameter,
+            limit=effective_limit,
+        )
+    except CwmsToolsError as err:
+        emit({"ok": False, "error": err.envelope.model_dump(mode="json")})
+        raise typer.Exit(code=from_error_code(err.envelope.code)) from err
+    if detail is Detail.SUMMARY:
+        payload = {
+            **payload,
+            "results": [{k: v for k, v in r.items() if k != "raw"} for r in payload["results"]],
+        }
+    emit(payload)
+
+
+@app.command("describe")
+def describe(
+    spec: Annotated[
+        str,
+        typer.Argument(help="Place id in OFFICE/NAME form, e.g. NWDM/FTPK or SWT/FOSS."),
+    ],
+    detail: Annotated[
+        Detail,
+        typer.Option(
+            "--detail",
+            help=(
+                "'summary' returns the triage subset of the location DTO; "
+                "'full' returns every field."
+            ),
+        ),
+    ] = Detail.SUMMARY,
+) -> None:
+    """Print everything about one place in a single call.
+
+    Combines the location record, project metadata (when present), the
+    parameters published at the location grouped by publisher, and the
+    most recent data timestamp. Sets `partial: true` when any
+    underlying lookup degrades.
+    """
+    office, name = _parse_office_slash_name(spec)
+    try:
+        payload = places.describe_place(office, name)
+    except CwmsToolsError as err:
+        emit({"ok": False, "error": err.envelope.model_dump(mode="json")})
+        raise typer.Exit(code=from_error_code(err.envelope.code)) from err
+    if detail is Detail.SUMMARY and isinstance(payload.get("location"), dict):
+        loc = payload["location"]
+        payload = {
+            **payload,
+            "location": {
+                k: loc.get(k)
+                for k in (
+                    "office-id",
+                    "name",
+                    "location-kind",
+                    "latitude",
+                    "longitude",
+                    "public-name",
+                    "long-name",
+                    "horizontal-datum",
+                    "state-initial",
+                    "nearest-city",
+                    "timezone-name",
+                )
+                if k in loc
+            },
+        }
+    emit(payload)
+
+
+@app.command("parameters")
+def parameters(
+    spec: Annotated[
+        str,
+        typer.Argument(help="Place id in OFFICE/NAME form, e.g. SWT/FOSS."),
+    ],
+) -> None:
+    """List the parameters published at a place, grouped by publisher.
+
+    The cheapest probe for distinguishing data-bearing locations from
+    ghost catalog records: a ghost returns ts_count=0 and an empty
+    by_publisher list.
+    """
+    office, name = _parse_office_slash_name(spec)
+    try:
+        emit(places.list_parameters(office, name))
+    except CwmsToolsError as err:
+        emit({"ok": False, "error": err.envelope.model_dump(mode="json")})
+        raise typer.Exit(code=from_error_code(err.envelope.code)) from err