ynab-api-cli 0.1.0__py3-none-any.whl

ynab_api_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Contract-driven YNAB REST CLI and generated typed Python client."""
+
+from __future__ import annotations

ynab_api_cli/__main__.py

@@ -0,0 +1,266 @@
+"""CLI orchestration with safe diagnostics and explicit mutation execution."""
+
+from __future__ import annotations
+
+import getpass
+import json
+import logging
+import shutil
+import sys
+from collections.abc import Callable, Sequence
+from importlib.resources import files
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from ynab_api_cli.cli import Command, CommandLine
+from ynab_api_cli.compat import Compatibility
+from ynab_api_cli.config import ConfigStore
+from ynab_api_cli.contract import Contract
+from ynab_api_cli.exceptions import AppError
+from ynab_api_cli.generated.bindings import Bindings
+from ynab_api_cli.transport import Transport
+from ynab_api_cli.types import JsonCodec, JsonValue, RequestValues
+
+logger = logging.getLogger(__name__)
+
+
+class Application:
+    """Coordinate connection setup and reviewed typed operation dispatch."""
+
+    def __init__(
+        self, store: ConfigStore | None = None, transport: Transport | None = None
+    ) -> None:
+        self.contract = Contract()
+        self.store = store
+        self.transport = transport
+
+    @classmethod
+    def main(cls, argv: Sequence[str] | None = None) -> None:
+        """Run the console entry point and return its documented exit status."""
+        sys.exit(cls().run(argv))
+
+    def run(self, argv: Sequence[str] | None = None) -> int:
+        """Produce JSON output and omit traceback chains containing secrets."""
+        try:
+            command = CommandLine(self.contract).parse(argv)
+            logging.basicConfig(
+                level=command.log_level, format="%(levelname)s: %(message)s"
+            )
+            output = self.dispatch(command)
+            sys.stdout.write(
+                json.dumps(output, indent=2, ensure_ascii=False, allow_nan=False) + "\n"
+            )
+            if isinstance(output, dict) and output.get("compatible") is False:
+                return 1
+        except (AppError, OSError) as err:
+            logger.error(  # noqa: TRY400 - never expose credential-bearing tracebacks.
+                "%s",
+                str(err)
+                if isinstance(err, AppError)
+                else "Filesystem operation failed.",
+            )
+            return 1
+        except ValidationError:
+            logger.error("Generated model validation failed; check compatibility.")  # noqa: TRY400 - omit request values.
+            return 1
+        except KeyboardInterrupt:
+            return 130
+        return 0
+
+    def dispatch(self, command: Command) -> JsonValue:
+        """Route non-network discovery and authenticated commands."""
+        routes: dict[str, Callable[[Command], JsonValue]] = {
+            "discover": self.discover,
+            "inspect": self.inspect,
+            "compat": self.compatibility,
+            "skill": self.skill,
+        }
+        if command.name in routes:
+            return routes[command.name](command)
+        store = self.store if self.store is not None else ConfigStore()
+        if command.name in {"configure", "select-plan"}:
+            return self.configure(command, store)
+        connection = store.load()
+        transport = (
+            self.transport
+            if self.transport is not None
+            else Transport(connection, self.contract)
+        )
+        if command.name == "doctor":
+            return self.doctor(command, transport, store)
+        return self.execute(command, transport)
+
+    def execute(self, command: Command, transport: Transport) -> JsonValue:
+        """Validate and preview or submit one reviewed operation."""
+        connection = transport.connection
+        operation = self.contract.get(command.operation or "")
+        request = self.request(command)
+        path = dict(request.path)
+        if (
+            "{plan_id}" in operation.path
+            and "plan_id" not in path
+            and connection.plan_id is not None
+        ):
+            path["plan_id"] = connection.plan_id
+        request = RequestValues(path, request.query, request.body)
+        self.contract.validate_request(operation, request)
+        if operation.write and not command.execute:
+            return {
+                "preview": True,
+                "operation": operation.identifier,
+                "method": operation.method,
+                "path": operation.path,
+                "request": request.json(),
+            }
+        response = Bindings.operations[operation.alias](transport, request)
+        if command.metadata:
+            return {
+                "status": response.status,
+                "headers": JsonCodec.encode(response.headers),
+                "contract_version": self.contract.version,
+                "body": response.raw,
+            }
+        return response.raw
+
+    def discover(self, command: Command) -> JsonValue:
+        """List the reviewed contract groups and matching operations."""
+        groups = {op.group for op in self.contract.operations.values()}
+        if command.group is not None and command.group not in groups:
+            raise AppError("Unknown resource group.")
+        return JsonCodec.encode(
+            {
+                "contract_version": self.contract.version,
+                "groups": sorted(groups),
+                "operations": [
+                    op.identifier
+                    for op in self.contract.operations.values()
+                    if op.identifier in self.contract.catalog
+                    and (command.group is None or op.group == command.group)
+                ],
+            }
+        )
+
+    def inspect(self, command: Command) -> JsonValue:
+        """Return the operation and only its reachable schemas."""
+        operation = self.contract.get(command.operation or "")
+        return {
+            "operation": operation.identifier,
+            "method": operation.method,
+            "path": operation.path,
+            "write": operation.write,
+            "definition": operation.definition,
+            "components": self.reachable(operation.definition),
+        }
+
+    def compatibility(self, _command: Command) -> JsonValue:
+        """Check the public upstream definition without credentials."""
+        checker = Compatibility(self.contract)
+        return checker.compare(checker.fetch())
+
+    @staticmethod
+    def configure(command: Command, store: ConfigStore) -> JsonValue:
+        """Perform only the explicitly selected local configuration action."""
+        if command.name == "select-plan":
+            store.select_plan(command.plan or "")
+            return {"plan_id": command.plan}
+        if not sys.stdin.isatty():
+            raise AppError("Run configure in an interactive terminal for hidden input.")
+        store.configure(
+            getpass.getpass("YNAB personal access token (hidden): "),
+            replace=command.replace,
+        )
+        return {"configured": True, "directory": str(store.root)}
+
+    def doctor(
+        self, command: Command, transport: Transport, store: ConfigStore
+    ) -> dict[str, JsonValue]:
+        """Validate API access separately from offline configuration checks."""
+        if not command.offline:
+            Bindings.operations["get_user"](transport, RequestValues())
+            if transport.connection.plan_id is not None:
+                Bindings.operations["get_plan_by_id"](
+                    transport, RequestValues({"plan_id": transport.connection.plan_id})
+                )
+        output: dict[str, JsonValue] = {
+            "ok": True,
+            "api_checked": not command.offline,
+            "directory": str(store.root),
+            "plan_id": transport.connection.plan_id,
+            "contract_version": self.contract.version,
+        }
+        if command.upstream:
+            checker = Compatibility(self.contract)
+            report = checker.compare(checker.fetch())
+            output["upstream"] = report
+            output["compatible"] = report["compatible"]
+        return output
+
+    def request(self, command: Command) -> RequestValues:
+        """Read the uniform envelope or a resource command's body."""
+        if command.source is None:
+            return command.arguments
+        text = command.source
+        if text.startswith("@"):
+            text = Path(text[1:]).read_text(encoding="utf-8")
+        elif text == "-":
+            text = sys.stdin.read()
+        try:
+            raw = JsonCodec.loads(text)
+        except ValueError as err:
+            raise AppError("Invalid request JSON.") from err
+        if command.name != "call":
+            return RequestValues(command.arguments.path, command.arguments.query, raw)
+        envelope = self.contract.object(raw)
+        if set(envelope) - {"path", "query", "body"}:
+            raise AppError("Request accepts only path, query, and body fields.")
+        base = RequestValues(
+            dict(self.contract.object(envelope.get("path", {}))),
+            dict(self.contract.object(envelope.get("query", {}))),
+        )
+        return (
+            RequestValues(base.path, base.query, envelope["body"])
+            if "body" in envelope
+            else base
+        )
+
+    def reachable(self, definition: JsonValue) -> dict[str, JsonValue]:
+        """Disclose only schemas reachable from the inspected operation."""
+        selected: dict[str, JsonValue] = {}
+        pending = [definition]
+        schemas = self.contract.object(
+            self.contract.object(self.contract.document["components"])["schemas"]
+        )
+        while pending:
+            value = pending.pop()
+            if isinstance(value, dict):
+                reference = value.get("$ref")
+                if isinstance(reference, str) and reference.startswith(
+                    "#/components/schemas/"
+                ):
+                    name = reference.rsplit("/", 1)[-1]
+                    if name not in selected:
+                        selected[name] = schemas[name]
+                        pending.append(schemas[name])
+                pending.extend(value.values())
+            elif isinstance(value, list):
+                pending.extend(value)
+        return selected
+
+    @staticmethod
+    def skill(command: Command) -> JsonValue:
+        """Display or export the skill supplied by the installed distribution."""
+        resource = files("ynab_api_cli.resources").joinpath("skill")
+        if command.operation == "show":
+            return {"skill": resource.joinpath("SKILL.md").read_text(encoding="utf-8")}
+        if command.source is None:
+            raise AppError("skill export requires a destination directory.")
+        destination = Path(command.source)
+        if destination.exists():
+            raise AppError("Skill export destination already exists.")
+        shutil.copytree(str(resource), destination)
+        return {"exported": str(destination)}
+
+
+if __name__ == "__main__":
+    Application.main()

ynab_api_cli/cli.py

@@ -0,0 +1,171 @@
+"""Contract-derived argument parsing into immutable command settings."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from ynab_api_cli.contract import Contract
+from ynab_api_cli.types import RequestValues
+
+
+@dataclass(frozen=True, slots=True)
+class Command:
+    """Typed command input separated from argparse's dynamic namespace."""
+
+    name: str
+    operation: str | None
+    group: str | None
+    plan: str | None
+    source: str | None
+    arguments: RequestValues
+    execute: bool
+    metadata: bool
+    offline: bool
+    upstream: bool
+    replace: bool
+    log_level: str
+
+
+class CommandLine:
+    """Expose every reviewed endpoint with useful resource-specific flags."""
+
+    def __init__(self, contract: Contract) -> None:
+        self.contract = contract
+
+    def parser(self) -> argparse.ArgumentParser:
+        """Build connection, discovery, uniform, and resource subcommands."""
+        parser = argparse.ArgumentParser(
+            prog="ynab-api-cli", description="Complete reviewed YNAB REST API CLI"
+        )
+        parser.add_argument(
+            "--log-level", choices=["ERROR", "WARNING", "INFO"], default="WARNING"
+        )
+        sub = parser.add_subparsers(dest="command", required=True)
+        configure = sub.add_parser(
+            "configure", help="Prompt locally for protected credentials"
+        )
+        configure.add_argument("--replace", action="store_true")
+        doctor = sub.add_parser(
+            "doctor", help="Validate local settings and read-only API access"
+        )
+        doctor.add_argument("--offline", action="store_true")
+        doctor.add_argument("--upstream", action="store_true")
+        select = sub.add_parser("select-plan")
+        select.add_argument("plan")
+        discover = sub.add_parser("discover")
+        discover.add_argument("group", nargs="?")
+        describe = sub.add_parser("inspect")
+        describe.add_argument("operation")
+        call = sub.add_parser("call")
+        call.add_argument("operation")
+        call.add_argument(
+            "--request",
+            dest="source",
+            default="{}",
+            help="JSON envelope, @file, or - for stdin",
+        )
+        self.execution_flags(call)
+        compat = sub.add_parser("compat")
+        compat.add_argument("action", choices=["check"])
+        skill = sub.add_parser(
+            "skill", help="Inspect or export the bundled supplementary skill"
+        )
+        skill.add_argument("action", choices=["show", "export"])
+        skill.add_argument("destination", nargs="?")
+        groups = {
+            group: sub.add_parser(group).add_subparsers(dest="operation", required=True)
+            for group in sorted(
+                {
+                    op.group
+                    for op in self.contract.operations.values()
+                    if op.identifier in self.contract.catalog
+                }
+            )
+        }
+        for operation in self.contract.operations.values():
+            if operation.identifier not in self.contract.catalog:
+                continue
+            endpoint = groups[operation.group].add_parser(
+                operation.alias.replace("_", "-"),
+                help=str(operation.definition.get("summary", "")),
+            )
+            endpoint.set_defaults(operation=operation.identifier)
+            for parameter in self.contract.parameters(operation):
+                endpoint.add_argument(
+                    "--" + str(parameter["name"]).replace("_", "-"),
+                    dest="argument_" + str(parameter["name"]),
+                    required=bool(parameter.get("required"))
+                    and parameter["name"] != "plan_id",
+                    help=str(parameter.get("description", "")),
+                )
+            if operation.definition.get("requestBody") is not None:
+                endpoint.add_argument(
+                    "--body",
+                    dest="source",
+                    required=True,
+                    help="JSON object, @file, or - for stdin",
+                )
+            self.execution_flags(endpoint)
+        return parser
+
+    @staticmethod
+    def execution_flags(parser: argparse.ArgumentParser) -> None:
+        """Add mutation guards and optional HTTP metadata."""
+        parser.add_argument(
+            "--execute", action="store_true", help="Submit an authorized mutation"
+        )
+        parser.add_argument("--metadata", action="store_true")
+
+    def parse(self, argv: Sequence[str] | None = None) -> Command:
+        """Convert the namespace and endpoint flags into immutable settings."""
+        parser = self.parser()
+        args = parser.parse_args(argv)
+        name = str(args.command)
+        operation = getattr(args, "operation", None)
+        path: dict[str, object] = {}
+        query: dict[str, object] = {}
+        if operation is not None and name not in {"inspect", "call"}:
+            for parameter in self.contract.parameters(self.contract.get(operation)):
+                raw = getattr(args, "argument_" + str(parameter["name"]), None)
+                if raw is not None:
+                    schema = self.contract.object(parameter["schema"])
+                    value = self.convert(
+                        str(raw), str(schema.get("type", "string")), parser
+                    )
+                    (path if parameter["in"] == "path" else query)[
+                        str(parameter["name"])
+                    ] = value
+        source = getattr(args, "source", None)
+        if name == "skill":
+            operation = str(args.action)
+            source = getattr(args, "destination", None)
+        return Command(
+            name,
+            operation,
+            getattr(args, "group", None),
+            getattr(args, "plan", None),
+            source,
+            RequestValues(path, query),
+            bool(getattr(args, "execute", False)),
+            bool(getattr(args, "metadata", False)),
+            bool(getattr(args, "offline", False)),
+            bool(getattr(args, "upstream", False)),
+            bool(getattr(args, "replace", False)),
+            str(args.log_level),
+        )
+
+    @staticmethod
+    def convert(text: str, kind: str, parser: argparse.ArgumentParser) -> object:
+        """Decode CLI primitive types without treating false as truthy."""
+        if kind == "boolean":
+            if text not in {"true", "false"}:
+                parser.error("Boolean values must be true or false.")
+            return text == "true"
+        if kind == "integer":
+            try:
+                return int(text)
+            except ValueError:
+                parser.error("Integer argument required.")
+        return text

ynab_api_cli/compat.py

@@ -0,0 +1,120 @@
+"""Compare bundled and upstream contracts without modifying installed files."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+import httpx
+import yaml
+
+from ynab_api_cli.contract import Contract
+from ynab_api_cli.exceptions import AppError
+from ynab_api_cli.types import JsonCodec, JsonValue
+
+
+class Compatibility:
+    """Detect additions, removals, and structural contract changes."""
+
+    URL = "https://api.ynab.com/papi/open_api_spec.yaml"
+    DOCUMENTATION_KEYS = frozenset(
+        {"description", "summary", "example", "examples", "externalDocs"}
+    )
+
+    def __init__(self, contract: Contract | None = None) -> None:
+        self.contract = contract if contract is not None else Contract()
+
+    @classmethod
+    def structural(cls, value: JsonValue) -> JsonValue:
+        """Strip documentation while retaining API validation and wire semantics."""
+        if isinstance(value, dict):
+            return {
+                key: cls.structural(item)
+                for key, item in value.items()
+                if key not in cls.DOCUMENTATION_KEYS
+            }
+        if isinstance(value, list):
+            return [cls.structural(item) for item in value]
+        return value
+
+    def compare(self, latest: dict[str, JsonValue]) -> dict[str, JsonValue]:
+        """Report semantic paths and operation changes, including optional additions."""
+        upstream = Contract(latest)
+        baseline = self.contract.operations
+        added = sorted(set(upstream.operations) - set(baseline))
+        removed = sorted(set(baseline) - set(upstream.operations))
+        changed = [
+            name
+            for name in sorted(set(baseline) & set(upstream.operations))
+            if self.structural(baseline[name].definition)
+            != self.structural(upstream.operations[name].definition)
+            or baseline[name].path != upstream.operations[name].path
+            or baseline[name].method != upstream.operations[name].method
+        ]
+        schema_changes = self.differences(
+            self.structural(self.contract.document["components"]),
+            self.structural(latest["components"]),
+            "/components",
+        )
+        server_changes = self.contract.document.get("servers") != latest.get("servers")
+        compatible = not (
+            added or removed or changed or schema_changes or server_changes
+        )
+        affected = sorted(
+            set(changed)
+            | set(removed)
+            | (set(baseline) if schema_changes or server_changes else set())
+        )
+        output: dict[str, JsonValue] = {
+            "compatible": compatible,
+            "baseline_version": self.contract.version,
+            "upstream_version": upstream.version,
+            "added": JsonCodec.encode(added),
+            "removed": JsonCodec.encode(removed),
+            "changed": JsonCodec.encode(changed),
+            "schema_changes": JsonCodec.encode(schema_changes),
+            "server_changed": server_changes,
+            "affected_commands": JsonCodec.encode(affected),
+            "missing_tests": JsonCodec.encode(added),
+            "documentation_only": compatible and self.contract.document != latest,
+        }
+        return output
+
+    @classmethod
+    def differences(cls, old: JsonValue, new: JsonValue, path: str) -> list[str]:
+        """Find changed schema paths without relying on version strings."""
+        if isinstance(old, dict) and isinstance(new, dict):
+            result: list[str] = []
+            for key in sorted(set(old) | set(new)):
+                pointer = path + "/" + key.replace("~", "~0").replace("/", "~1")
+                result.extend(
+                    [pointer]
+                    if key not in old or key not in new
+                    else cls.differences(old[key], new[key], pointer)
+                )
+            return result
+        return [] if old == new else [path]
+
+    def fetch(self, client: httpx.Client | None = None) -> dict[str, JsonValue]:
+        """Fetch the official YAML using bounded credential-free HTTPS."""
+        try:
+            if client is None:
+                with httpx.Client(
+                    verify=True, follow_redirects=False, timeout=30, trust_env=False
+                ) as session:
+                    response = session.get(self.URL)
+            else:
+                response = client.get(self.URL, timeout=30, follow_redirects=False)
+            response.raise_for_status()
+            return Contract.object(JsonCodec.encode(yaml.safe_load(response.text)))
+        except (httpx.HTTPError, yaml.YAMLError, ValueError) as err:
+            raise AppError(
+                "Cannot fetch or parse the public upstream contract."
+            ) from err
+
+    @staticmethod
+    def digest(value: dict[str, JsonValue]) -> str:
+        """Hash a canonical contract document for provenance checks."""
+        return hashlib.sha256(
+            json.dumps(value, sort_keys=True).encode("utf-8")
+        ).hexdigest()

ynab_api_cli/config.py

@@ -0,0 +1,110 @@
+"""Atomic connection configuration in XDG-style directories."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from uuid import UUID
+
+from ynab_api_cli.contract import Contract
+from ynab_api_cli.exceptions import AppError
+from ynab_api_cli.security import FileSecurity
+from ynab_api_cli.transport import Connection
+from ynab_api_cli.types import JsonCodec, JsonValue
+
+
+class ConfigStore:
+    """Keep credentials separate from non-secret default settings."""
+
+    def __init__(
+        self, root: Path | None = None, security: FileSecurity | None = None
+    ) -> None:
+        base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+        if root is None and not base.is_absolute():
+            raise AppError("XDG_CONFIG_HOME must be absolute.")
+        self.root = root if root is not None else base / "ynab-api-cli"
+        self.security = security if security is not None else FileSecurity()
+
+    @staticmethod
+    def read(path: Path) -> dict[str, JsonValue]:
+        """Read a JSON object without reporting credential file contents."""
+        try:
+            return Contract.object(JsonCodec.loads(path.read_text(encoding="utf-8")))
+        except (OSError, ValueError) as err:
+            raise AppError(f"Cannot read JSON configuration: {path.name}.") from err
+
+    def write(
+        self,
+        path: Path,
+        values: dict[str, JsonValue],
+        *,
+        secret: bool = False,
+        exclusive: bool = False,
+    ) -> None:
+        """Replace a JSON file atomically after securing its temporary file."""
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        descriptor, temporary = tempfile.mkstemp(dir=self.root, prefix=".ynab-api-cli-")
+        temporary_path = Path(temporary)
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+                stream.write(json.dumps(values, indent=2) + "\n")
+                stream.flush()
+                os.fsync(stream.fileno())
+            if secret:
+                self.security.protect(temporary_path)
+            if exclusive:
+                os.link(temporary_path, path)
+            else:
+                temporary_path.replace(path)
+        except OSError as err:
+            raise AppError("Cannot write configuration atomically.") from err
+        finally:
+            temporary_path.unlink(missing_ok=True)
+
+    def configure(self, token: str, *, replace: bool = False) -> None:
+        """Create or explicitly replace protected credentials."""
+        if not token.strip() or any(character.isspace() for character in token.strip()):
+            raise AppError("Token must be nonempty and contain no whitespace.")
+        Connection(token.strip())
+        path = self.root / "auth.json"
+        if path.exists() and not replace:
+            raise AppError(
+                "Credentials already exist; use configure --replace to rotate."
+            )
+        previous = self.read(path) if path.exists() else {}
+        previous["access_token"] = token.strip()
+        self.write(path, previous, secret=True, exclusive=not replace)
+
+    def load(self) -> Connection:
+        """Validate permissions, credentials, and optional default plan."""
+        path = self.root / "auth.json"
+        if not path.is_file():
+            raise AppError("Missing auth.json; run configure in a local terminal.")
+        self.security.validate(path)
+        token = self.read(path).get("access_token")
+        if (
+            not isinstance(token, str)
+            or not token.strip()
+            or any(character.isspace() for character in token)
+        ):
+            raise AppError(
+                "auth.json requires a nonempty access_token without whitespace."
+            )
+        config = self.root / "config.json"
+        plan = self.read(config).get("plan_id") if config.exists() else None
+        if plan is not None and (not isinstance(plan, str) or not plan):
+            raise AppError("config.json plan_id must be a nonempty string.")
+        return Connection(token, plan)
+
+    def select_plan(self, plan: str) -> None:
+        """Store an explicit UUID without overwriting unrelated settings."""
+        try:
+            UUID(plan)
+        except ValueError as err:
+            raise AppError("Select an explicit plan UUID.") from err
+        path = self.root / "config.json"
+        values = self.read(path) if path.exists() else {}
+        values["plan_id"] = plan
+        self.write(path, values)