adopt-cli 0.3.0__py3-none-any.whl

adopt_cli/commands/policy.py

@@ -0,0 +1,164 @@
+"""`adopt probe manifest validate` and `adopt envelope validate` -- contracts §14.
+
+Both exit `3` on a violation, because both refusals are `policy` category and
+`02` §13 maps `policy` to `3`. Neither command opens a store to do its work: a
+capability manifest and an outbound envelope are documents, and validating one
+must be possible in a CI job with no `.adopt/` directory anywhere.
+
+**The envelope command is the exception that proves the boundary rule.** It needs
+a `BoundaryView`, and the boundary is *stored* -- so `--scope` reads the declared
+one. Without a scope it validates against the default metadata-only boundary,
+which is the strictest one that exists: that fallback can only ever reject more
+than the real boundary would, never less, so a caller who forgets `--scope` gets
+a conservative answer rather than a permissive one.
+"""
+
+import json
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+import yaml
+
+from adopt_cli.json_out import emit
+from adopt_cli.store_option import open_configured_store
+from adopt_detect import DEFAULT_OUTBOUND_CATEGORIES, BoundaryView
+from adopt_obs import AdoptError, ErrorCode, now
+from adopt_policy import validate_capability_manifest, validate_envelope
+from adopt_scope import ScopePath
+
+__all__ = ["envelope_app", "probe_app"]
+
+probe_app = typer.Typer(name="probe", help="Probe definitions and their capability manifests.")
+manifest_app = typer.Typer(name="manifest", help="Capability manifests.")
+probe_app.add_typer(manifest_app)
+envelope_app = typer.Typer(name="envelope", help="Outbound envelopes.")
+
+FileArgument = Annotated[Path, typer.Argument(help="The document to validate.")]
+ScopeOption = Annotated[
+    str | None,
+    typer.Option(
+        "--scope",
+        help="firm/engagement/system[/environment], to validate against the boundary "
+        "declared for that scope. Omitted, the strictest default boundary is used.",
+    ),
+]
+StoreOption = Annotated[Path | None, typer.Option("--store", help="Store path override.")]
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+
+
+def _read_document(path: Path, *, as_yaml: bool) -> Any:
+    """Parse a YAML or JSON document, refusing rather than guessing.
+
+    Raises:
+        AdoptError: ``MANIFEST_INVALID`` when the file is unreadable or malformed.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as error:
+        raise AdoptError(
+            ErrorCode.MANIFEST_INVALID,
+            message=f"cannot read {path}",
+            hint="Check the path.",
+        ) from error
+    try:
+        return yaml.safe_load(text) if as_yaml else json.loads(text)
+    except (yaml.YAMLError, json.JSONDecodeError) as error:
+        raise AdoptError(
+            ErrorCode.MANIFEST_INVALID,
+            message=f"{path} is not a well-formed document: {error}",
+            hint="A document that cannot be parsed is refused rather than partially "
+            "validated -- an unparseable declaration is not a permissive one.",
+        ) from error
+
+
+def _default_boundary() -> BoundaryView:
+    """The strictest boundary: metadata-only, nothing else permitted.
+
+    Used when no scope is named. It cannot be more permissive than a declared
+    boundary, because `metadata_only` is the floor every boundary starts from
+    (contracts §8 rule 1) -- so validating against it is conservative by
+    construction rather than by luck.
+    """
+    return BoundaryView(
+        boundary_id="",
+        system_id="",
+        environment_id=None,
+        tier="T0",
+        archetype=None,
+        knowledge_plane_location="customer",
+        control_plane_location="vendor",
+        permitted_outbound_categories=DEFAULT_OUTBOUND_CATEGORIES,
+        unavailable_capabilities=(),
+        contractual_approval_ref=None,
+        declared_at=now(),
+        decline_recommended=False,
+        archetype_floor_violated=False,
+    )
+
+
+def _boundary_for(scope: str | None, store: Path | None) -> BoundaryView:
+    if scope is None:
+        return _default_boundary()
+    parsed = ScopePath.parse(scope)
+    with open_configured_store(store) as handle:
+        resolved = handle.scope().resolve(parsed)
+        if resolved.system is None:
+            raise AdoptError(
+                ErrorCode.SCOPE_VIOLATION,
+                message="--scope must name at least firm/engagement/system",
+                hint="A boundary is declared for a system.",
+            )
+        environment_id = None if resolved.environment is None else resolved.environment.id
+        row = handle.boundary().current(system_id=resolved.system.id, environment_id=environment_id)
+        if row is None:
+            raise AdoptError(
+                ErrorCode.SCOPE_VIOLATION,
+                message=f"no boundary is declared for {scope}",
+                hint="Run `adopt init` or `adopt boundary --scope ...` first. Validating "
+                "against a boundary that was never declared would mean inventing what "
+                "the client agreed to.",
+            )
+        return BoundaryView.of(row, archetype=None)
+
+
+@manifest_app.command("validate")
+def validate_manifest(file: FileArgument, json_output: JsonOption = False) -> None:
+    """Validate a probe capability manifest. Exits `3` on a violation."""
+    verdict = validate_capability_manifest(_read_document(file, as_yaml=True))
+    emit(
+        {
+            "valid": True,
+            "violations": [],
+            "probe_id": verdict.probe_id,
+            "declared_hosts": list(verdict.declared_hosts),
+            "side_effect_policy": verdict.side_effect_policy,
+            # Returned, never judged: expiry enforcement is item 8 (PRD F11.5).
+            "approval_expires_at": verdict.approval_expires_at,
+        },
+        as_json=json_output,
+        title="adopt probe manifest validate",
+    )
+
+
+@envelope_app.command("validate")
+def validate_outbound(
+    file: FileArgument,
+    scope: ScopeOption = None,
+    store: StoreOption = None,
+    json_output: JsonOption = False,
+) -> None:
+    """Validate an outbound envelope against the boundary. Exits `3` on a violation."""
+    document = _read_document(file, as_yaml=False)
+    if not isinstance(document, dict):
+        raise AdoptError(
+            ErrorCode.MANIFEST_INVALID,
+            message=f"{file} is a {type(document).__name__}, not a JSON object",
+            hint="Contracts §8 gives the envelope shape.",
+        )
+    validate_envelope(document, _boundary_for(scope, store))
+    emit(
+        {"valid": True, "violations": []},
+        as_json=json_output,
+        title="adopt envelope validate",
+    )

adopt_cli/commands/store.py

@@ -0,0 +1,98 @@
+"""`adopt store info | doctor | migrate` -- contracts §14.
+
+**A coverage gap, closed here.** `02` §14 defines this command group and `01`
+F16.1 lists it among the verbs, and **no sprint task in `05` ever created it** --
+S2 built `adopt_store.doctor` as a library and nothing gave it a command line.
+It surfaces at S8 because Final Output Validation item 7 runs `adopt store info`
+to prove the OSS path needs no Postgres. Recorded as a gap rather than folded in
+silently, the way S0's missing `error_registry_sync.py` and S6's missing
+`adopt init` were.
+
+All three emit the one envelope §14 declares -- `{schema_version, counts{},
+findings[]}` -- because a group whose subcommands each invented a shape would
+make the contract three contracts.
+
+**`info` and `doctor` open read-only.** Looking must not repair: §8's incident
+card says rebuilding a disagreeing cache first destroys the evidence of whatever
+wrote it. Only `migrate` opens for writing, and it is the only one that can.
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from adopt_cli.json_out import emit
+from adopt_cli.store_option import open_configured_store, open_for_migration
+from adopt_obs import ExitCode
+
+__all__ = ["app"]
+
+app = typer.Typer(
+    name="store",
+    help="Inspect, diagnose and migrate a store. Looking never repairs.",
+    no_args_is_help=True,
+)
+
+StoreOption = Annotated[
+    Path | None,
+    typer.Option("--store", help="Store path. Defaults to the resolved ADOPT_STORE_PATH."),
+]
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+
+
+@app.command()
+def info(store: StoreOption = None, json_output: JsonOption = False) -> None:
+    """Schema version and row counts. Reads; never writes."""
+    with open_configured_store(store, read_only=True) as handle:
+        payload = {
+            "schema_version": handle.schema_version,
+            "counts": handle.counts(),
+            "findings": [],
+        }
+    emit(payload, as_json=json_output, title="adopt store info")
+
+
+@app.command()
+def doctor(store: StoreOption = None, json_output: JsonOption = False) -> None:
+    """Report every finding in the store, and change nothing.
+
+    Exit `4` with findings -- degraded success, not failure. The store opened,
+    the checks ran, and their answers are trustworthy; what needs a human is
+    what they found.
+    """
+    with open_configured_store(store, read_only=True) as handle:
+        findings = handle.doctor()
+        payload = {
+            "schema_version": handle.schema_version,
+            "counts": handle.counts(),
+            "findings": [
+                {
+                    "code": finding.code.value,
+                    "table": finding.table,
+                    "subject_id": finding.subject_id,
+                    "detail": finding.detail,
+                }
+                for finding in findings
+            ],
+        }
+
+    emit(payload, as_json=json_output, title="adopt store doctor")
+    if findings:
+        raise typer.Exit(ExitCode.DEGRADED_WITH_FINDINGS)
+
+
+@app.command()
+def migrate(store: StoreOption = None, json_output: JsonOption = False) -> None:
+    """Apply pending forward migrations, then report the resulting version.
+
+    Forward-only, always: implementation spec §7.4 states the schema has no
+    rollback, and recovery is older code against a newer store.
+    """
+    with open_for_migration(store) as handle:
+        payload = {
+            "schema_version": handle.schema_version,
+            "counts": handle.counts(),
+            "findings": [],
+        }
+    emit(payload, as_json=json_output, title="adopt store migrate")

adopt_cli/commands/version.py

@@ -0,0 +1,37 @@
+"""`adopt version` -- contracts §14.
+
+Output: ``{version, schema_version, export_version, sbom_sha256, build_id}``.
+
+`sbom_sha256` and `build_id` are **build facts, not configuration**: they are
+injected by the release job and are absent from a development checkout, where
+they render as `null`. Reporting a fabricated build id would make the field
+useless for the thing it exists for -- tying a binary in the field back to the
+artifact that was signed.
+"""
+
+from importlib import metadata
+from typing import Any, Final
+
+from adopt_cli._build_info import BUILD_ID, SBOM_SHA256
+from adopt_const import EXPORT_VERSION, SCHEMA_VERSION
+
+__all__ = ["build_payload"]
+
+_DISTRIBUTION: Final[str] = "adopt-cli"
+
+
+def _package_version() -> str:
+    try:
+        return metadata.version(_DISTRIBUTION)
+    except metadata.PackageNotFoundError:  # pragma: no cover -- source checkout only
+        return "0.0.0+unknown"
+
+
+def build_payload() -> dict[str, Any]:
+    return {
+        "version": _package_version(),
+        "schema_version": SCHEMA_VERSION,
+        "export_version": EXPORT_VERSION,
+        "sbom_sha256": SBOM_SHA256,
+        "build_id": BUILD_ID,
+    }

adopt_cli/config.py

@@ -0,0 +1,162 @@
+"""Configuration resolution: flag > environment > project file > user file > default.
+
+Every key reports **where its value came from**, because "it works on my
+machine" is almost always a resolution-order question, and answering it by
+reading code takes an order of magnitude longer than reading it off
+``adopt doctor``.
+
+Secrets are marked in the registry and are reported by **presence and source
+only, never by value**. A secret is read once at process start into a typed
+object; it never enters a store, a trace, an error message or a log line.
+"""
+
+import os
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import Final
+
+__all__ = [
+    "REGISTRY",
+    "ConfigKey",
+    "Resolution",
+    "Source",
+    "load_config_file",
+    "project_config_path",
+    "resolve_all",
+    "user_config_path",
+]
+
+
+class Source(StrEnum):
+    """Where a resolved value came from. Order here is resolution order."""
+
+    FLAG = "flag"
+    ENV = "env"
+    PROJECT_FILE = "project-file"
+    USER_FILE = "user-file"
+    DEFAULT = "default"
+
+
+@dataclass(frozen=True)
+class ConfigKey:
+    name: str
+    default: str | None
+    description: str
+    is_secret: bool = False
+
+
+@dataclass(frozen=True)
+class Resolution:
+    key: str
+    value: str | None
+    source: Source
+    is_secret: bool
+
+    def render(self) -> dict[str, str | None]:
+        """The `doctor` shape from contracts §14: ``{key, value, source}``.
+
+        A secret renders as presence, never as value. There is no verbosity
+        flag that reveals it: a flag that can print a secret will eventually be
+        used in CI with logs attached to a ticket.
+        """
+        shown = ("<set>" if self.value else "<unset>") if self.is_secret else self.value
+        return {"key": self.key, "value": shown, "source": str(self.source)}
+
+
+#: The configuration registry from implementation spec §3.
+#:
+#: Feature flags are typed accessors and **default off**, without exception.
+#: New behaviour arrives behind a flag that is off until it has earned being on.
+REGISTRY: Final[tuple[ConfigKey, ...]] = (
+    ConfigKey("ADOPT_STORE_PATH", ".adopt/store.db", "Canonical SQLite store location."),
+    ConfigKey(
+        "ADOPT_RUNTIME_PATH",
+        ".adopt/runtime.db",
+        "Runtime annex: agent-run idempotency and in-client audit. Never exported.",
+    ),
+    ConfigKey(
+        "ADOPT_OFFLINE",
+        "1",
+        "Offline is the default posture. Network egress requires an explicit opt-in.",
+    ),
+    ConfigKey("ADOPT_ADAPTER", None, "Configured model adapter id. No default: none is required."),
+    ConfigKey("ADOPT_ADAPTER_ENDPOINT", None, "OpenAI-compatible local endpoint, when configured."),
+    ConfigKey(
+        "ADOPT_MODEL",
+        None,
+        "Model identifier. Never hard-coded, including as a default -- a default here is "
+        "how a tool aimed at every lab acquires a house lab.",
+    ),
+    ConfigKey("ADOPT_LOG_LEVEL", "info", "Minimum emitted log level."),
+    ConfigKey("ADOPT_LOG_FORMAT", "json", "Log rendering. JSON is the only supported sink format."),
+    ConfigKey("ADOPT_SCRATCH_DIR", None, "Scratch directory for bundle and export work."),
+    ConfigKey(
+        "ADOPT_PROMPTS_DIR",
+        "prompts",
+        "Immutable prompt versions (AI spec §5). `03` §1.2 places the directory at the "
+        "repository root, which is not inside any package -- so its location is "
+        "configuration rather than a path a module can compute, and `doctor` reports "
+        "where it resolved from.",
+    ),
+    ConfigKey("ADOPT_FEATURE_AGENT_DISAMBIGUATION", "0", "Archetype disambiguation pass. Off."),
+    ConfigKey("ADOPT_FEATURE_DBOS_BACKEND", "0", "DBOS workflow backend. Off."),
+    ConfigKey("ADOPT_FEATURE_POSTGRES_STORE", "0", "Postgres store realization. Off."),
+    ConfigKey("ADOPT_FEATURE_VECTOR_INDEX", "0", "Vector index behind the VectorIndex seam. Off."),
+    ConfigKey("ADOPT_API_KEY", None, "Provider credential, when an adapter is configured.", True),
+)
+
+
+def project_config_path(cwd: Path | None = None) -> Path:
+    return (cwd or Path.cwd()) / ".adopt" / "config.toml"
+
+
+def user_config_path(home: Path | None = None) -> Path:
+    return (home or Path.home()) / ".config" / "adopt" / "config.toml"
+
+
+def load_config_file(path: Path) -> dict[str, str]:
+    """Read a config file, tolerating absence but not malformation.
+
+    A missing file is normal. A malformed file is not silently ignored: a
+    typo'd config that is quietly skipped produces the exact "it works on my
+    machine" failure this module exists to answer.
+    """
+    if not path.exists():
+        return {}
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    return {str(k).upper(): str(v) for k, v in data.items() if not isinstance(v, dict)}
+
+
+def resolve_all(
+    *,
+    flags: Mapping[str, str] | None = None,
+    env: Mapping[str, str] | None = None,
+    project: Mapping[str, str] | None = None,
+    user: Mapping[str, str] | None = None,
+) -> list[Resolution]:
+    """Resolve every registered key, recording the winning source.
+
+    All four layers are injectable so the resolution order can be tested
+    without touching the real environment or the real filesystem.
+    """
+    layers: tuple[tuple[Source, Mapping[str, str]], ...] = (
+        (Source.FLAG, flags or {}),
+        (Source.ENV, os.environ if env is None else env),
+        (Source.PROJECT_FILE, project or {}),
+        (Source.USER_FILE, user or {}),
+    )
+
+    resolutions: list[Resolution] = []
+    for key in REGISTRY:
+        value: str | None = key.default
+        source = Source.DEFAULT
+        for candidate_source, layer in layers:
+            found = layer.get(key.name)
+            if found:
+                value, source = found, candidate_source
+                break
+        resolutions.append(Resolution(key.name, value, source, key.is_secret))
+    return resolutions

adopt_cli/json_out.py

@@ -0,0 +1,65 @@
+"""Output rendering. `--json` suppresses every human affordance.
+
+Two renderings, one source. The JSON envelope is a contract from 0.3.0: command
+names, flags, JSON keys and exit codes are additive-only thereafter, exactly as
+for the schema. The human rendering is free to change.
+"""
+
+import json
+import sys
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+__all__ = ["emit", "emit_error"]
+
+_stdout = Console(file=sys.stdout, highlight=False, soft_wrap=True)
+_stderr = Console(file=sys.stderr, highlight=False, soft_wrap=True)
+
+
+def emit(payload: dict[str, Any], *, as_json: bool, title: str = "") -> None:
+    """Render a command result.
+
+    In JSON mode nothing but the envelope reaches stdout -- no banner, no
+    colour, no progress. A caller piping into `jq` must not have to strip
+    anything.
+    """
+    if as_json:
+        print(json.dumps(payload, indent=2, sort_keys=False, default=str))
+        return
+    _render_human(payload, title)
+
+
+def _render_human(payload: dict[str, Any], title: str) -> None:
+    if title:
+        _stdout.print(f"[bold]{title}[/bold]")
+    for key, value in payload.items():
+        if isinstance(value, list) and value and isinstance(value[0], dict):
+            table = Table(title=key, title_justify="left", show_lines=False)
+            for column in value[0]:
+                table.add_column(column)
+            for row in value:
+                table.add_row(*[str(row.get(c, "")) for c in value[0]])
+            _stdout.print(table)
+        elif isinstance(value, list):
+            _stdout.print(f"{key}: {', '.join(str(v) for v in value) or '(none)'}")
+        elif isinstance(value, dict):
+            _stdout.print(f"{key}:")
+            for inner_key, inner_value in value.items():
+                _stdout.print(f"  {inner_key}: {inner_value}")
+        else:
+            _stdout.print(f"{key}: {value}")
+
+
+def emit_error(envelope: dict[str, Any], *, as_json: bool) -> None:
+    """Render the one documented error envelope to stderr."""
+    if as_json:
+        print(json.dumps(envelope, indent=2, default=str), file=sys.stderr)
+        return
+    error = envelope.get("error", {})
+    _stderr.print(f"[bold red]{error.get('code')}[/bold red] ({error.get('category')})")
+    if error.get("message"):
+        _stderr.print(str(error["message"]))
+    if error.get("hint"):
+        _stderr.print(f"[dim]hint: {error['hint']}[/dim]")

adopt_cli/main.py

@@ -0,0 +1,150 @@
+"""The `adopt` CLI entry point.
+
+Three postures are set here and inherited by every command added later:
+
+* **`--json` on every command.** The JSON envelope is a contract from 0.3.0.
+* **Offline by default.** Network egress requires `--allow-network`. In offline
+  mode the process opens no socket other than to a configured local adapter
+  endpoint.
+* **Typed errors map to stable exit codes.** `0` success, `1` operational
+  failure, `2` usage error, `3` policy refusal, `4` degraded success with
+  findings. The mapping lives in `adopt_obs.errors` -- a second copy here would
+  be a second place to get it wrong.
+"""
+
+import sys
+from typing import Annotated
+
+import click
+import typer
+
+from adopt_cli.commands import agent as agent_commands
+from adopt_cli.commands import boundary as boundary_command
+from adopt_cli.commands import coverage as coverage_commands
+from adopt_cli.commands import detect as detect_command
+from adopt_cli.commands import doctor as doctor_command
+from adopt_cli.commands import freshness as freshness_commands
+from adopt_cli.commands import identity as identity_commands
+from adopt_cli.commands import init as init_command
+from adopt_cli.commands import interchange as interchange_commands
+from adopt_cli.commands import policy as policy_commands
+from adopt_cli.commands import store as store_commands
+from adopt_cli.commands import version as version_command
+from adopt_cli.json_out import emit, emit_error
+from adopt_obs import AdoptError, ExitCode, get_logger
+
+__all__ = ["app", "main"]
+
+app = typer.Typer(
+    name="adopt",
+    help="Adoption-Phase Platform CLI. Offline by default; no telemetry, ever.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+app.add_typer(identity_commands.app)
+app.add_typer(coverage_commands.app)
+app.add_typer(freshness_commands.app)
+app.add_typer(store_commands.app)
+app.add_typer(policy_commands.probe_app)
+app.add_typer(policy_commands.envelope_app)
+app.add_typer(agent_commands.app)
+
+# `init`, `detect` and `boundary` are bare commands, not groups: contracts §14
+# names them `adopt init [path]`, `adopt detect [path]` and `adopt boundary`.
+app.command("init")(init_command.init)
+app.command("detect")(detect_command.detect)
+app.command("boundary")(boundary_command.boundary)
+
+# Registered as bare commands rather than a group: contracts §14 names them
+# `adopt export DIR` and `adopt import DIR`. `import` is a Python keyword, so the
+# function is `import_` and the command name is given explicitly -- the CLI
+# surface is the contract, not the identifier that happens to implement it.
+app.command("export")(interchange_commands.export)
+app.command("import")(interchange_commands.import_)
+
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+NetworkOption = Annotated[
+    bool,
+    typer.Option(
+        "--allow-network",
+        help="Permit network egress for this invocation. Offline is the default posture.",
+    ),
+]
+
+
+@app.callback()
+def _root(ctx: typer.Context, allow_network: NetworkOption = False) -> None:
+    """Set the process posture before any command runs."""
+    ctx.ensure_object(dict)
+    ctx.obj["allow_network"] = allow_network
+
+
+@app.command()
+def version(json_output: JsonOption = False) -> None:
+    """Report the binary, schema and export versions and the build provenance."""
+    emit(version_command.build_payload(), as_json=json_output, title="adopt version")
+
+
+@app.command()
+def doctor(json_output: JsonOption = False) -> None:
+    """Report every configuration key with its resolved value and source.
+
+    Exits `4` when there are findings: degraded success, not failure. `doctor`
+    never repairs what it reports.
+    """
+    payload, findings = doctor_command.build_payload()
+    emit(payload, as_json=json_output, title="adopt doctor")
+    if findings:
+        raise typer.Exit(ExitCode.DEGRADED_WITH_FINDINGS)
+
+
+def _wants_json(argv: list[str] | None) -> bool:
+    return "--json" in (argv if argv is not None else sys.argv[1:])
+
+
+def _exit_code_of(error: click.ClickException | click.exceptions.Exit) -> int:
+    if isinstance(error, click.exceptions.Exit):
+        return int(error.exit_code)
+    if isinstance(error, click.UsageError):
+        error.show()
+        return ExitCode.USAGE_ERROR
+    error.show()
+    return ExitCode.OPERATIONAL_FAILURE
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Console-script entry point carrying the contracts §13 exit-code mapping.
+
+    A typed `AdoptError` escaping a command is rendered as the one documented
+    envelope and mapped to its category's exit code here, so no command has to
+    remember to do it. Click's own control-flow exceptions are translated in the
+    same place for the same reason.
+
+    **`app(...)` is invoked with `standalone_mode=False`, and in that mode Click
+    *returns* the exit code of a `typer.Exit` rather than raising it.** Discarding
+    the return value therefore silently turned every deliberate non-zero exit
+    into `0` -- including the `4` that contracts §14 gives `adopt doctor` and
+    `adopt coverage recompute` when there are findings. The `except` clause below
+    still catches an `Exit` raised from outside a command, so both paths are
+    covered; neither on its own is.
+    """
+    log = get_logger("adopt_cli")
+    try:
+        result = app(args=argv, standalone_mode=False)
+    except AdoptError as error:
+        emit_error(error.to_envelope(), as_json=_wants_json(argv))
+        log.error("cli.failed", code=str(error.code), category=str(error.category))
+        return error.exit_code
+    except click.exceptions.Abort:
+        log.warn("cli.aborted")
+        return ExitCode.OPERATIONAL_FAILURE
+    except (click.ClickException, click.exceptions.Exit) as error:
+        return _exit_code_of(error)
+    # A command returning an `int` returned it through `typer.Exit`; commands
+    # return `None` otherwise, so there is no value here to confuse with a code.
+    return result if isinstance(result, int) else ExitCode.SUCCESS
+
+
+if __name__ == "__main__":  # pragma: no cover -- exercised through the release entry point
+    sys.exit(main())