sourcelock 0.1.0__py3-none-any.whl

hc_source/cli.py

@@ -0,0 +1,959 @@
+"""``hc-source`` command line.
+
+Exit codes are part of the contract:
+
+* ``doctor``: 0 in sync with the lockfile, 1 drift or schema change,
+  2 unreachable source, adapter load failure, or an unpinned canary.
+* ``call``: 0 on success, 1 on a usage or validation error, 2 when the upstream
+  source could not be read. 1 and 2 are kept apart deliberately -- a caller has
+  to be able to tell "your input was wrong" from "CMS is down", and retrying is
+  the right response to only one of them.
+* every other command: 0 on success, 1 on a usage, I/O, or validation error.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from pydantic import ValidationError
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__, cache
+from .adapters import AdapterError, discover, discovery_errors, find_tool, iter_tools
+from .doctor import EXIT_DRIFT, EXIT_OK, EXIT_UNREACHABLE, run_doctor
+from .guard import (
+    ParamsRejected,
+    PHIRejected,
+    assert_public_params,
+    safe_label,
+    safe_tool_name,
+    safe_validation_message,
+)
+from .http import SourceUnreachable
+from .lockfile import (
+    DEFAULT_LOCK_FILENAME,
+    build_lockfile,
+    default_lock_path,
+    load_lockfile,
+    save_lockfile,
+)
+from .schemas import CanarySeverity, CanaryStatus, Lockfile, Receipt
+
+app = typer.Typer(
+    name="hc-source",
+    help="Source assurance for public healthcare data. Receipts on every answer.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+lock_app = typer.Typer(help="Manage source-lock.json.", no_args_is_help=True)
+app.add_typer(lock_app, name="lock")
+
+# Additive registration: the manifest commands live in cli_manifest.py.
+from .cli_manifest import manifest_app  # noqa: E402
+
+app.add_typer(manifest_app, name="manifest")
+
+console = Console(stderr=False)
+err = Console(stderr=True)
+
+_STATUS_STYLE = {
+    CanaryStatus.OK: "green",
+    CanaryStatus.DRIFT: "yellow",
+    CanaryStatus.SCHEMA_CHANGED: "yellow",
+    CanaryStatus.UNREACHABLE: "red",
+    CanaryStatus.UNPINNED: "yellow",
+    CanaryStatus.STALE: "yellow",
+    CanaryStatus.ERROR: "red",
+}
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"hc-source {__version__}")
+        raise typer.Exit(EXIT_OK)
+
+
+@app.callback()
+def main_callback(
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True, help="Show version and exit."
+    ),
+) -> None:
+    """Source assurance for public healthcare data."""
+
+
+def _fail(message: str, code: int = 1) -> None:
+    typer.echo(message)
+    raise typer.Exit(code)
+
+
+def _os_error_reason(exc: OSError) -> str:
+    """A short human reason for an OSError, with no traceback and no payload."""
+    return (exc.strerror or type(exc).__name__).lower()
+
+
+def _load_lock_or_none(path: Path) -> tuple[Any, str | None]:
+    try:
+        return load_lockfile(path), None
+    except FileNotFoundError as exc:
+        return None, str(exc)
+    except OSError as exc:
+        # Unreadable (permissions, a directory, a broken symlink). Not "no
+        # lockfile": pretending nothing is pinned would report a green run that
+        # verified nothing, the same failure `_scoped_discovery` refuses.
+        _fail(f"cannot read {path}: {_os_error_reason(exc)}")
+        raise AssertionError  # pragma: no cover - _fail always exits
+    except ValidationError as exc:
+        _fail(f"source-lock.json at {path} is not valid: {exc.error_count()} problem(s). "
+              "Regenerate it with `hc-source lock init`.")
+        raise AssertionError  # pragma: no cover - _fail always exits
+
+
+def _scoped_discovery(source: list[str]):
+    """Discover adapters, optionally scoped to specific source ids.
+
+    Returns ``(adapters, load_errors)``. An unknown ``--source`` is a usage
+    error: silently checking nothing would report a green run that verified
+    nothing. Load errors are matched to a scope by module basename, since a
+    module that failed to load has no source_id to ask.
+    """
+    found = discover()
+    adapters, load_errors = found.adapters, found.errors
+    if not source:
+        return adapters, load_errors
+
+    wanted = set(source)
+    known = {a.source_id for a in adapters} | {
+        e.module.rsplit(".", 1)[-1] for e in load_errors
+    }
+    unknown = sorted(wanted - known)
+    if unknown:
+        available = ", ".join(sorted(a.source_id for a in adapters)) or "none"
+        _fail(
+            f"unknown source(s): {', '.join(unknown)}. Discovered sources: {available}."
+        )
+    return (
+        [a for a in adapters if a.source_id in wanted],
+        [e for e in load_errors if e.module.rsplit(".", 1)[-1] in wanted],
+    )
+
+
+# ---------------------------------------------------------------------------
+# doctor
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def doctor(
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+    lock: Optional[Path] = typer.Option(
+        None, "--lock", help="Path to source-lock.json (default: ./source-lock.json)."
+    ),
+    source: list[str] = typer.Option(
+        [],
+        "--source",
+        "-s",
+        help="Check only these source ids (repeatable). Default: every discovered source.",
+    ),
+) -> None:
+    """Run every adapter's canaries and compare them to the lockfile."""
+    lock_path = lock or default_lock_path()
+    lockfile, missing = _load_lock_or_none(lock_path)
+    adapters, load_errors = _scoped_discovery(source)
+    report = run_doctor(lockfile, adapters, load_errors=load_errors)
+
+    if json_output:
+        payload = report.to_dict()
+        payload["lock_path"] = str(lock_path)
+        if missing:
+            payload["lockfile_error"] = missing
+        typer.echo(json.dumps(payload, indent=2))
+        raise typer.Exit(report.exit_code)
+
+    if missing:
+        typer.echo(f"! {missing}")
+
+    for error in report.load_errors:
+        typer.echo(f"! adapter failed to load -- {error}")
+
+    # canary and status must always be readable; observed/expected absorb the
+    # truncation when the terminal is narrow (all-no_wrap columns make rich
+    # collapse the narrowest column to zero width instead). Full values are
+    # always available via --json.
+    table = Table(title=f"hc-source doctor  ({lock_path.name})", title_justify="left")
+    table.add_column("canary", no_wrap=True)
+    table.add_column("status", no_wrap=True)
+    # Which source actually answered. An `ok` from a mirror while the authority
+    # is dark is a different claim from an `ok` from the authority (finding H2).
+    table.add_column("via", overflow="ellipsis", max_width=22)
+    table.add_column("observed", overflow="ellipsis", max_width=38)
+    table.add_column("expected", overflow="ellipsis", max_width=38)
+
+    for result in report.results:
+        advisory = result.severity is CanarySeverity.ADVISORY
+        # An advisory finding is still a finding: it keeps its status word and
+        # is marked as not counting, rather than being quietly recoloured green.
+        status_text = result.status.value + (" (advisory)" if advisory else "")
+        style = "dim" if advisory and result.status is not CanaryStatus.OK else (
+            _STATUS_STYLE[result.status]
+        )
+        table.add_row(
+            result.canary_id,
+            f"[{style}]{status_text}[/]",
+            f"[yellow]{result.fallback_name or 'mirror'}[/]" if result.fallback_used
+            else "authority",
+            result.observed or "-",
+            result.expected or "-",
+        )
+    console.print(table)
+
+    summary = report.summary
+    extras = []
+    if summary["fallback"]:
+        extras.append(f"{summary['fallback']} answered by a mirror")
+    if summary["advisory"]:
+        extras.append(f"{summary['advisory']} advisory, not counted")
+    if summary["retried"]:
+        extras.append(f"{summary['retried']} needed a retry")
+    typer.echo(
+        ", ".join(f"{summary[s.value]} {s.value}" for s in CanaryStatus)
+        + (f" ({'; '.join(extras)})" if extras else "")
+    )
+
+    # Printed unwrapped: remediation text is meant to be copied and run.
+    for result in report.results:
+        if result.status is not CanaryStatus.OK:
+            mark = (
+                " advisory -- reported, not counted toward the exit code"
+                if result.severity is CanarySeverity.ADVISORY
+                else ""
+            )
+            typer.echo(
+                f"\n{result.canary_id} [{result.status.value}{mark}]: {result.remediation}"
+            )
+        for warning in result.warnings:
+            typer.echo(f"  note {result.canary_id}: {warning}")
+
+    raise typer.Exit(report.exit_code)
+
+
+# ---------------------------------------------------------------------------
+# lock
+# ---------------------------------------------------------------------------
+
+
+@lock_app.command("init")
+def lock_init(
+    lock: Optional[Path] = typer.Option(
+        None, "--lock", help="Where to write the lockfile (default: ./source-lock.json)."
+    ),
+    source: list[str] = typer.Option(
+        [],
+        "--source",
+        "-s",
+        help=(
+            "Pin only these source ids (repeatable); other sources' existing pins are "
+            "kept untouched. Default: every discovered source."
+        ),
+    ),
+    allow_partial: bool = typer.Option(
+        False,
+        "--allow-partial",
+        help=(
+            "Write the lockfile even though some canaries could not be observed. "
+            "Previous pins for those canaries are kept; canaries that have never "
+            "been pinned stay unpinned, and doctor will report them as such."
+        ),
+    ),
+) -> None:
+    """Observe every source now and pin what it says to source-lock.json.
+
+    Refuses to write unless every selected canary was observed. A `lock init`
+    that runs offline used to pin what it could reach and drop the rest, which
+    quietly deleted exactly the pins that detect drift. Pass `--allow-partial`
+    to accept a partial run; previous pins are preserved either way.
+    """
+    lock_path = lock or default_lock_path()
+    adapters, load_errors = _scoped_discovery(source)
+
+    for error in load_errors:
+        typer.echo(f"! adapter failed to load -- {error}")
+
+    existing, _ = _load_lock_or_none(lock_path)
+    build = build_lockfile(adapters, previous=existing)
+    lockfile = build.lockfile
+
+    if existing is not None:
+        # Never drop a source this run did not actually re-observe. A source
+        # whose adapter module failed to LOAD has no canaries to run, so it is
+        # absent from `build.lockfile` -- and dropping it here is how a scoped
+        # `lock init --source leie` with a broken leie.py wiped leie's pins.
+        rebuilt = set(lockfile.sources)
+        merged = {
+            sid: entry for sid, entry in existing.sources.items() if sid not in rebuilt
+        }
+        merged.update(lockfile.sources)
+        merged = dict(sorted(merged.items()))
+        generated_at = (
+            existing.generated_at if merged == existing.sources else lockfile.generated_at
+        )
+        lockfile = Lockfile(generated_at=generated_at, sources=merged)
+
+    blocked = bool(build.failures or load_errors) and not allow_partial
+    if blocked:
+        for failure in build.failures:
+            typer.echo(f"! {failure}")
+        typer.echo(
+            f"refusing to write {lock_path}: "
+            + _incomplete_summary(build.failures, load_errors)
+            + ". Nothing was changed -- the existing pins are intact. Fix the source (or "
+            "the adapter) and run again, or accept a partial pin with "
+            "`hc-source lock init --allow-partial`."
+        )
+        raise typer.Exit(EXIT_UNREACHABLE)
+
+    try:
+        save_lockfile(lockfile, lock_path)
+    except OSError as exc:
+        # Read-only checkout, a directory in the way, a full disk. All of these
+        # used to surface as a raw PermissionError traceback.
+        _fail(f"cannot write {lock_path}: {_os_error_reason(exc)}")
+        raise AssertionError  # pragma: no cover
+
+    pinned = sum(len(e.expected_canaries) for e in lockfile.sources.values())
+    typer.echo(
+        f"wrote {lock_path} -- {len(lockfile.sources)} source(s), {pinned} canary expectation(s)"
+    )
+
+    if build.failures or load_errors:
+        typer.echo(
+            f"! PARTIAL PIN: {_incomplete_summary(build.failures, load_errors)}. "
+            "This lockfile is not a complete observation of upstream."
+        )
+        for failure in build.failures:
+            typer.echo(f"!   {failure}")
+        if build.preserved:
+            typer.echo(
+                f"!   {len(build.preserved)} previous pin(s) were kept unchanged and "
+                "describe an EARLIER observation, not this run."
+            )
+        if build.unpinned:
+            typer.echo(
+                f"!   {len(build.unpinned)} canary/canaries remain unpinned; "
+                "`hc-source doctor` will report them as unpinned (exit 3)."
+            )
+
+    raise typer.Exit(
+        EXIT_UNREACHABLE if (build.failures or load_errors) else EXIT_OK
+    )
+
+
+def _incomplete_summary(failures, load_errors) -> str:
+    parts = []
+    if failures:
+        parts.append(f"{len(failures)} canary/canaries could not be observed")
+    if load_errors:
+        parts.append(f"{len(load_errors)} adapter(s) failed to load")
+    return " and ".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# tools
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def tools(
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """List every tool from every discovered adapter.
+
+    Exits 2 when any adapter module failed to load. An adapter that is broken
+    looks exactly like an adapter that is absent from a list of what works, and
+    a source someone is paying for must not disappear quietly.
+    """
+    found = discover()
+    specs = iter_tools(found.adapters)
+    load_errors = found.errors
+
+    if json_output:
+        typer.echo(
+            json.dumps(
+                {
+                    "load_errors": [e.as_dict() for e in load_errors],
+                    # Where each source came from: built in, an installed
+                    # distribution, or a local file. A proprietary adapter is
+                    # not a second-class citizen, but it is a DIFFERENT claim,
+                    # and the person reading a receipt gets to see which.
+                    "adapters": [
+                        {"source_id": a.source_id, "origin": found.origin(a.source_id)}
+                        for a in found.adapters
+                    ],
+                    "tools": [
+                        {
+                            "name": s.name,
+                            "source_id": s.source_id,
+                            "description": s.description,
+                            "tags": list(s.tags),
+                            "params_schema": s.params_schema(),
+                        }
+                        for s in specs
+                    ]
+                },
+                indent=2,
+            )
+        )
+        raise typer.Exit(EXIT_UNREACHABLE if load_errors else EXIT_OK)
+
+    # tool names stay whole; parameters wrap; description gets the room
+    # (a no_wrap parameters column can starve description to nothing).
+    table = Table(title="hc-source tools", title_justify="left")
+    table.add_column("tool", no_wrap=True)
+    table.add_column("parameters", max_width=24)
+    table.add_column("description", ratio=1)
+    for spec in specs:
+        params = ", ".join(spec.params_model.model_fields) or "-"
+        table.add_row(spec.name, params, spec.description)
+    console.print(table)
+
+    third_party = found.third_party()
+    if third_party:
+        typer.echo(
+            f"{len(third_party)} source(s) came from outside this package: "
+            + ", ".join(f"{a.source_id} ({found.origin(a.source_id)})" for a in third_party)
+        )
+
+    for error in load_errors:
+        typer.echo(f"! adapter failed to load -- {error}")
+    if load_errors:
+        typer.echo(
+            f"! {len(load_errors)} adapter(s) are missing from this list because they "
+            "failed to import, not because they do not exist. Every route they provide "
+            "is unavailable."
+        )
+        raise typer.Exit(EXIT_UNREACHABLE)
+
+
+# ---------------------------------------------------------------------------
+# call
+# ---------------------------------------------------------------------------
+
+
+def _parse_params(pairs: list[str], tool: str) -> dict[str, str]:
+    """Turn ``k=v`` strings into a mapping, guarding the RAW text first.
+
+    Three round-1 holes lived in the four lines this replaced:
+
+    * a syntax error printed the offending pair verbatim, so ``--param
+      123-45-6789`` was refused by echoing it;
+    * ``params[key] = value`` was last-wins, so ``-p code=<something dirty>
+      -p code=E11.9`` dropped the first value BEFORE the guard ever saw it --
+      a clean second value hid a dirty first;
+    * the key itself was never scanned as text.
+
+    So the raw pairs are scanned before anything is parsed, duplicates are a
+    refusal rather than an overwrite, and nothing caller-supplied is echoed
+    unless it is identifier-shaped.
+    """
+    # Scan the raw text of every occurrence. The keys here are ours, so the
+    # guard's own paths stay readable; the values are the whole `k=v` strings.
+    try:
+        assert_public_params(
+            {f"param_{i + 1}": pair for i, pair in enumerate(pairs)}, tool=tool
+        )
+    except PHIRejected as exc:
+        # Carries detector codes and positions only, never the text.
+        _fail(str(exc))
+        raise AssertionError  # pragma: no cover
+
+    params: dict[str, str] = {}
+    for i, pair in enumerate(pairs, start=1):
+        key, sep, value = pair.partition("=")
+        if not sep or not key:
+            _fail(
+                f"bad --param #{i}: expected k=v. The pair is not repeated here on "
+                "purpose -- SourceLock does not echo parameter text back at you."
+            )
+        if key in params:
+            _fail(
+                f"--param {safe_label(key)} was given more than once. SourceLock refuses "
+                "rather than taking the last one: a repeated key means one of the values "
+                "was going to be discarded, and discarding a value before it is inspected "
+                "is how a clean second value hides a dirty first."
+            )
+        params[key] = value
+    return params
+
+
+@app.command()
+def call(
+    tool: str = typer.Argument(..., help="Tool name, e.g. demo.lookup_code."),
+    param: list[str] = typer.Option(
+        [], "--param", "-p", help="Typed public parameter as k=v. Repeatable."
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Call one tool and print its result with the evidence receipt."""
+    # Resolved before the parameters are parsed so that a misspelled tool name
+    # is reported as a misspelled tool name, not as a complaint about the flags
+    # that were going to be passed to it.
+    spec = _resolve_tool(tool)
+    _run_tool(tool, _parse_params(param, tool), json_output, spec=spec)
+
+
+def _resolve_tool(tool: str) -> Any:
+    """Find one tool, or exit with the right code and a fix.
+
+    ``call`` had this and the shortcuts did not, so a broken adapter answered
+    ``valid-on``, ``lookup-npi``, ``check-npi`` and ``hcc score`` with a Python
+    traceback and exit 1. A traceback is not remediation, and exit 1 says "your
+    command was wrong" about something that was not.
+    """
+    try:
+        return find_tool(tool)
+    except AdapterError as exc:
+        # The route exists and is broken. Exit 2, not 1: nothing about the
+        # caller's command was wrong.
+        _fail(str(exc), EXIT_UNREACHABLE)
+        raise AssertionError  # pragma: no cover
+    except KeyError:
+        # safe_tool_name, not `tool!r`: the name is caller-supplied text, and
+        # "no tool named X" reflecting X back is a free write into anyone's log.
+        _fail(
+            f"no tool named {safe_tool_name(tool)}. Run `hc-source tools` to see what "
+            "is available."
+        )
+        raise AssertionError  # pragma: no cover
+
+
+def _run_tool(
+    tool: str, params: dict[str, Any], json_output: bool, *, spec: Any = None
+) -> None:
+    """Resolve, invoke and print one tool call. The single error-mapping path.
+
+    Every command that reaches an adapter goes through here -- ``call`` and all
+    four shortcuts -- so the exit codes, the remediation text and the
+    no-echo rules are the same wherever you arrive from. Two copies of this
+    drifted once already: the shortcuts' copy was missing the adapter-load
+    cases entirely.
+    """
+    spec = spec if spec is not None else _resolve_tool(tool)
+    try:
+        result = spec.invoke(params)
+    except (PHIRejected, ParamsRejected) as exc:
+        # Both carry field names and rule text only, never a parameter value.
+        _fail(str(exc))
+        raise AssertionError  # pragma: no cover
+    except ValidationError as exc:
+        # Defence in depth: invoke() converts these, so reaching here means an
+        # adapter validated something itself. Never print the raw exception.
+        _fail(f"{tool}: invalid parameters -- {safe_validation_message(exc)}")
+        raise AssertionError  # pragma: no cover
+    except SourceUnreachable as exc:
+        # exc carries a URL and a transport reason, never a response body and
+        # never a parameter value. Exit 2, not 1: this is not the caller's fault.
+        _fail(
+            f"{tool}: source unreachable -- {exc.url} ({exc.reason}"
+            + (f", HTTP {exc.status}" if exc.status else "")
+            + ").\n"
+            "The answer would have had no evidence behind it, so no answer was given. "
+            "Check connectivity and any proxy settings, then run `hc-source doctor "
+            f"--source {tool.split('.', 1)[0]}` to see whether the source is reachable "
+            "at all.",
+            EXIT_UNREACHABLE,
+        )
+        raise AssertionError  # pragma: no cover
+    except AdapterError as exc:
+        # An adapter that returned something invalid -- a receipt naming another
+        # source, a handler returning the wrong type. Our bug, not the caller's.
+        _fail(str(exc), EXIT_UNREACHABLE)
+        raise AssertionError  # pragma: no cover
+
+    if json_output:
+        typer.echo(
+            json.dumps(
+                {"data": result.data, "receipt": result.receipt.model_dump(mode="json")},
+                indent=2,
+            )
+        )
+        raise typer.Exit(EXIT_OK)
+
+    typer.echo(json.dumps(result.data, indent=2))
+    _print_receipt(result.receipt)
+
+
+def _print_receipt(receipt: Receipt) -> None:
+    # The field names must stay whole and the values must stay VISIBLE. When
+    # every column is no_wrap, rich collapses the narrowest one to zero width
+    # instead of eliding it -- which rendered every receipt value, including the
+    # fallback flag, as an empty box at narrow widths (finding H5; the same bug
+    # commit be56f3d fixed for the doctor table). Giving the field column a
+    # ceiling and letting the value column fold keeps the evidence on screen.
+    table = Table(title="receipt", title_justify="left", show_header=False)
+    table.add_column("field", overflow="ellipsis", max_width=17)
+    table.add_column("value", overflow="fold", ratio=1)
+    table.add_row("source", receipt.source_id)
+    table.add_row("route", receipt.route)
+    table.add_row("source_version", receipt.source_version)
+    table.add_row("effective", f"{receipt.effective_from or '-'} .. {receipt.effective_to or 'open'}")
+    table.add_row("retrieved_at", receipt.retrieved_at.isoformat())
+    table.add_row("upstream_status", str(receipt.upstream_status))
+    table.add_row("raw_sha256", receipt.raw_sha256)
+    table.add_row("transform_version", receipt.transform_version)
+    table.add_row(
+        "fallback", receipt.fallback_name if receipt.fallback_used else "no (authority used)"
+    )
+    console.print(table)
+
+    for warning in receipt.warnings:
+        typer.echo(f"warning: {warning}")
+    typer.echo("does not prove:")
+    for claim in receipt.non_claims:
+        typer.echo(f"  - {claim}")
+
+
+# ---------------------------------------------------------------------------
+# shortcuts
+# ---------------------------------------------------------------------------
+#
+# `call` is the honest general form: any tool, any parameter, one syntax that
+# does not change when an adapter does. It is also the reason a newcomer's first
+# command is
+#
+#     hc-source call codes.valid_on --param code=E11.9 --param date=2026-07-15
+#
+# which asks them to know a route name and a parameter grammar before they have
+# seen the product do anything. These four wrap the questions people actually
+# arrive with. They are thin on purpose: same tool, same guard, same receipt,
+# same exit codes -- `call` remains the power-user path and the only one that
+# reaches a third-party adapter's routes.
+
+
+def _shortcut(tool: str, params: dict[str, Any], json_output: bool) -> None:
+    """Run a tool exactly as `call` would, and print it exactly as `call` does.
+
+    Literally the same function -- "exactly as `call` would" used to be a
+    promise kept by a second copy of the error handling, and the copy was
+    missing the two adapter-load cases.
+    """
+    _run_tool(tool, params, json_output)
+
+
+@app.command("valid-on")
+def valid_on(
+    code: str = typer.Argument(..., help="ICD-10-CM code, e.g. E11.9."),
+    date: str = typer.Argument(..., help="Date of service, YYYY-MM-DD."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Was this ICD-10-CM code valid on this date of service? (offline)
+
+    Answered from the vendored release tables, so it works with no network and
+    no credentials. Shorthand for `call codes.valid_on`.
+    """
+    _shortcut("codes.valid_on", {"code": code, "date": date}, json_output)
+
+
+@app.command("lookup-npi")
+def lookup_npi(
+    npi: str = typer.Argument(..., help="10-digit NPI."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Look one NPI up in the NPPES registry. Shorthand for `call provider.lookup_npi`."""
+    _shortcut("provider.lookup_npi", {"npi": npi}, json_output)
+
+
+@app.command("check-npi")
+def check_npi(
+    npi: str = typer.Argument(..., help="10-digit NPI."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Screen one NPI against the OIG LEIE exclusion list.
+
+    A miss never clears a provider -- about 89.5% of LEIE records carry no NPI.
+    The receipt says so. Shorthand for `call leie.check_npi`.
+    """
+    _shortcut("leie.check_npi", {"npi": npi}, json_output)
+
+
+hcc_app = typer.Typer(help="CMS-HCC risk model shortcuts.", no_args_is_help=True)
+app.add_typer(hcc_app, name="hcc")
+
+
+@hcc_app.command("score")
+def hcc_score(
+    dx: str = typer.Option(..., "--dx", help="Comma-separated ICD-10-CM codes."),
+    model: str = typer.Option(..., "--model", help="v24 or v28."),
+    year: int = typer.Option(..., "--year", help="Payment year, e.g. 2026."),
+    age: Optional[int] = typer.Option(None, "--age", help="Beneficiary age."),
+    sex: Optional[str] = typer.Option(None, "--sex", help="F or M."),
+    dual: str = typer.Option("non", "--dual", help="non, full, or partial."),
+    orig_disabled: bool = typer.Option(
+        False, "--orig-disabled", help="Originally disabled entitlement."
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Community continuing-enrollee RAF score. Shorthand for `call hcc.score`."""
+    params: dict[str, Any] = {
+        "diagnoses": dx,
+        "model": model,
+        "payment_year": year,
+        "dual": dual,
+        "orig_disabled": orig_disabled,
+    }
+    if age is not None:
+        params["age"] = age
+    if sex is not None:
+        params["sex"] = sex
+    _shortcut("hcc.score", params, json_output)
+
+
+# ---------------------------------------------------------------------------
+# init
+# ---------------------------------------------------------------------------
+
+#: The `actions/checkout` pin the scaffold writes, and the tag it names.
+#:
+#: A mutable `@v4` follows wherever that tag is republished, including to a
+#: compromised republish -- which is the hole this repository's own workflows
+#: closed, and which the scaffold went on writing into other people's
+#: repositories afterwards. A product about pinning the things your build
+#: depends on does not hand its users an unpinned dependency on the way in.
+#:
+#: `.github/` is not in the wheel, so this cannot be read off our workflows at
+#: runtime; `tests/test_release_workflow.py` asserts the two agree, so the pair
+#: moves together or the suite goes red.
+CHECKOUT_ACTION_PIN = "actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683"
+CHECKOUT_ACTION_VERSION = "v4.2.2"
+
+_CI_WORKFLOW = """\
+# Written by `hc-source init --ci`.
+#
+# What this does: pins the public data sources your build depends on, and fails
+# the build when one of them moves underneath you. `source-lock.json` is the pin;
+# commit it and review its diffs like any other lockfile.
+name: source-doctor
+
+on:
+  pull_request:
+  push:
+    branches: [{branch}]
+  schedule:
+    # Drift happens on CMS's clock, not yours.
+    - cron: "17 6 * * *"
+
+# This job reads public data sources and reports. It writes nothing, so it is
+# given nothing to write with. GitHub's default token is read-write on most
+# repositories; a workflow that runs on `pull_request` and does not narrow it
+# is handing that token to whatever the pull request contains.
+permissions:
+  contents: read
+
+jobs:
+  doctor:
+    runs-on: ubuntu-latest
+    steps:
+      # Pinned to a commit, with the tag in the comment. A `@v4` follows
+      # wherever that tag points next -- including a compromised republish of
+      # it -- and this job runs before anything else in the workflow. Update
+      # the SHA and the comment together.
+      - uses: {checkout} # {checkout_version}
+      - uses: {action}
+        with:
+          lock-path: {lock_path}
+          # Warn rather than fail when a source is unreachable or a snapshot is
+          # stale on a scheduled run, and fail on a pull request. A nightly job
+          # exists to tell you CMS was down; a PR that could not read its inputs
+          # has verified nothing. "auto" is that rule.
+          on-unreachable: auto
+          on-stale: auto
+"""
+
+
+@app.command()
+def init(
+    ci: bool = typer.Option(False, "--ci", help="Write a GitHub Actions workflow."),
+    path: Optional[Path] = typer.Option(
+        None, "--path", help="Where to write it (default: .github/workflows/source-doctor.yml)."
+    ),
+    action: str = typer.Option(
+        "OWNER/sourcelock/action@REF",
+        "--action",
+        help="The action reference to use. Pin REF to a commit SHA: a tag can be moved after you read it.",
+    ),
+    branch: str = typer.Option("main", "--branch", help="Default branch to run on push."),
+    lock: Optional[Path] = typer.Option(
+        None, "--lock", help="Lockfile path to reference (default: source-lock.json)."
+    ),
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing file."),
+) -> None:
+    """Scaffold SourceLock into a repository.
+
+    Today this writes the CI workflow. It never overwrites without `--force`:
+    the file it would replace is the one deciding whether your build fails.
+    """
+    if not ci:
+        _fail("nothing to do: pass --ci to write the GitHub Actions workflow.")
+
+    target = path or Path(".github/workflows/source-doctor.yml")
+    if target.exists() and not force:
+        _fail(
+            f"{target} already exists. Pass --force to overwrite it, or --path to write "
+            "somewhere else -- this file decides whether your build fails, so it is not "
+            "replaced silently."
+        )
+
+    content = _CI_WORKFLOW.format(
+        branch=branch,
+        action=action,
+        lock_path=(lock or Path(DEFAULT_LOCK_FILENAME)).as_posix(),
+        checkout=CHECKOUT_ACTION_PIN,
+        checkout_version=CHECKOUT_ACTION_VERSION,
+    )
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        _fail(f"cannot write {target}: {_os_error_reason(exc)}")
+        raise AssertionError  # pragma: no cover
+
+    typer.echo(f"wrote {target}")
+    if "OWNER/sourcelock" in action:
+        typer.echo(
+            "! edit the `uses:` line: OWNER/sourcelock/action@REF is a placeholder. "
+            "Pin REF to a commit SHA: a tag can be moved after you read it."
+        )
+    typer.echo("next: `hc-source lock init`, then commit source-lock.json with the workflow.")
+
+
+# ---------------------------------------------------------------------------
+# receipt
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def receipt(
+    verify: Path = typer.Option(..., "--verify", help="Path to a receipt JSON file."),
+) -> None:
+    """Validate a receipt file against the Receipt schema.
+
+    Schema validation only. Signature verification is not implemented yet:
+    a valid receipt here proves shape, not authorship.
+    """
+    try:
+        raw = Path(verify).read_text(encoding="utf-8")
+    except OSError as exc:
+        _fail(f"cannot read {verify}: {type(exc).__name__}")
+        raise AssertionError  # pragma: no cover
+
+    try:
+        parsed = Receipt.model_validate_json(raw)
+    except ValidationError as exc:
+        problems = "; ".join(
+            f"{'.'.join(str(p) for p in e['loc']) or '<receipt>'}: {e['msg']}" for e in exc.errors()
+        )
+        _fail(f"receipt is not valid -- {problems}")
+        raise AssertionError  # pragma: no cover
+
+    typer.echo(f"receipt is valid against the Receipt schema (v{__version__}).")
+    typer.echo(f"  source={parsed.source_id} route={parsed.route} version={parsed.source_version}")
+    typer.echo(f"  raw_sha256={parsed.raw_sha256}")
+    typer.echo("signature verification: not implemented -- this checks shape, not authorship.")
+
+
+# ---------------------------------------------------------------------------
+# cache
+# ---------------------------------------------------------------------------
+
+cache_app = typer.Typer(help="Inspect and clear the local caches.", no_args_is_help=True)
+app.add_typer(cache_app, name="cache")
+
+
+def _cache_report(stats: dict) -> None:
+    if not stats["enabled"]:
+        typer.echo(
+            f"caching is off ({cache.CACHE_DIR_ENV} is set to a disabling value). "
+            "Every fetch goes to the source."
+        )
+        return
+    ttl = stats["tool_cache_ttl_seconds"]
+    typer.echo(f"cache directory: {stats['path']}")
+    typer.echo(
+        f"HTTP entries: {stats['http_entries']} "
+        "(revalidated with ETag/Last-Modified on every use, so a hit is bytes "
+        "the source just confirmed)"
+    )
+    typer.echo(
+        f"result entries: {stats['tool_entries']} "
+        + (
+            f"(replayed for up to {ttl:g}s without contacting anyone)"
+            if ttl > 0
+            else f"(the result cache is OFF; set {cache.TOOL_TTL_ENV} to a number of seconds)"
+        )
+    )
+    typer.echo(f"on disk: {stats['bytes'] / 1024:.1f} KiB")
+
+    uncacheable = stats["uncacheable_urls"]
+    if uncacheable:
+        # Otherwise "0 entries" reads as a broken cache. It usually is not: most
+        # of the CMS Coverage API answers with neither an ETag nor a
+        # Last-Modified, so there is nothing to revalidate against and storing
+        # the body would break the only promise this cache makes.
+        typer.echo(
+            f"\n{len(uncacheable)} endpoint(s) cannot be cached: upstream sends no "
+            "ETag and no Last-Modified, so a stored copy could never be re-confirmed. "
+            "These are fetched fresh every time, by design:"
+        )
+        for url in uncacheable[:10]:
+            typer.echo(f"  {url}")
+        if len(uncacheable) > 10:
+            typer.echo(f"  ... and {len(uncacheable) - 10} more (--json for all)")
+
+
+@cache_app.command("info")
+def cache_info(
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Where the cache is, what is in it, and what it is allowed to do."""
+    stats = cache.cache_stats()
+    if json_output:
+        typer.echo(json.dumps(stats, indent=2))
+        raise typer.Exit(EXIT_OK)
+    _cache_report(stats)
+
+
+@cache_app.command("clear")
+def cache_clear() -> None:
+    """Delete every cached response and result."""
+    before = cache.clear_cache()
+    if not before["enabled"]:
+        typer.echo("caching is off; there was nothing to clear.")
+        raise typer.Exit(EXIT_OK)
+    typer.echo(
+        f"cleared {before['path']} -- {before['http_entries']} HTTP entry/entries, "
+        f"{before['tool_entries']} result(s), {before['bytes'] / 1024:.1f} KiB"
+    )
+
+
+# ---------------------------------------------------------------------------
+# mcp
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def mcp() -> None:
+    """Serve every discovered tool to an agent over MCP stdio."""
+    from .mcp_server import serve_stdio
+
+    serve_stdio()
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()