regents-cli 1.0.0__py3-none-any.whl

regents_cli/__init__.py

@@ -0,0 +1 @@
+"""The regents command line."""

regents_cli/__main__.py

@@ -0,0 +1,3 @@
+from regents_cli.app import run
+
+run()

regents_cli/app.py

@@ -0,0 +1,94 @@
+"""The `regents` executable: one namespace per site, one answer shape, one set of exit codes."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+from importlib.metadata import version
+
+import click
+
+from regents_cli import output
+from regents_cli.auth import auth_group
+from regents_cli.errors import (
+    EXIT_CANCELLED,
+    EXIT_CODES,
+    EXIT_FAILED,
+    EXIT_OK,
+    CommandError,
+    UsageError,
+)
+from regents_cli.platforms import pinned_platforms
+from regents_cli.runner import platform_group
+from regents_cli.techtree.cli import techtree_group
+
+EPILOG = "Add --json to any command for machine output.\n\nExit codes:\n\n" + "\n\n".join(
+    f"  {code}  {meaning}" for code, meaning in EXIT_CODES.items()
+)
+
+
+def root() -> click.Group:
+    group = click.Group(
+        "regents",
+        help="Every Regents Labs site from one command line.",
+        epilog=EPILOG,
+        no_args_is_help=True,
+        params=[
+            click.Option(
+                ["--version"],
+                is_flag=True,
+                expose_value=False,
+                is_eager=True,
+                callback=_print_version,
+                help="Print the version.",
+            )
+        ],
+    )
+    platforms = pinned_platforms()
+    group.add_command(
+        auth_group(
+            [p.site for p in platforms if any(c.authority == "wallet-proof" for c in p.commands)]
+        )
+    )
+    for platform in platforms:
+        group.add_command(platform_group(platform))
+    group.add_command(techtree_group())
+    return group
+
+
+def _print_version(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
+    if value:
+        click.echo(f"regents {version('regents-cli')}")
+        ctx.exit()
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    as_json = "--json" in args[: args.index("--") if "--" in args else len(args)]
+    try:
+        root().main(args, prog_name="regents", standalone_mode=False)
+    except click.exceptions.NoArgsIsHelpError as shown:
+        click.echo(shown.ctx.get_help() if shown.ctx else "")
+    except click.UsageError as error:
+        problem = UsageError(error.format_message())
+        output.emit_error(problem, as_json=as_json)
+        return problem.exit_code
+    except CommandError as error:
+        output.emit_error(error, as_json=as_json)
+        return error.exit_code
+    except (click.Abort, KeyboardInterrupt):
+        output.emit_error(
+            CommandError("cancelled", "The command was interrupted.", exit_code=EXIT_CANCELLED),
+            as_json=as_json,
+        )
+        return EXIT_CANCELLED
+    except click.exceptions.Exit as done:
+        return done.exit_code
+    except click.ClickException as error:
+        output.emit_error(CommandError("command_error", error.format_message()), as_json=as_json)
+        return EXIT_FAILED
+    return EXIT_OK
+
+
+def run() -> None:
+    sys.exit(main())

regents_cli/auth.py

@@ -0,0 +1,161 @@
+"""`regents auth`: sign in to a site with the agent key on this machine, or with your own."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any
+
+import click
+
+from regents_cli import output, siwa
+from regents_cli.errors import CommandError, UsageError
+from regents_cli.http import Request, base_address, send
+from regents_cli.platforms import pinned_platforms
+from regents_cli.runner import read_stdin
+
+TIMEOUT = click.Option(
+    ["--timeout-ms"],
+    type=click.IntRange(1, 300_000),
+    default=30_000,
+    show_default=True,
+    help="How long to wait for each answer.",
+)
+JSON = click.Option(["--json", "as_json"], is_flag=True, help="Print the answer as JSON.")
+
+
+def auth_group(sites: list[str]) -> click.Group:
+    site = click.Option(
+        ["--site"], type=click.Choice(sites), required=True, help="The site to sign in to."
+    )
+    group = click.Group(
+        "auth",
+        help="Sign in to a site with a wallet. One agent key on this machine signs every "
+        f"request; it lives in {siwa.key_file()}.",
+        no_args_is_help=True,
+    )
+    group.add_command(
+        click.Command(
+            "login",
+            callback=login,
+            params=[
+                site,
+                click.Option(
+                    ["--phase"],
+                    type=click.Choice(["prepare", "send"]),
+                    help="Sign in with your own key: prepare prints the message to sign; "
+                    'send reads {"wallet_address", "nonce", "message", "signature"} on stdin.',
+                ),
+                click.Option(
+                    ["--wallet-address"], help="Your own wallet's address, with --phase prepare."
+                ),
+                click.Option(
+                    ["--siwa-url"],
+                    default=siwa.BROKER,
+                    show_default=True,
+                    help="The sign-in server.",
+                ),
+                JSON,
+                TIMEOUT,
+            ],
+            help="Sign in to a site. Creates the agent key on first use.",
+        )
+    )
+    group.add_command(
+        click.Command(
+            "status",
+            callback=status,
+            params=[JSON, TIMEOUT],
+            help="Show the agent key's address and each site's sign-in. Signed in to Regents, "
+            "it also shows the account the agent is paired with, and Regents counts that as "
+            "the agent checking in.",
+        )
+    )
+    group.add_command(
+        click.Command(
+            "logout",
+            callback=logout,
+            params=[site, JSON],
+            help="Forget a site's sign-in. The agent key stays.",
+        )
+    )
+    return group
+
+
+def login(
+    site: str,
+    phase: str | None,
+    wallet_address: str | None,
+    siwa_url: str,
+    as_json: bool,
+    timeout_ms: int,
+) -> None:
+    if (phase == "prepare") != (wallet_address is not None):
+        raise UsageError("--wallet-address goes with --phase prepare, and only with it.")
+    if phase == "prepare" and wallet_address is not None:
+        output.emit(siwa.challenge(site, wallet_address, siwa_url, timeout_ms), as_json=as_json)
+        return
+    created = False
+    if phase == "send":
+        signed = read_stdin(timeout_ms)
+        fields = {"wallet_address", "nonce", "message", "signature"}
+        if not isinstance(signed, dict) or set(signed) != fields:
+            raise UsageError(
+                'stdin must hold {"wallet_address", "nonce", "message", "signature"}: the '
+                "answer of --phase prepare with the message's signature added."
+            )
+        sign_in = siwa.verify(site, signed, siwa_url, timeout_ms, local=False)
+    else:
+        key = siwa.load_key()
+        if key is None:
+            key, created = siwa.create_key(), True
+        sign_in = siwa.sign_in_with_key(site, key, siwa_url, timeout_ms)
+    answer: dict[str, Any] = {
+        "site": site,
+        "wallet_address": sign_in.wallet_address,
+        "signed_in_until": sign_in.expires_at,
+        "signs": "this machine" if sign_in.local else "you",
+    }
+    if created:
+        answer["key_created"] = str(siwa.key_file())
+    output.emit(answer, as_json=as_json)
+
+
+def status(as_json: bool, timeout_ms: int) -> None:
+    key = siwa.load_key()
+    sign_ins = siwa.sign_ins()
+    answer: dict[str, Any] = {
+        "agent_key": key.address if key is not None else None,
+        "sign_ins": [
+            {
+                "site": site,
+                "wallet_address": sign_in.wallet_address,
+                "signed_in_until": sign_in.expires_at,
+                "fresh": sign_in.fresh(),
+                "signs": "this machine" if sign_in.local else "you",
+            }
+            for site, sign_in in sign_ins.items()
+        ],
+    }
+    if "regents" in sign_ins:
+        answer["paired_with"] = paired_account(timeout_ms)
+    output.emit(answer, as_json=as_json)
+
+
+def paired_account(timeout_ms: int) -> dict[str, Any] | None:
+    """The agent's pairing on Regents, as `regents protocol agents me` reads it; None unpaired."""
+    platform = next(p for p in pinned_platforms() if p.site == "regents")
+    me = next(c for c in platform.commands if c.words == ("agents", "me"))
+    request = Request(me.method, me.path, {}, None)
+    request = replace(request, headers=siwa.sign(request, siwa.current("regents", timeout_ms)))
+    try:
+        answer = send(base_address(None, platform.env_var, platform.base_url), request, timeout_ms)
+    except CommandError as error:
+        if error.code == "not_paired":
+            return None
+        raise
+    paired: dict[str, Any] = answer["data"]
+    return paired
+
+
+def logout(site: str, as_json: bool) -> None:
+    output.emit({"site": site, "signed_out": siwa.remove_sign_in(site)}, as_json=as_json)

regents_cli/check_commands.py

@@ -0,0 +1,146 @@
+"""Check site command descriptions against the format and the site's own OpenAPI documents.
+
+    python -m regents_cli.check_commands
+        every pinned platforms/<name>/commands.json, with the documents pinned beside it
+    python -m regents_cli.check_commands <commands.json> <openapi file>...
+        one site's description, for the site's own `make check-cli`
+
+A site runs it at a pinned regents-cli commit, with nothing checked out:
+
+    uv run --no-project \\
+        --with "regents-cli[check] @ git+https://github.com/regents-ai/regents-cli@<commit>" \\
+        python -m regents_cli.check_commands cli/commands.json <openapi.json>
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections import Counter
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import Draft202012Validator
+
+SHARED_FLAGS = frozenset({"json", "help", "version", "base-url", "timeout-ms", "phase"})
+METHODS = ("get", "put", "post", "patch", "delete")
+
+
+def read_document(path: Path) -> Any:
+    text = path.read_text("utf-8")
+    return json.loads(text) if path.suffix == ".json" else yaml.safe_load(text)
+
+
+def operations_in(documents: list[Any]) -> dict[str, tuple[str, str]]:
+    found = {}
+    for document in documents:
+        for route, item in (document.get("paths") or {}).items():
+            for method in METHODS:
+                operation = (item or {}).get(method) or {}
+                if "operationId" in operation:
+                    found[operation["operationId"]] = (method.upper(), route)
+    return found
+
+
+def problems_in(description: Any, operations: dict[str, tuple[str, str]]) -> list[str]:
+    schema = json.loads(
+        files("regents_cli.schemas").joinpath("commands.v1.json").read_text("utf-8")
+    )
+    errors = sorted(Draft202012Validator(schema).iter_errors(description), key=lambda e: e.path)
+    if errors:
+        return [f"/{'/'.join(map(str, e.absolute_path))} {e.message}" for e in errors]
+
+    problems = []
+    shapes = Counter(re.sub(r"<[^>]+>", "<>", c["command"]) for c in description["commands"])
+    problems += [f'two commands have the shape "{shape}"' for shape, n in shapes.items() if n > 1]
+
+    for entry in description["commands"]:
+
+        def say(message: str, entry: dict[str, Any] = entry) -> None:
+            problems.append(f"{entry['command']}: {message}")
+
+        args = entry.get("arguments", [])
+        flags = entry.get("flags", [])
+        flag_names = [f["name"] for f in flags]
+        inputs = args + flags
+
+        placeholders = [w[1:-1] for w in entry["command"].split(" ") if w.startswith("<")]
+        if placeholders != [a["name"] for a in args]:
+            say("arguments must match the <words> in the command, in order")
+        for name, n in Counter(i["name"] for i in inputs).items():
+            if n > 1:
+                say(f"input {name} is listed twice")
+        if entry["command"].split(" ")[0] == "doctor":
+            say("doctor is regents' own command for every site")
+        for name in flag_names:
+            if name in SHARED_FLAGS:
+                say(f"--{name} is a shared flag")
+
+        path_fields = sorted(i["field"] for i in inputs if i["in"] == "path")
+        if path_fields != sorted(re.findall(r"\{([^}]+)\}", entry["path"])):
+            say(
+                f"path inputs ({', '.join(path_fields) or 'none'}) "
+                f"must fill exactly {entry['path']}"
+            )
+        for i in inputs:
+            if "enum" in i and i["type"] != "string":
+                say(f"{i['name']}: only string inputs take enum")
+            if ("minimum" in i or "maximum" in i) and i["type"] != "integer":
+                say(f"{i['name']}: only integer inputs take minimum and maximum")
+
+        sends_body = (
+            any(i["in"] == "body" for i in inputs) or "body" in entry or "stdin_fields" in entry
+        )
+        if sends_body and entry["method"] in ("GET", "DELETE"):
+            say(f"{entry['method']} sends no body")
+        if "stdin_fields" in entry and entry["authority"] != "wallet-proof":
+            say("only wallet-proof commands read body fields from stdin")
+        for name in entry.get("required_one_of", []):
+            if name not in flag_names:
+                say(f"required_one_of names --{name}, which is not a flag")
+        pagination = entry.get("pagination")
+        if pagination and pagination["flag"] not in flag_names:
+            say(f"pagination passes the cursor as --{pagination['flag']}, which is not a flag")
+
+        operation = operations.get(entry["operation_id"])
+        if operation is None:
+            say(f"operation {entry['operation_id']} is not in the site's OpenAPI documents")
+        elif operation != (entry["method"], entry["path"]):
+            say(
+                f"operation {entry['operation_id']} is {' '.join(operation)}, "
+                f"not {entry['method']} {entry['path']}"
+            )
+    return problems
+
+
+def pinned_sites() -> list[tuple[Path, list[Path]]]:
+    root = Path(str(files("regents_cli.platforms")))
+    return [
+        (folder / "commands.json", sorted(p for p in folder.iterdir() if p.name != "commands.json"))
+        for folder in sorted(root.iterdir())
+        if (folder / "commands.json").is_file()
+    ]
+
+
+def main(args: list[str]) -> int:
+    sites = [(Path(args[0]), [Path(a) for a in args[1:]])] if args else pinned_sites()
+    failed = False
+    for commands, documents in sites:
+        problems = problems_in(
+            read_document(commands), operations_in(list(map(read_document, documents)))
+        )
+        if problems:
+            failed = True
+            print(f"{commands}:\n  " + "\n  ".join(problems), file=sys.stderr)
+        else:
+            print(f"{commands}: ok")
+    if not sites:
+        print("No pinned site describes its commands yet.")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

regents_cli/doctor.py

@@ -0,0 +1,95 @@
+"""`regents <site> doctor`: the same checks for every site, read from its description.
+
+The site answers at all; each public read that needs no input answers; and, for a site with
+wallet-proof commands, the sign-in on this machine is one the sign-in server accepts.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import partial
+from typing import Any
+
+import click
+
+from regents_cli import output, siwa
+from regents_cli.errors import CommandError
+from regents_cli.http import Request, base_address, respond, send
+from regents_cli.platforms import Command, Platform
+
+
+def doctor_command(platform: Platform) -> click.Command:
+    def run(as_json: bool, base_url: str | None, timeout_ms: int) -> None:
+        base = base_address(base_url, platform.env_var, platform.base_url)
+        checks = [check("site answers", lambda: site_answers(base, timeout_ms))]
+        checks += [
+            check(" ".join(c.words), partial(read_answers, base, c, timeout_ms))
+            for c in platform.commands
+            if needs_nothing(c)
+        ]
+        if any(c.authority == "wallet-proof" for c in platform.commands):
+            checks.append(check("sign-in", lambda: sign_in_good(platform.site, timeout_ms)))
+        found: dict[str, Any] = {"site": platform.site, "base_url": base, "checks": checks}
+        failed = sum(not c["ok"] for c in checks)
+        if failed:
+            raise CommandError(
+                "doctor_found_problems", f"{failed} of {len(checks)} checks failed.", **found
+            )
+        output.emit(found, as_json=as_json)
+
+    return click.Command(
+        "doctor",
+        callback=run,
+        params=[
+            click.Option(["--json", "as_json"], is_flag=True, help="Print the answer as JSON."),
+            click.Option(["--base-url"], help=f"The site's address; also {platform.env_var}."),
+            click.Option(
+                ["--timeout-ms"],
+                type=click.IntRange(1, 300_000),
+                default=30_000,
+                show_default=True,
+                help="How long to wait for each answer.",
+            ),
+        ],
+        help="Check that the site answers, that its public reads answer, and that your "
+        "sign-in is good.",
+    )
+
+
+def needs_nothing(command: Command) -> bool:
+    return (
+        command.authority == "public"
+        and command.effect == "read"
+        and command.method == "GET"
+        and not command.arguments
+        and not command.required_one_of
+        and not any(flag.required for flag in command.flags)
+    )
+
+
+def check(name: str, run: Callable[[], str]) -> dict[str, Any]:
+    try:
+        return {"check": name, "ok": True, "detail": run()}
+    except CommandError as error:
+        return {"check": name, "ok": False, "detail": f"{error.code}: {error.message}"}
+
+
+def site_answers(base: str, timeout_ms: int) -> str:
+    response = respond(base, Request("GET", "/", headers={"accept": "*/*"}), timeout_ms)
+    return f"{base} answered {response.status_code}."
+
+
+def read_answers(base: str, command: Command, timeout_ms: int) -> str:
+    send(base, Request(command.method, command.path), timeout_ms)
+    return f"{command.method} {command.path} answered."
+
+
+def sign_in_good(site: str, timeout_ms: int) -> str:
+    sign_in = siwa.current(site, timeout_ms)
+    if not sign_in.local:
+        return (
+            f"Signed in with your own key as {sign_in.wallet_address} until "
+            f"{sign_in.expires_at}; only that key can sign a request to check it further."
+        )
+    siwa.confirm(site, sign_in, timeout_ms)
+    return f"The sign-in server accepts {sign_in.wallet_address} until {sign_in.expires_at}."

regents_cli/errors.py

@@ -0,0 +1,47 @@
+"""Failures and the exit codes every `regents` command shares."""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+EXIT_OK: Final = 0
+EXIT_FAILED: Final = 1
+EXIT_USAGE: Final = 2
+EXIT_AUTH: Final = 3
+EXIT_NOT_FOUND: Final = 4
+EXIT_UNREACHABLE: Final = 5
+EXIT_CANCELLED: Final = 130
+
+EXIT_CODES: Final = {
+    EXIT_OK: "Success.",
+    EXIT_FAILED: "The command ran but the operation failed.",
+    EXIT_USAGE: "Usage error: unknown command, missing argument, or invalid flag value.",
+    EXIT_AUTH: "Sign-in or wallet proof is missing, expired, or rejected.",
+    EXIT_NOT_FOUND: "The requested record was not found.",
+    EXIT_UNREACHABLE: "The site could not be reached, or did not answer in time.",
+    EXIT_CANCELLED: "The command was interrupted.",
+}
+
+
+class CommandError(Exception):
+    """A failure reported as {"error": {"code", "message", ...}} with its exit code.
+
+    Extra fields travel into the error object; never put a secret in them.
+    """
+
+    def __init__(
+        self, code: str, message: str, *, exit_code: int = EXIT_FAILED, **fields: Any
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.exit_code = exit_code
+        self.fields = fields
+
+    def as_json(self) -> dict[str, Any]:
+        return {"error": {"code": self.code, "message": self.message, **self.fields}}
+
+
+class UsageError(CommandError):
+    def __init__(self, message: str) -> None:
+        super().__init__("usage_error", message, exit_code=EXIT_USAGE)