mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/commands/catalog_search.py

@@ -0,0 +1,71 @@
+"""``mr-data catalog-search`` over one exact verified sealed catalog."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.sources.catalog.gating import CatalogRequirement
+from mostlyright.data_harness.sources.catalog.search import search_catalog
+from mostlyright.data_harness.ux.commands import CommandSpec
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--catalog", dest="dir", type=Path, required=True, help="the sealed catalog folder"
+    )
+    parser.add_argument("--catalog-sha256", required=True, help="the exact SHA-256 of catalog.json")
+    parser.add_argument("--question", required=True, help="the source question to answer")
+    parser.add_argument(
+        "--limit",
+        type=int,
+        choices=range(1, 21),
+        default=5,
+        help="the maximum number of ranked sources to inspect",
+    )
+    parser.add_argument(
+        "--format",
+        dest="formats",
+        action="append",
+        default=None,
+        help="a required data format; repeat to allow more than one",
+    )
+    parser.add_argument(
+        "--max-update-seconds",
+        type=int,
+        default=31_536_000,
+        help="the slowest acceptable source update interval in seconds",
+    )
+    parser.add_argument(
+        "--intended-use", default="analysis", help="how the selected source will be used"
+    )
+    parser.add_argument(
+        "--lifecycle", default="candidate", help="the lifecycle stage required of the source"
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    requirement = CatalogRequirement(
+        intended_use=args.intended_use,
+        lifecycle=args.lifecycle,
+        required_data_formats=tuple(args.formats or ("csv",)),
+        max_update_frequency_seconds=args.max_update_seconds,
+        require_open_access=True,
+        require_live=True,
+    )
+    return search_catalog(
+        catalog_root=args.dir,
+        catalog_manifest_sha256=args.catalog_sha256,
+        question=args.question,
+        requirement=requirement,
+        limit=args.limit,
+    )
+
+
+SPEC = CommandSpec(
+    name="catalog-search",
+    help="search one exact verified sealed source catalog",
+    add_arguments=add_arguments,
+    run=run,
+)

mostlyright/data_harness/ux/commands/catalog_update.py

@@ -0,0 +1,437 @@
+"""``mr-data catalog-update`` installs one published catalog release on this computer.
+
+The release is fetched from the address given -- or read from a file already here -- and nothing
+about it is trusted until its bytes match the published SHA-256 the person typed. After that the
+archive is screened, the generation is written next to the ones already installed, the real store
+verification runs over it before it is made visible, and the recorded state advances only when
+the release descends from the generation this computer already has. When the recorded state
+already names the typed digest, the installed folder is re-verified and nothing is fetched.
+
+THE THIRD WAY IN: ``--channel-url`` with ``--channel-manifest-sha256``. Typing an archive URL and
+its digest is what one person does once. Tracking a channel is what everybody else does, and it is
+what the hosted workers do (see ``sources.catalog.channel``): the pinned manifest names the
+current generation, and the digest the person types is the manifest's rather than the archive's.
+The trust story is unchanged -- one digest typed by a person, everything else derived from it --
+and the installation itself is the identical code path, so a channel install and a hand-typed
+install produce the same generation folder and the same recorded state.
+
+This command needs the local execution lane, and so does ``catalog-search``: verifying an
+installed generation *is* loading it with the real store reader. A thin install therefore refuses
+this command by name and says what to install, which is the correct answer -- there is nothing for
+a catalogue to do on a machine that cannot search it. See ``docs/CATALOG-CHANNEL.md``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from mostlyright.data_harness.sources.catalog.update import (
+    MAX_RELEASE_ARCHIVE_BYTES,
+    confirm_already_current,
+    install_release,
+)
+from mostlyright.data_harness.sources.contracts import SourceContractError
+from mostlyright.data_harness.ux.commands import CommandSpec
+from mostlyright.data_harness.ux.credentials import CREDENTIALS_DIR_NAME
+from mostlyright.data_harness.ux.plain_file import PlainFileRefusal, open_plain_file, read_bounded
+
+# GitHub serves release assets through one redirect onto its object hosts, so an address on the
+# release page implies those hostnames. Any other address stands alone: the allowlist is the
+# host the person named, plus every host they explicitly allowed with --allow-host.
+_GITHUB_HOSTNAMES = frozenset({"github.com", "api.github.com", "www.github.com"})
+_GITHUB_ASSET_HOSTNAMES = (
+    "objects.githubusercontent.com",
+    "release-assets.githubusercontent.com",
+)
+_RELEASE_MEDIA_TYPES = ("application/zip", "application/octet-stream")
+
+#: A bearer token is a few kilobytes at most; anything larger is not a token.
+MAX_CHANNEL_TOKEN_BYTES = 8192
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--catalog",
+        dest="dir",
+        type=Path,
+        default=Path.home() / CREDENTIALS_DIR_NAME / "catalog",
+        help="the folder this computer keeps its installed catalog in",
+    )
+    parser.add_argument(
+        "--archive",
+        type=Path,
+        default=None,
+        help="a release archive already on this computer",
+    )
+    parser.add_argument(
+        "--release-url",
+        default=None,
+        help="the https address of one published release archive",
+    )
+    parser.add_argument(
+        "--channel-url",
+        default=None,
+        help="the https address of one release channel's channel.json",
+    )
+    parser.add_argument(
+        "--channel-manifest-sha256",
+        default=None,
+        help="the published SHA-256 of that channel manifest",
+    )
+    parser.add_argument(
+        "--channel-token-file",
+        type=Path,
+        default=None,
+        help="a file holding one bearer token, for a channel that is not world-readable",
+    )
+    parser.add_argument(
+        "--archive-sha256",
+        default=None,
+        help="the published SHA-256 of the release archive; not used with --channel-url",
+    )
+    parser.add_argument(
+        "--allow-host",
+        dest="allow_hosts",
+        action="append",
+        default=None,
+        help="one more hostname the download may reach; repeat to allow more than one",
+    )
+    parser.add_argument(
+        "--replace",
+        action="store_true",
+        help="accept a release that does not descend from the installed generation",
+    )
+
+
+def _allowed_hostnames(url: str, extra: tuple[str, ...]) -> tuple[str, ...]:
+    """The closed set of hosts one release download may reach, from the address and the caller."""
+
+    hostname = urlsplit(url).hostname
+    if not hostname:
+        raise SourceContractError(
+            "CATALOG_UPDATE_URL", url, "must be one https address with a hostname"
+        )
+    allowed = (hostname,)
+    if hostname in _GITHUB_HOSTNAMES:
+        allowed = allowed + _GITHUB_ASSET_HOSTNAMES
+    for host in extra:
+        if host not in allowed:
+            allowed = (*allowed, host)
+    return allowed
+
+
+def _fetch(url: str, allow_hosts: tuple[str, ...]) -> bytes:
+    from mostlyright.data_harness.acquisition.http import (
+        PinnedHttpsRetriever,
+        RetrievalLimits,
+        StdlibPinnedTransport,
+    )
+    from mostlyright.data_harness.acquisition.url_policy import EgressPolicy, SystemResolver
+
+    retriever = PinnedHttpsRetriever(
+        resolver=SystemResolver(),
+        egress_policy=EgressPolicy(allowed_hostnames=_allowed_hostnames(url, allow_hosts)),
+        transport=StdlibPinnedTransport(),
+        limits=RetrievalLimits(
+            max_response_bytes=MAX_RELEASE_ARCHIVE_BYTES,
+            max_redirects=3,
+            max_requests=4,
+            allowed_media_types=_RELEASE_MEDIA_TYPES,
+            # The default transport budget suits metadata pages; a release archive is up to a
+            # gibibyte, so the read and total budgets are raised to their ceilings.
+            read_timeout_seconds=300.0,
+            total_timeout_seconds=600.0,
+        ),
+    )
+    return retriever.retrieve(url).content
+
+
+class PolicyPinnedChannelTransport:
+    """The channel's two GETs, over the egress hardening ``--release-url`` already got.
+
+    WHY THIS EXISTS. One command had two fetch paths with materially different egress properties.
+    ``--release-url`` went through :class:`PinnedHttpsRetriever`: DNS resolved once into an
+    approved peer set, the connection made to one of those addresses with the hostname verified in
+    TLS, metadata and internal hosts denied by name, obfuscated numeric hosts denied, and a closed
+    host allowlist. ``--channel-url`` went through the standard library with none of it. Digest
+    pinning made the *content* untrustable-until-verified either way, which is why nothing had
+    gone wrong -- but "the digest would have caught it" is a statement about the bytes that
+    arrived, not about which host this computer was persuaded to talk to, and the channel path
+    could be steered at a link-local metadata address by an address a person typed.
+
+    So the channel transport is the pinned one, and the seam is the ``ChannelTransport`` protocol
+    that ``sources.catalog.channel_client`` already accepts. Nothing in that module changes: the
+    worker keeps the standard-library transport it needs to read its own instance metadata, which
+    this policy would deny by name -- and denying it is the correct behaviour for a person's
+    laptop and the wrong behaviour for the worker, which is precisely why the choice is made here,
+    at the command, rather than there.
+
+    WHAT IS NOT CLAIMED, STATED PRECISELY. This is the pinned TRANSPORT, not
+    :class:`PinnedHttpsRetriever`. The retriever is what enforces the redirect budget, the request
+    budget and the media-type allowlist, and none of the three is reimplemented here. Two of them
+    are unnecessary: ``StdlibPinnedTransport`` speaks ``http.client`` and cannot follow a redirect
+    at all, so a 302 comes back AS a 302 and ``channel_client._get`` refuses it on the status --
+    which is a stronger guarantee than a budget of zero and does not depend on one. The third is
+    genuinely absent: nothing here checks ``Content-Type``, and it would be the wrong check anyway,
+    because the two objects on this route are a JSON manifest and a zip archive. What stands in its
+    place is what always stood there -- both are refused unless their bytes hash to a digest that
+    was pinned before the request was made.
+
+    So the properties this transport does add, and the only ones it adds, are the egress ones: one
+    DNS epoch bound into an approved peer set, the connection made to one of those addresses with
+    the hostname verified in TLS, metadata and internal hosts denied by name, obfuscated numeric
+    hosts denied, and a closed allowlist. Those are exactly the ones the channel path did not have.
+    """
+
+    def __init__(self, allowed_hostnames: tuple[str, ...]) -> None:
+        from mostlyright.data_harness.acquisition.http import StdlibPinnedTransport
+        from mostlyright.data_harness.acquisition.url_policy import EgressPolicy, SystemResolver
+
+        self._resolver = SystemResolver()
+        self._egress_policy = EgressPolicy(allowed_hostnames=allowed_hostnames)
+        self._transport = StdlibPinnedTransport()
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        maximum: int,
+    ) -> tuple[int, bytes, Mapping[str, str]]:
+        from mostlyright.data_harness.acquisition.http import (
+            RetrievalLimits,
+            TransportFailureError,
+        )
+        from mostlyright.data_harness.acquisition.url_policy import validate_public_https_url
+
+        if method != "GET" or body is not None:
+            raise SourceContractError(
+                "CATALOG_UPDATE_URL", url, "a channel is read with one GET and no request body"
+            )
+        target = validate_public_https_url(
+            url, resolver=self._resolver, egress_policy=self._egress_policy
+        )
+        # ⚠ ONLY THE FIELDS THIS TRANSPORT ACTUALLY READS. `StdlibPinnedTransport.request` reads
+        # `max_response_bytes` and the three timeouts and nothing else -- the redirect, request and
+        # media-type budgets belong to the retriever, which is not on this path. Setting them here
+        # would be configuration that looks enforced and is not, which is worse than a gap because
+        # the next reader stops looking for one. The byte ceiling is the caller's own per-route
+        # bound; the read and total budgets are the ones the hand-typed release download uses,
+        # because an archive is up to a gibibyte and the metadata defaults are for a JSON page.
+        limits = RetrievalLimits(
+            max_response_bytes=maximum,
+            read_timeout_seconds=300.0,
+            total_timeout_seconds=600.0,
+        )
+        # Every approved address from the one DNS epoch, in turn. A peer that fails before it
+        # answers is a peer, not a verdict; anything else -- a refused hostname, a response over
+        # the ceiling -- is the answer and stops here.
+        failures: list[str] = []
+        for approved_ip in target.approved_ips:
+            try:
+                response = self._transport.request(
+                    target, approved_ip=approved_ip, headers=dict(headers), limits=limits
+                )
+            except TransportFailureError as error:
+                # Each peer's own reason, kept. "No address answered" on its own cannot tell a
+                # refused connection from a failed handshake from a body cut mid-transfer, and
+                # those are three different things to go and look at.
+                failures.append(f"{approved_ip}: {error.detail}")
+                continue
+            return response.status, response.body, dict(response.headers)
+        raise SourceContractError(
+            "CATALOG_CHANNEL_FETCH",
+            url,
+            "no approved address for this channel host answered -- " + "; ".join(failures),
+        )
+
+
+def _read_local(path: Path) -> bytes:
+    """Read the release archive the person named, through the one plain-file rule.
+
+    A second hard link to the archive is fine: nothing about the file is trusted anyway until
+    its bytes match the digest the person typed next to it.
+    """
+
+    try:
+        descriptor, size = open_plain_file(path)
+    except PlainFileRefusal as refusal:
+        raise SourceContractError(
+            "CATALOG_UPDATE_ARCHIVE", str(path), "release archive could not be read as one file"
+        ) from refusal
+    try:
+        if size > MAX_RELEASE_ARCHIVE_BYTES:
+            raise SourceContractError(
+                "CATALOG_UPDATE_ARCHIVE", str(path), "release archive is larger than the bound"
+            )
+        raw = read_bounded(descriptor, max_bytes=MAX_RELEASE_ARCHIVE_BYTES)
+    finally:
+        os.close(descriptor)
+    if len(raw) > MAX_RELEASE_ARCHIVE_BYTES:
+        raise SourceContractError(
+            "CATALOG_UPDATE_ARCHIVE", str(path), "release archive is larger than the bound"
+        )
+    return raw
+
+
+def _channel_authorization(path: Path | None) -> str | None:
+    """Read one bearer token out of a file, for a channel whose bucket is not world-readable.
+
+    A file rather than an argument or an environment variable, for the reason every other
+    credential in this product is a file: an argument is in the process table and the shell
+    history, and a token that reaches object storage is worth exactly as much as the objects it
+    reads. The token itself never appears in a refusal, a receipt, or a URL.
+    """
+
+    if path is None:
+        return None
+    try:
+        descriptor, size = open_plain_file(path)
+    except PlainFileRefusal as refusal:
+        raise SourceContractError(
+            "CATALOG_UPDATE_TOKEN", str(path), "channel token could not be read as one file"
+        ) from refusal
+    try:
+        if size > MAX_CHANNEL_TOKEN_BYTES:
+            raise SourceContractError(
+                "CATALOG_UPDATE_TOKEN", str(path), "channel token is larger than the bound"
+            )
+        raw = read_bounded(descriptor, max_bytes=MAX_CHANNEL_TOKEN_BYTES)
+    finally:
+        os.close(descriptor)
+    token = raw.decode("ascii", errors="replace").strip()
+    if not token or not all(0x21 <= ord(character) <= 0x7E for character in token):
+        raise SourceContractError(
+            "CATALOG_UPDATE_TOKEN", str(path), "channel token must be one printable ASCII line"
+        )
+    return token if token.lower().startswith("bearer ") else "Bearer " + token
+
+
+def channel_transport(channel_url: str) -> PolicyPinnedChannelTransport:
+    """The hardened transport one channel install fetches through.
+
+    A named function rather than an inline construction, so a test can substitute the seam the way
+    it already substitutes the standard-library one, and so the allowlist this path uses is
+    visible in one place: the pinned channel's own host, and nothing else at all.
+
+    ⚠ NOT ``_allowed_hostnames``. That builder widens the set to GitHub's asset hosts when the
+    address is a GitHub one, which is right for a hand-typed release: a GitHub release URL is
+    served by one redirect onto those hosts, so an allowlist that omitted them would refuse the
+    ordinary case. This path follows no redirect and derives the archive address from the pinned
+    channel address, so a second host is unreachable from here -- and an allowlist naming a host
+    that cannot be reached is an allowlist whose written promise is not the one it keeps.
+    """
+
+    hostname = urlsplit(channel_url).hostname
+    if not hostname:
+        raise SourceContractError(
+            "CATALOG_UPDATE_URL", channel_url, "must be one https address with a hostname"
+        )
+    return PolicyPinnedChannelTransport((hostname,))
+
+
+def _run_channel(args: argparse.Namespace) -> dict[str, Any]:
+    """Install whatever generation the pinned channel manifest currently names."""
+
+    from mostlyright.data_harness.sources.catalog.channel import build_catalog_channel_pin
+    from mostlyright.data_harness.sources.catalog.channel_client import install_from_channel
+
+    if args.archive is not None or args.release_url is not None or args.archive_sha256 is not None:
+        raise SourceContractError(
+            "CATALOG_UPDATE_URL",
+            "arguments",
+            "--channel-url names the release on its own; drop --archive, --release-url "
+            "and --archive-sha256",
+        )
+    if args.allow_hosts:
+        # ⚠ REFUSED, NOT HONOURED, AND NOT IGNORED EITHER. On the hand-typed path --allow-host
+        # widens a set that a redirect can actually reach. A channel reaches exactly two addresses
+        # and derives both from the pinned channel URL -- the manifest's own address, and the
+        # archive one object over in the same folder -- and it follows no redirect, so a further
+        # host is a host this command will never open a connection to. Honouring the flag would
+        # widen a policy to admit something unreachable, which reads to whoever typed it as though
+        # the host had been allowed. Saying so is the only answer that is true.
+        raise SourceContractError(
+            "CATALOG_UPDATE_URL",
+            "arguments",
+            "--allow-host means nothing with --channel-url: the manifest and the archive are both "
+            "fetched from the host the pinned channel address names, and no redirect is followed",
+        )
+    if args.channel_manifest_sha256 is None:
+        raise SourceContractError(
+            "CATALOG_UPDATE_URL",
+            "arguments",
+            "--channel-url needs --channel-manifest-sha256, the digest the channel published",
+        )
+    pin = build_catalog_channel_pin(
+        channel_url=args.channel_url, manifest_sha256=args.channel_manifest_sha256
+    )
+    report = install_from_channel(
+        Path(args.dir),
+        pin,
+        transport=channel_transport(pin.channel_url),
+        authorization=_channel_authorization(args.channel_token_file),
+        replace=args.replace,
+    )
+    payload = report.to_dict()
+    payload["channel"] = {
+        "channel_url": pin.channel_url,
+        "manifest_sha256": pin.manifest_sha256,
+        "pin_selection_id": pin.selection_id,
+    }
+    return payload
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    if args.channel_url is not None:
+        return _run_channel(args)
+    for name, flag in (
+        ("channel_manifest_sha256", "--channel-manifest-sha256"),
+        ("channel_token_file", "--channel-token-file"),
+    ):
+        if getattr(args, name) is not None:
+            raise SourceContractError(
+                "CATALOG_UPDATE_URL",
+                "arguments",
+                f"{flag} only means something with --channel-url",
+            )
+    if args.archive_sha256 is None:
+        raise SourceContractError(
+            "CATALOG_UPDATE_DIGEST_SPELLING",
+            "arguments",
+            "--archive-sha256 is required unless the release comes from --channel-url",
+        )
+    if (args.archive is None) == (args.release_url is None):
+        raise SourceContractError(
+            "CATALOG_UPDATE_URL",
+            "arguments",
+            "exactly one of --archive and --release-url names the release",
+        )
+    current = confirm_already_current(Path(args.dir), expected_archive_sha256=args.archive_sha256)
+    if current is not None:
+        return current.to_dict()
+    if args.archive is not None:
+        raw = _read_local(args.archive)
+    else:
+        raw = _fetch(args.release_url, tuple(args.allow_hosts or ()))
+    report = install_release(
+        Path(args.dir),
+        raw,
+        expected_archive_sha256=args.archive_sha256,
+        replace=args.replace,
+    )
+    return report.to_dict()
+
+
+SPEC = CommandSpec(
+    name="catalog-update",
+    help="install one published catalog release after checking its exact fingerprint",
+    add_arguments=add_arguments,
+    run=run,
+)

mostlyright/data_harness/ux/commands/deploy.py

@@ -0,0 +1,134 @@
+"""``mr-data deploy`` -- stage and activate one exact verified Build."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.ux.commands import CommandSpec
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.description = (
+        "Stage one exact verified Build in Studio and activate it as the authenticated Editor."
+    )
+    parser.add_argument("run_dir", type=Path, help="the folder holding the sealed Build")
+    parser.add_argument(
+        "--previous-run-dir",
+        type=Path,
+        help="required to update a Dataset that is already live: the run directory whose "
+        "deployment published it, and whose Build this version follows",
+    )
+    parser.add_argument("--dataset-name", required=True, help="what to call the managed Dataset")
+    parser.add_argument(
+        "--cron",
+        default="0 0 * * *",
+        help="UTC refresh schedule; Studio pauses it unless every source is refreshable",
+    )
+    parser.add_argument(
+        "--resume",
+        action="store_true",
+        help="recover the exact journaled deployment after an interruption or lost response",
+    )
+    parser.add_argument("--max-runs-per-month", type=int, help="tighten the monthly run allowance")
+    parser.add_argument(
+        "--max-concurrent-runs", type=int, help="tighten how many runs may happen at once"
+    )
+    parser.add_argument(
+        "--max-monthly-cost-units",
+        type=int,
+        help="tighten the recorded monthly spend ceiling, in cost units",
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    # Authentication is resolved before the Build path is read. An absent/empty credential cannot
+    # be mistaken for permission to inspect or mutate a deployment.
+    from mostlyright.data_harness import cli
+    from mostlyright.data_harness.deploy import (
+        Cadence,
+        DeployRefused,
+        build_deployment_request,
+    )
+    from mostlyright.data_harness.governors import CapPolicy
+    from mostlyright.data_harness.hosted_deploy import (
+        HostedDeployError,
+        deploy_managed_dataset,
+        exchange_studio_token,
+    )
+    from mostlyright.data_harness.ux.credentials import LoginError, resolve_cloud_credentials
+
+    try:
+        credentials = resolve_cloud_credentials()
+    except LoginError as error:
+        raise cli._CliUsageError(f"{error.code}: {error.detail}") from error
+    try:
+        token = exchange_studio_token(credentials)
+    except HostedDeployError as error:
+        raise cli._CliUsageError(f"{error.code}: {error.detail}") from error
+    try:
+        caps = CapPolicy().tighten(
+            max_runs_per_month=args.max_runs_per_month,
+            max_concurrent_runs=args.max_concurrent_runs,
+            max_monthly_cost_units=args.max_monthly_cost_units,
+        )
+    except ValueError as error:
+        raise cli._CliUsageError(str(error)) from error
+    try:
+        # An ordinary Editor deploy is one authenticated Studio transaction chain. It always
+        # re-verifies the Build locally, but it neither looks for a coordinator review session nor
+        # asks a second person to approve the proposal. Studio records the request and the Editor's
+        # decision durably before activation; this command only recovers an interrupted chain.
+        # One predecessor, named once, threaded to both layers that need it. The Recipe layer
+        # authenticates the version chain out of it whenever this Build's execution mode is not
+        # `initial`; the deployment layer reads the Studio project, plan, and Dataset that its
+        # deployment published, so a corrected Build updates that Dataset instead of founding a
+        # second one. `hosted_deploy` settles which of the two shapes this invocation is before it
+        # writes anything -- see `_deployment_predecessor`.
+        request = build_deployment_request(
+            candidate_run_dir=args.run_dir,
+            previous_run_dir=args.previous_run_dir,
+            dataset_name=args.dataset_name,
+            target=None,
+            caps=caps,
+            cadence=Cadence(label="Studio UTC cron", cycle_template=args.cron),
+            review_authority_provider=None,
+            require_reviewed_build=False,
+        )
+        return deploy_managed_dataset(
+            request,
+            run_dir=args.run_dir,
+            previous_run_dir=args.previous_run_dir,
+            token=token,
+            credentials=credentials,
+            resume=args.resume,
+            cron=args.cron,
+            max_concurrent_runs=caps.max_concurrent_runs,
+        )
+    except (DeployRefused, HostedDeployError) as error:
+        if isinstance(error, HostedDeployError):
+            message = f"{error.code}: {error.detail}"
+        else:
+            message = str(error)
+        raise cli._CliUsageError(message) from error
+
+
+def exit_code(payload: Mapping[str, Any]) -> int:
+    return 0 if payload.get("status") == "dataset_activation_queued" else 1
+
+
+def _mapping(value: Any, label: str, usage_error: type[Exception]) -> Mapping[str, object]:
+    if not isinstance(value, dict):
+        raise usage_error(f"the {label} document must be one object")
+    return value
+
+
+SPEC = CommandSpec(
+    name="deploy",
+    help="stage one verified Build and activate it as the authenticated Editor",
+    add_arguments=add_arguments,
+    run=run,
+    exit_code=exit_code,
+)