mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/commands/deploy_dataset.py

@@ -0,0 +1,98 @@
+"""``mr-data deploy-dataset`` -- bring one released hosted Build here and write its notebook."""
+
+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
+
+# Where the released Build lands when the caller does not say. It is a fixed name under the folder
+# the deployment was run from, and being fixed is the point: a viewer can be opened on it before
+# the hosted work has finished -- a folder that is not there yet is a target the viewer already
+# accepts -- so the Dataset tab arrives without anyone going and looking for a path first. The
+# deployment folder itself is not usable as the destination: it already holds the Build that was
+# deployed, and a folder holds one Build.
+DEFAULT_DESTINATION = "hosted"
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.description = (
+        "Bring the Build this deployment's run released back to this machine and write its "
+        "dataset notebook. The rows are transferred through one short-lived Mostly Right cloud "
+        "transfer, checked against the fingerprints the release sealed, and checked again here by "
+        "the same checks a Build made on this machine passes. Nothing is written until all of "
+        "that has passed, and the notebook is derived here rather than downloaded. It lands in "
+        "the 'hosted' folder beside the deployment record unless you say otherwise, and a "
+        "workbench window already open on that folder shows its Dataset tab by itself."
+    )
+    parser.add_argument(
+        "run_dir",
+        type=Path,
+        help="the folder the deployment was run from, which holds its record",
+    )
+    parser.add_argument(
+        "--into",
+        type=Path,
+        help=(
+            "where to write the Build and its notebook; made if it is not there yet, "
+            "and never written over. Defaults to the 'hosted' folder beside the deployment record"
+        ),
+    )
+    parser.add_argument(
+        "--research-dir",
+        type=Path,
+        help="the open workbench folder to tell about the dataset when it lands",
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    # Authentication is resolved before anything local is read, so an absent or empty credential
+    # can never be mistaken for permission to look at a deployment. Typed refusals are raised, not
+    # rewritten: this command's failures each carry a code with a fix written against it, and
+    # flattening them into a usage error would tell a person their command line was wrong when
+    # what actually happened was a transfer that did not match its fingerprint.
+    from mostlyright.data_harness import cli
+    from mostlyright.data_harness.hosted_dataset import materialize_hosted_dataset
+    from mostlyright.data_harness.hosted_deploy import HostedDeployError, exchange_studio_token
+    from mostlyright.data_harness.ux.credentials import resolve_cloud_credentials
+    from mostlyright.data_harness.ux.hosted_run_status import journaled_activation
+
+    credentials = resolve_cloud_credentials()
+    token = exchange_studio_token(credentials)
+    # The same reader `mr-data deploy-status` uses. One deployment journal, one function that
+    # knows its shape, and one set of sentences for a journal that is not ready yet.
+    activated = journaled_activation(args.run_dir)
+    if token.workspace_id != activated.workspace_id:
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH",
+            "this deployment belongs to a different workspace from the one you are signed in to",
+        )
+    destination = args.into if args.into is not None else args.run_dir / DEFAULT_DESTINATION
+    visual_store = cli._visual_store_for_research(
+        args.research_dir, run_id=f"hosted-{activated.run_id}"
+    )
+    handoff = materialize_hosted_dataset(
+        destination,
+        dataset_id=activated.dataset_id,
+        table_id=activated.table_id,
+        hosted_run_id=activated.run_id,
+        token=token,
+        visual_store=visual_store,
+    )
+    return {"status": "hosted_dataset_ready", **handoff.to_dict()}
+
+
+def exit_code(payload: Mapping[str, Any]) -> int:
+    return 0 if payload.get("status") == "hosted_dataset_ready" else 1
+
+
+SPEC = CommandSpec(
+    name="deploy-dataset",
+    help="bring the Build a deployment released back here and write its dataset notebook",
+    add_arguments=add_arguments,
+    run=run,
+    exit_code=exit_code,
+)

mostlyright/data_harness/ux/commands/deploy_plan.py

@@ -0,0 +1,105 @@
+"""``mr-data deploy-plan`` -- build a deployment request without deploying anything."""
+
+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 = (
+        "Plan a live dataset request from one reviewed Build. This command contacts nothing, "
+        "deploys nothing, and reports whether the recorded caps are enforced here."
+    )
+    parser.add_argument("run_dir", type=Path, help="the folder holding the reviewed Build")
+    parser.add_argument(
+        "--previous-run-dir",
+        type=Path,
+        help="required for a refresh or backfill: the reviewed Build this version follows",
+    )
+    parser.add_argument("--dataset-name", required=True, help="what to call the planned dataset")
+    parser.add_argument(
+        "--target",
+        type=Path,
+        required=True,
+        help="the file naming the intended project, region, Studio account, and job",
+    )
+    parser.add_argument(
+        "--corroboration",
+        type=Path,
+        required=True,
+        help="the file containing an independent reading of the intended target project",
+    )
+    parser.add_argument("--cadence", default="daily", help="how often it should look for new data")
+    parser.add_argument("--cycle-template", help="the cycle variable the source publishes on")
+    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 planned monthly spend ceiling, in cost units",
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    # Function-local imports are the point: parser construction and command inventory do not load
+    # deployment verification, recipe execution, or cap-governor implementation modules.
+    from mostlyright.data_harness import cli
+    from mostlyright.data_harness.deploy import Cadence, DeployRefused, plan_deployment
+    from mostlyright.data_harness.deploy_target import DeployTargetError
+    from mostlyright.data_harness.governors import CapPolicy
+
+    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:
+        result = plan_deployment(
+            descriptor=_mapping(cli._read_json(args.target), "target", cli._CliUsageError),
+            corroboration=_mapping(
+                cli._read_json(args.corroboration), "corroboration", cli._CliUsageError
+            ),
+            candidate_run_dir=args.run_dir,
+            previous_run_dir=args.previous_run_dir,
+            dataset_name=args.dataset_name,
+            caps=caps,
+            cadence=Cadence(label=args.cadence, cycle_template=args.cycle_template),
+            review_authority_provider=cli._runtime_review_authority_provider(),
+        )
+    except (DeployRefused, DeployTargetError) as error:
+        raise cli._CliUsageError(str(error)) from error
+    return result.to_dict()
+
+
+def exit_code(payload: Mapping[str, Any]) -> int:
+    return 0 if payload.get("status") == "deployment_plan_ready" 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-plan",
+    help="plan a live dataset request without deploying it",
+    add_arguments=add_arguments,
+    run=run,
+    exit_code=exit_code,
+)

mostlyright/data_harness/ux/commands/deploy_status.py

@@ -0,0 +1,104 @@
+"""``mr-data deploy-status`` -- what Studio says about the run this deployment queued.
+
+`mr-data deploy --resume` hands back a `run_id` and returns. This command is how that identifier
+becomes an answer: it reads the run's coordinates out of the deployment journal the deploy already
+wrote, asks Studio for that exact run, and prints the state Studio holds -- one of thirteen, each
+with what it means and what to do about it.
+
+It is a read. It sends no body, carries no idempotency key, and reaches exactly one Studio
+operation, so running it on a finished deployment, on a sleeping laptop's return, or from a
+different terminal an hour later cannot change anything about the run it is reporting on, or
+anything else Studio holds.
+
+With no `--watch-seconds` it makes exactly one request and reports what came back. With one, it
+reads on a bounded backoff until the state stops changing on its own and lists each distinct state
+it saw; if the bound arrives first it says so, and says which state the run was actually in.
+
+The exit code is 1 when the run needs a person, when it ended without a version, or when a watch
+ran out before it settled -- so `mr-data deploy-status RUN_DIR --watch-seconds 900` reads as a gate
+in a script. A run still working, and a run whose version is live, are both 0.
+"""
+
+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
+from mostlyright.data_harness.ux.hosted_run_status import (
+    MAX_WATCH_SECONDS,
+    RELEASED,
+    WATCHING,
+    report_run_status,
+)
+
+DESCRIPTION = (
+    "Report the real state of the run one deployment queued, read from Mostly Right Studio's own "
+    "durable record of it. The run is named by the deployment journal inside RUN_DIR, so a "
+    "process that was killed, a laptop that slept, or a fresh terminal picks the same run back "
+    "up. It sends no request body and no idempotency key, nothing Studio holds is changed, and "
+    "no state is shown that Studio did not report."
+)
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.description = DESCRIPTION
+    parser.add_argument(
+        "run_dir", type=Path, help="the folder whose deployment queued the run to report on"
+    )
+    parser.add_argument(
+        "--watch-seconds",
+        type=int,
+        help=(
+            "keep reading until the run settles, waiting at most this many seconds "
+            f"(1-{MAX_WATCH_SECONDS}); without it this makes exactly one request"
+        ),
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    # Authentication is resolved before the journal is read, exactly as `deploy` resolves it before
+    # the Build path is read: an absent or empty credential cannot be mistaken for permission to
+    # read a deployment's state.
+    from mostlyright.data_harness import cli
+    from mostlyright.data_harness.hosted_deploy import HostedDeployError, 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)
+        return report_run_status(
+            args.run_dir,
+            token=token,
+            credentials=credentials,
+            watch_seconds=args.watch_seconds,
+        )
+    except HostedDeployError as error:
+        raise cli._CliUsageError(f"{error.code}: {error.detail}") from error
+
+
+def exit_code(payload: Mapping[str, Any]) -> int:
+    """1 when somebody has to do something, so this reads as a gate in a script.
+
+    A run that is still working is not a failure and a released one is the point, so both are 0.
+    Everything else -- the two states waiting on somebody, the three that ended without a version,
+    and a watch that ran out before the run settled -- is 1.
+    """
+
+    if payload.get("status") != "run_status_reported":
+        return 1
+    return 0 if payload.get("run_disposition") in {WATCHING, RELEASED} else 1
+
+
+SPEC = CommandSpec(
+    name="deploy-status",
+    help="report what Studio says about the run one deployment queued",
+    add_arguments=add_arguments,
+    run=run,
+    exit_code=exit_code,
+)

mostlyright/data_harness/ux/commands/diff.py

@@ -0,0 +1,74 @@
+"""``mr-data diff`` -- point at two builds and ask what is different.
+
+This module is the command and nothing else: its arguments, and the one call that turns them into
+the payload both renderings are built from. The comparison itself lives in
+:mod:`mostlyright.data_harness.ux.diffing`, so the same answer is available to a browser page
+without going through argparse.
+
+Nothing here prints, and nothing here catches: a refusal is a typed error, and the command line
+renders it with the sentences the remediation map supplies.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.ux.commands import CommandSpec
+from mostlyright.data_harness.ux.diffing import compare_builds
+
+# Said in the command's own help, not only in a design document: a difference is an answer, and
+# scripting against a nonzero exit code for one would be scripting against something this command
+# never promised.
+DESCRIPTION = (
+    "Compare two builds and say what changed: which columns were added, removed or retyped, "
+    "whether the row count moved, and whether the data itself is different. Both builds are "
+    "replayed and verified before anything is compared. "
+    "Finding a difference is not a failure, so the exit code is 0 whether the two builds match "
+    "or not; read the status field from --json (builds_identical or builds_differ) if you want "
+    "to act on the answer."
+)
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.description = DESCRIPTION
+    parser.add_argument(
+        "left",
+        type=Path,
+        help="the first build folder, or the Workbench folder that holds one",
+    )
+    parser.add_argument(
+        "right",
+        type=Path,
+        help="the second build folder, or the Workbench folder that holds one",
+    )
+    parser.add_argument(
+        "--columns-only",
+        action="store_true",
+        help=(
+            "list only the changes to the columns; the count and the status still cover "
+            "every change"
+        ),
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    # Imported here, not at the top: this package is loaded while the command line is still being
+    # set up. Calling the command line's own helper rather than restating its rule is what stops
+    # diff and verify ever disagreeing about which folder a Workbench folder's run lives in.
+    from mostlyright.data_harness.cli import _candidate_run_target
+
+    comparison = compare_builds(
+        _candidate_run_target(args.left),
+        _candidate_run_target(args.right),
+    )
+    return comparison.to_dict(columns_only=args.columns_only)
+
+
+SPEC = CommandSpec(
+    name="diff",
+    help="compare two builds and say what changed",
+    add_arguments=add_arguments,
+    run=run,
+)

mostlyright/data_harness/ux/commands/index.py

@@ -0,0 +1,84 @@
+"""``mr-data index``: explicitly rebuild the private local Build index."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.local_search.build_index import (
+    BuildDiscoveryLimits,
+    LocalSearchIndexError,
+    build_private_index,
+)
+from mostlyright.data_harness.sources.contracts import SourceContractError
+from mostlyright.data_harness.ux.commands import CommandSpec
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--build-root", type=Path, required=True, help="the explicit Build root")
+    parser.add_argument(
+        "--index-root", type=Path, required=True, help="the explicit private index output root"
+    )
+    parser.add_argument("--max-depth", type=int, required=True, help="maximum discovery depth")
+    parser.add_argument(
+        "--max-entries", type=int, required=True, help="maximum directory entries inspected"
+    )
+    parser.add_argument("--max-builds", type=int, required=True, help="maximum Builds inspected")
+    parser.add_argument(
+        "--max-receipt-bytes", type=int, required=True, help="maximum bytes in one Build receipt"
+    )
+    parser.add_argument(
+        "--max-member-bytes", type=int, required=True, help="maximum bytes in one Build member"
+    )
+    parser.add_argument(
+        "--max-aggregate-bytes",
+        type=int,
+        required=True,
+        help="maximum aggregate verified Build bytes",
+    )
+    parser.add_argument(
+        "--max-elapsed-seconds",
+        type=float,
+        required=True,
+        help="maximum elapsed discovery and verification time",
+    )
+    parser.add_argument(
+        "--max-diagnostics", type=int, required=True, help="maximum retained diagnostics"
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    try:
+        limits = BuildDiscoveryLimits(
+            max_depth=args.max_depth,
+            max_entries=args.max_entries,
+            max_builds=args.max_builds,
+            max_receipt_bytes=args.max_receipt_bytes,
+            max_member_bytes=args.max_member_bytes,
+            max_aggregate_bytes=args.max_aggregate_bytes,
+            max_elapsed_seconds=args.max_elapsed_seconds,
+            max_diagnostics=args.max_diagnostics,
+        )
+        published = build_private_index(args.build_root, args.index_root, limits=limits)
+    except LocalSearchIndexError as error:
+        raise SourceContractError(error.code, error.path, error.detail) from error
+    manifest = published.manifest
+    return {
+        "schema_version": "mr-data-private-index.v1",
+        "status": "build_index_published",
+        "manifest_sha256": published.manifest_sha256,
+        "aggregate_sha256": manifest.aggregate_sha256,
+        "entry_count": manifest.entry_count,
+        "locator_count": manifest.locator_count,
+        "diagnostic_count": manifest.diagnostic_count,
+        "total_bytes": manifest.total_bytes,
+    }
+
+
+SPEC = CommandSpec(
+    name="index",
+    help="build one bounded private index from exact-verified local Builds",
+    add_arguments=add_arguments,
+    run=run,
+)

mostlyright/data_harness/ux/commands/inventory.py

@@ -0,0 +1,47 @@
+"""``mr-data inventory`` -- the closed sets this build is held to, with their caveats.
+
+This module is the command and nothing else: its one argument and the one call that turns it into
+the payload both renderings are built from. The lists live in
+:mod:`mostlyright.data_harness.ux.inventory`, derived from the frozensets the contract checker
+uses, so the same answer is available to a browser page without going through argparse.
+
+``--section`` offers exactly the sections that exist, taken from the inventory itself, so asking
+for one that is not there is answered by the command line with the list of the ones that are.
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from mostlyright.data_harness.ux.commands import CommandSpec
+from mostlyright.data_harness.ux.inventory import SECTION_NAMES, build_inventory
+
+DESCRIPTION = (
+    "List what this build can do: the cleaning steps, the types a cast may target, the join "
+    "relationships, the engines, the checks every build must pass, and the words a source option "
+    "is written in. Every list is read out of the code at the moment you ask, so it cannot fall "
+    "behind what the code does. Each one carries the sentence you need in order not to misread "
+    "it, on the same screen rather than in a footnote."
+)
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.description = DESCRIPTION
+    parser.add_argument(
+        "--section",
+        choices=SECTION_NAMES,
+        help="list one section on its own instead of all of them",
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    return build_inventory().to_dict(section=args.section)
+
+
+SPEC = CommandSpec(
+    name="inventory",
+    help="list what this build can do: operations, types, joins, engines, and checks",
+    add_arguments=add_arguments,
+    run=run,
+)

mostlyright/data_harness/ux/commands/list_builds.py

@@ -0,0 +1,143 @@
+"""``mr-data list`` -- every build under a folder, and how much was actually read about each.
+
+The module is named for what it does rather than for the command, because ``list`` is a name
+Python already uses; ``SPEC.name`` is what reaches the command line.
+
+The one thing this command must never do is imply a check it did not perform. Listing reads each
+Receipt and stops there, so every row and the closing note say ``listed, not verified`` until
+``--verify`` replays each build. Both output modes carry the same words, from the same facts.
+
+That holds for the listing as a whole as well as for each row in it. The listing-level word comes
+from :func:`readers.listing_verification`, which reads the entries; it is never the flag the caller
+passed, because ``--verify`` is a request and "every build passed" is an outcome.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.ux.commands import CommandSpec
+from mostlyright.data_harness.ux.readers import (
+    DEFAULT_LIST_DEPTH,
+    DEFAULT_LIST_ROOT,
+    MAX_LIST_DEPTH,
+    BuildEntry,
+    list_builds,
+    listing_verification,
+)
+
+
+def _depth(value: str) -> int:
+    """Bound how far down to look at the command line, before anything is opened."""
+
+    try:
+        depth = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"{value!r} is not a whole number of folders") from None
+    if not 0 <= depth <= MAX_LIST_DEPTH:
+        raise argparse.ArgumentTypeError(f"how far down to look must be from 0 to {MAX_LIST_DEPTH}")
+    return depth
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "root",
+        type=Path,
+        nargs="?",
+        default=DEFAULT_LIST_ROOT,
+        help=f"the folder to look in (default {DEFAULT_LIST_ROOT})",
+    )
+    parser.add_argument(
+        "--verify",
+        action="store_true",
+        help="replay every build found and check it against its sealed bytes",
+    )
+    parser.add_argument(
+        "--depth",
+        type=_depth,
+        default=DEFAULT_LIST_DEPTH,
+        help=f"how many folders down to look (default {DEFAULT_LIST_DEPTH})",
+    )
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    entries = list_builds(args.root, verify=args.verify, max_depth=args.depth)
+    return {
+        "status": "builds_listed",
+        "root": str(Path(args.root)),
+        "depth": args.depth,
+        "verification": listing_verification(entries, verify=args.verify),
+        "note": _note(entries, root=Path(args.root), depth=args.depth, verify=args.verify),
+        "builds": _builds_payload(entries),
+    }
+
+
+def _builds_payload(entries: tuple[BuildEntry, ...]) -> dict[str, Any]:
+    """Facts about a build go in values; the keys only count. See the note in readers.py."""
+
+    width = len(str(max(len(entries), 1)))
+    return {
+        f"build {index:0{width}d}": entry.to_dict() for index, entry in enumerate(entries, start=1)
+    }
+
+
+def _note(
+    entries: tuple[BuildEntry, ...],
+    *,
+    root: Path,
+    depth: int,
+    verify: bool,
+) -> str:
+    """One sentence that says what was done, and never more than was done.
+
+    The counts are of what was actually read, not of what the walk stopped at. A folder holding no
+    Build was not read from a Receipt and was not replayed, so it is counted separately rather than
+    folded into a claim the listing cannot make about it.
+    """
+
+    if not entries:
+        return (
+            f"No builds under {root}, looking {depth} folders down. Run mr-data build to make one."
+        )
+    described = [entry for entry in entries if entry.reason is None]
+    if not described:
+        return f"{_leftover(entries)} {_ASK_FOR_MORE}"
+    if verify:
+        head = f"Each of these {len(described)} was replayed and matched its sealed bytes."
+    else:
+        head = (
+            f"These {len(described)} were read from their own Receipts and nothing more. "
+            "Add --verify to replay each one against its sealed bytes."
+        )
+    leftover = _leftover(entries)
+    return head if leftover is None else f"{head} {leftover} {_ASK_FOR_MORE}"
+
+
+# Where the exact wording went. The listing carries one plain sentence per unreadable entry and no
+# second engineering one, so it says which command does give the full answer.
+_ASK_FOR_MORE = "Run mr-data show on one of those folders for the full answer."
+
+
+def _leftover(entries: tuple[BuildEntry, ...]) -> str | None:
+    """What the listing found but could not describe, counted by which of the two it was."""
+
+    unbuilt = sum(1 for entry in entries if entry.nothing_built)
+    unreadable = sum(1 for entry in entries if entry.reason is not None and not entry.nothing_built)
+    parts = []
+    if unbuilt:
+        parts.append(f"{unbuilt} {'folder' if unbuilt == 1 else 'folders'} here holds no build yet")
+    if unreadable:
+        parts.append(f"{unreadable} could not be read")
+    if not parts:
+        return None
+    return f"{' and '.join(parts)}; each says so below."
+
+
+SPEC = CommandSpec(
+    name="list",
+    help="list the builds under a folder, and say whether they were checked",
+    add_arguments=add_arguments,
+    run=run,
+)