reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/workbench/cli/automation.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Sequence
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from typing import Any, Protocol, cast
+
+import click
+
+SCHEMA = "reader.cli/v1"
+_DEFAULT_META = {"projection": "full", "truncated": False, "continuation": None}
+
+
+@dataclass(frozen=True)
+class AutomationRequest:
+    json_requested: bool
+    command: str
+
+
+_REQUEST: ContextVar[AutomationRequest | None] = ContextVar("reader_cli_automation_request", default=None)
+_DOCUMENT_EMITTED: ContextVar[bool] = ContextVar("reader_cli_json_document_emitted", default=False)
+
+
+class ClickError(Protocol):
+    """The stable behavior Reader needs from a Click-compatible usage error."""
+
+    exit_code: int
+
+    def format_message(self) -> str: ...
+
+    def show(self) -> None: ...
+
+
+def request_from_argv(argv: Sequence[str]) -> AutomationRequest:
+    args = list(argv)
+    json_requested = any(
+        (item == "--format" and index + 1 < len(args) and args[index + 1].strip().lower() == "json")
+        or item.strip().lower() == "--format=json"
+        for index, item in enumerate(args)
+    )
+    positional = [item for item in args if item and not item.startswith("-")]
+    command = positional[0] if positional else "reader"
+    return AutomationRequest(json_requested=json_requested, command=command)
+
+
+def begin_request(argv: Sequence[str]) -> tuple[Token, Token]:
+    request_token = _REQUEST.set(request_from_argv(argv))
+    emitted_token = _DOCUMENT_EMITTED.set(False)
+    return request_token, emitted_token
+
+
+def end_request(tokens: tuple[Token, Token]) -> None:
+    request_token, emitted_token = tokens
+    _DOCUMENT_EMITTED.reset(emitted_token)
+    _REQUEST.reset(request_token)
+
+
+def _click_context() -> click.Context | None:
+    try:
+        return click.get_current_context(silent=True)
+    except RuntimeError:
+        return None
+
+
+def json_requested() -> bool:
+    request = _REQUEST.get()
+    if request is not None:
+        return request.json_requested
+    context = _click_context()
+    while context is not None:
+        value = context.params.get("format")
+        if isinstance(value, str) and value.strip().lower() == "json":
+            return True
+        context = context.parent
+    return request_from_argv(sys.argv[1:]).json_requested
+
+
+def command_name() -> str:
+    context = _click_context()
+    if context is not None:
+        parts = context.command_path.split()
+        if len(parts) > 1:
+            return " ".join(parts[1:])
+        if context.info_name:
+            return context.info_name
+    request = _REQUEST.get()
+    if request is not None:
+        return request.command
+    return request_from_argv(sys.argv[1:]).command
+
+
+def success_envelope(
+    data: object,
+    *,
+    command: str | None = None,
+    projection: str = "full",
+    truncated: bool = False,
+    continuation: str | None = None,
+) -> dict[str, object]:
+    return {
+        "schema": SCHEMA,
+        "ok": True,
+        "command": command or command_name(),
+        "data": data,
+        "error": None,
+        "meta": {
+            "projection": projection,
+            "truncated": truncated,
+            "continuation": continuation,
+        },
+    }
+
+
+def error_envelope(
+    *,
+    code: str,
+    field: str,
+    reason: str,
+    remediation: str,
+    retryable: bool,
+    command: str | None = None,
+) -> dict[str, object]:
+    return {
+        "schema": SCHEMA,
+        "ok": False,
+        "command": command or command_name(),
+        "data": None,
+        "error": {
+            "code": code,
+            "field": field,
+            "reason": reason,
+            "remediation": remediation,
+            "retryable": retryable,
+        },
+        "meta": dict(_DEFAULT_META),
+    }
+
+
+def emit_document(payload: dict[str, object]) -> None:
+    managed_request = _REQUEST.get() is not None
+    if managed_request and _DOCUMENT_EMITTED.get():
+        return
+    click.echo(json.dumps(payload, indent=2, sort_keys=True), err=False)
+    if managed_request:
+        _DOCUMENT_EMITTED.set(True)
+
+
+def _has_typer_click_base(exc: Exception, name: str) -> bool:
+    return any(base.__name__ == name and base.__module__.partition(".")[0] == "typer" for base in type(exc).__mro__)
+
+
+def as_click_error(exc: Exception) -> ClickError | None:
+    """Adapt external Click and Typer-owned Click errors at the CLI boundary.
+
+    Newer Typer releases may own their Click implementation, so exception class
+    identity is not guaranteed to match the separately installed ``click``
+    package. Reader depends only on the public usage-error behavior here and
+    does not import Typer's private compatibility modules.
+    """
+
+    if not isinstance(exc, click.ClickException) and not _has_typer_click_base(exc, "ClickException"):
+        return None
+    if type(getattr(exc, "exit_code", None)) is not int:
+        return None
+    if not callable(getattr(exc, "format_message", None)) or not callable(getattr(exc, "show", None)):
+        return None
+    return cast(ClickError, exc)
+
+
+def _bad_parameter_field(exc: ClickError) -> str:
+    param = getattr(exc, "param", None)
+    if param is not None and getattr(param, "name", None):
+        return str(param.name)
+    param_hint = getattr(exc, "param_hint", None)
+    if param_hint:
+        hint = param_hint[0] if isinstance(param_hint, tuple) else param_hint
+        return str(hint).lstrip("-").replace("-", "_")
+    reason = str(exc).lower()
+    if "experiment" in reason and "root" in reason:
+        return "root"
+    if "protocol" in reason:
+        return "name"
+    if "log level" in reason:
+        return "log_level"
+    if "format" in reason:
+        return "format"
+    if "section" in reason:
+        return "section"
+    if "continuation" in reason:
+        return "continuation"
+    if "limit" in reason:
+        return "limit"
+    return "parameter"
+
+
+def click_error_details(exc: ClickError) -> dict[str, Any]:
+    if isinstance(exc, click.BadParameter) or (
+        isinstance(exc, Exception) and _has_typer_click_base(exc, "BadParameter")
+    ):
+        field = _bad_parameter_field(exc)
+        return {
+            "code": "invalid_parameter",
+            "field": field,
+            "reason": exc.format_message(),
+            "remediation": f"Correct '{field}' and retry the command.",
+            "retryable": False,
+        }
+    return {
+        "code": "usage_error",
+        "field": "arguments",
+        "reason": exc.format_message(),
+        "remediation": "Correct the command arguments and retry. Use --help to inspect the accepted interface.",
+        "retryable": False,
+    }
+
+
+def reader_error_details(exc: Exception) -> dict[str, Any]:
+    reason = str(exc)
+    lowered = reason.lower()
+    field = "log_level" if "log level" in lowered else "experiment"
+    return {
+        "code": "reader_error",
+        "field": field,
+        "reason": reason,
+        "remediation": "Correct the reported Reader input or state, then retry the command.",
+        "retryable": False,
+    }

reader_workbench/workbench/cli/demo.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from rich import box
+from rich.panel import Panel
+
+from . import shared
+from .shared import app, table
+
+
+@app.command(help="Show a quick guided walkthrough.")
+def demo():
+    steps = [
+        ("1", "Find experiments", "reader ls --details --readiness"),
+        ("2", "Show experiment details", "reader inspect ./experiments/<experiment>/config.yaml"),
+        ("3", "List protocols", "reader protocols"),
+        (
+            "4",
+            "Scaffold a new experiment",
+            "reader init ./experiments/my_experiment --protocol <protocol-id>",
+        ),
+        ("5", "Starter YAML for a protocol", "reader protocols <protocol-id> --example-config"),
+        ("6", "Show pipeline chain", "reader steps ./experiments/<experiment>/config.yaml"),
+        ("7", "Explain plan", "reader explain ./experiments/<experiment>/config.yaml"),
+        ("8", "Validate config + inputs", "reader validate ./experiments/<experiment>/config.yaml"),
+        ("9", "Run pipeline (records)", "reader run ./experiments/<experiment>/config.yaml"),
+        ("10", "See records", "reader records ./experiments/<experiment>/config.yaml"),
+        ("11", "List plot specs", "reader plot ./experiments/<experiment>/config.yaml --list"),
+        ("12", "Save plots", "reader plot ./experiments/<experiment>/config.yaml"),
+        ("13", "Run exports", "reader export ./experiments/<experiment>/config.yaml"),
+        ("14", "Notebook (Marimo)", "reader notebook ./experiments/<experiment>/config.yaml"),
+        ("15", "Verify records and provenance", "reader verify ./experiments/<experiment>/config.yaml"),
+    ]
+    listing = table("Reader Demo")
+    listing.add_column("#", justify="right", style="muted")
+    listing.add_column("Goal", style="accent")
+    listing.add_column("Command", style="path")
+    for row in steps:
+        listing.add_row(*row)
+    shared.console.print(
+        Panel(
+            listing,
+            border_style="accent",
+            box=box.ROUNDED,
+            subtitle="[muted]Tip: replace the index with a path or experiment directory[/muted]",
+        )
+    )

reader_workbench/workbench/cli/dop.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import typer
+from rich import box
+from rich.panel import Panel
+
+from reader_workbench.errors import ConfigError
+
+from . import shared
+from ._lazy import load as _load
+from .shared import app, emit_json, normalize_output_format
+
+dop_app = typer.Typer(
+    add_completion=False,
+    help="Inspect the reader-local Data Operations Plan registry.",
+)
+
+
+def _registry():
+    return _load("reader_workbench.workbench.dop").builtin_dop_registry()
+
+
+def _validate_registry_protocol_refs(registry, runtime) -> None:
+    registry.validate_protocol_refs(descriptor.protocol for descriptor in runtime.protocols.all())
+
+
+@dop_app.command("classes", help="List DOP data classes and their reader protocol candidates.")
+def data_classes(
+    name: str | None = typer.Argument(None, metavar="[DATA_CLASS]", help="Optional DOP data class id to describe."),
+    protocol: str | None = typer.Option(
+        None,
+        "--protocol",
+        metavar="ID",
+        help="Only show data classes that include the given reader protocol id.",
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        metavar="FMT",
+        help="Output format: table | json (default: table).",
+    ),
+):
+    registry = _registry()
+    runtime = _load("reader_workbench.runtime").builtin_runtime()
+    inspection_dop = _load("reader_workbench.workbench.inspection.dop")
+    fmt = normalize_output_format(format)
+    try:
+        _validate_registry_protocol_refs(registry, runtime)
+        selected = registry.data_classes()
+        if name is not None:
+            selected = (registry.data_class(name),)
+        if protocol is not None and protocol.strip():
+            resolved_protocol = runtime.protocols.resolve(protocol.strip()).protocol
+            selected = tuple(item for item in selected if resolved_protocol in item.protocol_candidates)
+    except (ConfigError, ValueError) as err:
+        raise typer.BadParameter(str(err)) from err
+    if fmt == "json":
+        emit_json(inspection_dop.data_classes_payload(selected))
+        return
+    shared.console.print(Panel(inspection_dop.data_classes_table(selected), border_style="accent", box=box.ROUNDED))
+
+
+@dop_app.command("ready-specs", help="List DOP readiness gates and their reader evidence requirements.")
+def ready_specs(
+    name: str | None = typer.Argument(None, metavar="[READY_SPEC]", help="Optional DOP ready spec id to describe."),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        metavar="FMT",
+        help="Output format: table | json (default: table).",
+    ),
+):
+    registry = _registry()
+    inspection_dop = _load("reader_workbench.workbench.inspection.dop")
+    readiness = _load("reader_workbench.workbench.inspection.readiness")
+    fmt = normalize_output_format(format)
+    try:
+        registry.validate_ready_refs(
+            readiness_states=readiness.READINESS_STATES,
+            capability_keys=readiness.READINESS_CAPABILITY_KEYS,
+        )
+        selected = registry.ready_specs() if name is None else (registry.ready_spec(name),)
+    except ValueError as err:
+        raise typer.BadParameter(str(err)) from err
+    if fmt == "json":
+        emit_json(inspection_dop.ready_specs_payload(selected))
+        return
+    shared.console.print(Panel(inspection_dop.ready_specs_table(selected), border_style="accent", box=box.ROUNDED))
+
+
+app.add_typer(dop_app, name="dop")