reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/workbench/cli/helpers.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+
+from reader_workbench.errors import RecordError
+from reader_workbench.workbench.commands import reader_command
+from reader_workbench.workbench.experiments import discover_experiment_configs
+
+from ._lazy import load as _load
+
+if TYPE_CHECKING:
+    from reader_workbench.runtime import ReaderRuntime
+    from reader_workbench.workbench.config import ReaderSpec
+    from reader_workbench.workbench.decl import WorkbenchDecl
+
+
+def load_job_models(job_path: Path, *, runtime: ReaderRuntime | None = None) -> tuple[ReaderSpec, WorkbenchDecl]:
+    runtime = runtime or _load("reader_workbench.runtime").builtin_runtime()
+    spec = _load("reader_workbench.workbench.config").ReaderSpec.load(job_path)
+    return spec, _load("reader_workbench.workbench.decl").build_workbench_decl(
+        spec, source_path=job_path, protocols=runtime.protocols
+    )
+
+
+def bind_decl_protocol(*, decl: WorkbenchDecl, runtime: ReaderRuntime):
+    return runtime.bind_protocol(decl.experiment_semantics.protocol)
+
+
+def default_notebook_name() -> str:
+    return f"EDA_{datetime.now().strftime('%Y%m%d')}.py"
+
+
+def next_available_path(path: Path) -> Path:
+    if not path.exists():
+        return path
+    stem = path.stem
+    suffix = path.suffix
+    counter = 1
+    while True:
+        candidate = path.with_name(f"{stem}_{counter}{suffix}")
+        if not candidate.exists():
+            return candidate
+        counter += 1
+
+
+def find_nearest_experiments_dir(start: Path) -> Path:
+    for base in [start] + list(start.parents):
+        candidate = base / "experiments"
+        if candidate.exists() and candidate.is_dir():
+            return candidate.resolve()
+    return (start / "experiments").resolve()
+
+
+def find_jobs(root: Path, *, include_scaffolds: bool = False) -> list[Path]:
+    return discover_experiment_configs(root, include_scaffolds=include_scaffolds)
+
+
+def indexed_jobs(root: Path, *, include_scaffolds: bool = False) -> list[tuple[int, Path]]:
+    all_jobs = find_jobs(root, include_scaffolds=True)
+    if include_scaffolds:
+        return list(enumerate(all_jobs, 1))
+    visible_jobs = set(find_jobs(root, include_scaffolds=False))
+    return [(idx, job) for idx, job in enumerate(all_jobs, 1) if job in visible_jobs]
+
+
+def find_year_jobs(year: str, root: Path) -> list[Path]:
+    year_str = str(year).strip()
+    if not year_str:
+        raise typer.BadParameter("--year cannot be empty")
+    if not year_str.isdigit() or len(year_str) != 4:
+        raise typer.BadParameter("--year expects a 4-digit year (e.g., 2025).")
+    if not root.exists() or not root.is_dir():
+        raise typer.BadParameter(f"Experiments root not found: {root}")
+    year_dir = root / year_str
+    if not year_dir.exists() or not year_dir.is_dir():
+        raise typer.BadParameter(f"No experiments directory for year {year_str} under {root}.")
+    jobs = find_jobs(year_dir)
+    if not jobs:
+        raise typer.BadParameter(f"No experiments found under {year_dir}.")
+    return jobs
+
+
+def infer_job_path(job: str | None) -> Path:
+    if job:
+        value = str(job).strip()
+        path = Path(value)
+        if path.exists():
+            if path.is_dir():
+                candidate = path / "config.yaml"
+                if candidate.exists():
+                    return candidate.resolve()
+                raise typer.BadParameter(
+                    f"CONFIG directory {path!s} has no 'config.yaml'. "
+                    "Pass a file path, an experiment directory that contains config.yaml, or a numeric index "
+                    f"(see '{reader_command('ls')}')."
+                )
+            return path.resolve()
+        if value.isdigit():
+            idx = int(value)
+            root_path = find_nearest_experiments_dir(Path.cwd())
+            jobs = indexed_jobs(root_path)
+            jobs_with_scaffolds = indexed_jobs(root_path, include_scaffolds=True)
+            if not jobs_with_scaffolds:
+                raise typer.BadParameter(f"No experiments found under {root_path}. Use '{reader_command('ls')}' first.")
+            job_lookup = dict(jobs)
+            if idx in job_lookup:
+                return job_lookup[idx]
+            jobs_with_scaffolds_lookup = dict(jobs_with_scaffolds)
+            if idx in jobs_with_scaffolds_lookup:
+                hidden_job = jobs_with_scaffolds_lookup[idx]
+                raise typer.BadParameter(
+                    f"Experiment index {idx} points to hidden scaffold/template config {hidden_job.parent} under {root_path}. "
+                    "Numeric indexes only address the default 'reader ls' inventory. "
+                    "Pass the path explicitly for scaffold/template configs."
+                )
+            scaffold_hint = ""
+            if jobs_with_scaffolds != jobs:
+                scaffold_hint = (
+                    " Default index range: "
+                    f"{_format_index_span(index for index, _ in jobs)}; with '--all': "
+                    f"{_format_index_span(index for index, _ in jobs_with_scaffolds)}."
+                )
+            raise typer.BadParameter(
+                f"Experiment index out of range: {idx} (valid: {_format_index_span(index for index, _ in jobs)}"
+                f" under {root_path})."
+                f"{scaffold_hint} Use '{reader_command('ls')}' to see the index numbers."
+            )
+        raise typer.BadParameter(
+            f"CONFIG not found: {job!r}. Pass a path to a config.yaml, an experiment directory, "
+            f"or a numeric experiment index from '{reader_command('ls')}'."
+        )
+
+    cwd = Path.cwd()
+    candidate = cwd / "config.yaml"
+    if candidate.exists():
+        return candidate.resolve()
+    for base in cwd.parents:
+        candidate = base / "config.yaml"
+        if candidate.exists():
+            return candidate.resolve()
+    raise typer.BadParameter(
+        "Missing CONFIG and no 'config.yaml' found in the current or parent directories. "
+        "Run inside an experiment dir or pass a path to the config (or the experiment dir). "
+        f"Tip: use '{reader_command('ls')}' to list experiments and pass its index."
+    )
+
+
+def _format_index_span(indices) -> str:
+    values = [int(value) for value in indices]
+    if not values:
+        return "none"
+    if values == list(range(values[0], values[-1] + 1)):
+        if values[0] == values[-1]:
+            return str(values[0])
+        return f"{values[0]}..{values[-1]}"
+    return ", ".join(str(value) for value in values)
+
+
+def format_job_arg(job: str | None) -> str | None:
+    if job is None:
+        return None
+    value = str(job).strip()
+    return value or None
+
+
+def ensure_active_lifecycle(decl: WorkbenchDecl, job_path: Path, *, command_name: str) -> None:
+    lifecycle = decl.experiment.lifecycle
+    if lifecycle == "active":
+        return
+    raise typer.BadParameter(
+        f"Experiment lifecycle '{lifecycle}' is not runnable for '{command_name}'. "
+        f"Use '{reader_command('validate', job_path, '--no-files')}' to check the config or "
+        f"'{reader_command('inspect', job_path)}' for details."
+    )
+
+
+def require_dataframe_records(decl: WorkbenchDecl, job_path: Path, *, runtime: ReaderRuntime) -> None:
+    layout = decl.experiment_semantics.layout
+    outputs_dir = layout.outputs_dir
+    store = runtime.record_store(
+        outputs_dir,
+        plots_subdir=layout.plots_subdir,
+        exports_subdir=layout.exports_subdir,
+        create=False,
+    )
+    if not store.catalog_exists():
+        raise RecordError(
+            f"No outputs/manifests/records.json found. Run '{reader_command('run', job_path)}' first to generate dataframe records."
+        )
+    try:
+        records = store.iter_latest_records(kind="dataframe_artifact")
+    except RecordError as exc:
+        raise RecordError(f"Could not read record catalog at {store.records_path}: {exc}") from exc
+    if not records:
+        raise RecordError(
+            f"No dataframe records listed in outputs/manifests/records.json. Run '{reader_command('run', job_path)}' first."
+        )
+
+
+def resolve_pipeline_step_id(decl: WorkbenchDecl, which: str, *, job_path: Path | None = None) -> str:
+    which_str = str(which).strip()
+    pipeline = list(_load("reader_workbench.workbench.graph").resolve_workbench(decl).pipeline)
+    if any(step.id == which_str for step in pipeline):
+        return which_str
+    options = ", ".join(step.id for step in pipeline[:12])
+    steps_command = reader_command("steps", job_path) if job_path is not None else reader_command("steps")
+    raise typer.BadParameter(
+        f"Unknown pipeline step id '{which_str}'. Tip: use '{steps_command}' to list ids "
+        f"(first few: {options}{' …' if len(pipeline) > 12 else ''})."
+    )
+
+
+def spec_to_dict(spec_obj) -> dict:
+    if hasattr(spec_obj, "to_dict"):
+        return spec_obj.to_dict()
+    return {
+        "id": spec_obj.id,
+        "plugin": spec_obj.plugin,
+        "reads": {
+            key: _load("reader_workbench.workbench.graph").input_ref_to_dict(value)
+            for key, value in (spec_obj.reads or {}).items()
+        },
+        "with": dict(spec_obj.with_ or {}),
+        "writes": {
+            key: _load("reader_workbench.workbench.graph").output_ref_to_dict(value)
+            for key, value in (spec_obj.writes or {}).items()
+        },
+    }

reader_workbench/workbench/cli/main.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+
+import click
+import typer
+
+from reader_workbench.errors import ReaderError
+
+from .automation import (
+    as_click_error,
+    begin_request,
+    click_error_details,
+    emit_document,
+    end_request,
+    error_envelope,
+    json_requested,
+    reader_error_details,
+)
+from .shared import app
+
+
+def main(args: Sequence[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if args is None else args)
+    tokens = begin_request(argv)
+    try:
+        command = typer.main.get_command(app)
+        result = command.main(args=argv, prog_name="reader", standalone_mode=False)
+        return int(result) if isinstance(result, int) else 0
+    except (click.exceptions.Exit, typer.Exit) as exc:
+        return int(exc.exit_code)
+    except ReaderError as exc:
+        if json_requested():
+            emit_document(error_envelope(**reader_error_details(exc)))
+            return 1
+        raise
+    except Exception as exc:
+        click_error = as_click_error(exc)
+        if click_error is not None:
+            if json_requested():
+                emit_document(error_envelope(**click_error_details(click_error)))
+            else:
+                click_error.show()
+            return int(click_error.exit_code)
+        if not json_requested():
+            raise
+        emit_document(
+            error_envelope(
+                code="internal_error",
+                field="command",
+                reason="Reader encountered an unexpected internal error.",
+                remediation="Report this Reader defect with the command and error code; do not retry unchanged.",
+                retryable=False,
+            )
+        )
+        return 1
+    finally:
+        end_request(tokens)

reader_workbench/workbench/cli/maintenance.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from . import shared
+from ._lazy import load as _load
+from .shared import app, emit_json, emit_json_error, normalize_output_format
+
+maintain_app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Run checks that maintain the Reader source repository.",
+)
+REPO_ROOT_OPTION = typer.Option(Path("."), "--repo-root", metavar="DIR", help="Reader source checkout root.")
+
+
+def _emit_report(report, *, format: str) -> None:
+    if format == "json":
+        if report.ok:
+            emit_json(report.to_payload())
+        else:
+            first_error = report.errors[0] if report.errors else "unknown maintenance check failure"
+            emit_json_error(
+                code="maintenance_check_failed",
+                field="repo_root",
+                reason=f"{report.check} check found {len(report.errors)} problem(s). First: {first_error}",
+                remediation=f"Correct the reported {report.check} problem(s), then rerun this command.",
+            )
+        return
+    status = "ok" if report.ok else "failed"
+    shared.console.print(f"{report.check} integrity {status}: {report.checked} checked")
+    for error in report.errors:
+        shared.console.print(f"- {error}")
+
+
+def _run_check(name: str, *, repo_root: Path, format: str) -> None:
+    fmt = normalize_output_format(format)
+    if (
+        not repo_root.is_dir()
+        or not (repo_root / "pyproject.toml").is_file()
+        or not (repo_root / "src" / "reader_workbench").is_dir()
+    ):
+        raise typer.BadParameter(
+            f"Reader source checkout not found: {repo_root}",
+            param_hint="--repo-root",
+        )
+    module = _load(f"reader_workbench.maintenance.{name}")
+    report = getattr(module, f"check_{name}")(repo_root)
+    _emit_report(report, format=fmt)
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+@maintain_app.command("docs", help="Check documentation links, routes, anchors, and front matter.")
+def docs(
+    repo_root: Path = REPO_ROOT_OPTION,
+    format: str = typer.Option(
+        "table",
+        "--format",
+        metavar="FMT",
+        help="Output format: table | json (default: table).",
+    ),
+) -> None:
+    _run_check("docs", repo_root=repo_root, format=format)
+
+
+@maintain_app.command("skills", help="Check repo-local skill structure and source references.")
+def skills(
+    repo_root: Path = REPO_ROOT_OPTION,
+    format: str = typer.Option(
+        "table",
+        "--format",
+        metavar="FMT",
+        help="Output format: table | json (default: table).",
+    ),
+) -> None:
+    _run_check("skills", repo_root=repo_root, format=format)
+
+
+app.add_typer(maintain_app, name="maintain")

reader_workbench/workbench/cli/notebooks.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import typer
+from rich import box
+from rich.panel import Panel
+
+from reader_workbench.errors import ConfigError, RecordError
+from reader_workbench.workbench.paths import resolve_confined_sink_root, resolve_path_within_root
+
+from . import shared
+from ._lazy import load as _load
+from .helpers import (
+    default_notebook_name,
+    infer_job_path,
+    load_job_models,
+    next_available_path,
+)
+from .shared import (
+    NOTEBOOK_MODE_OPTION,
+    app,
+)
+
+
+def render_marimo_help(target: Path, *, mode: str, has_fcs: bool) -> None:
+    marimo_cmd = f"{shared.sys.executable} -m marimo {mode} {target}"
+    shared.console.print(
+        Panel.fit(
+            "Could not launch marimo automatically.\n\n"
+            "Reader does not publish a notebook dependency extra while the released Marimo and "
+            "PyMdown constraints remain unresolved. Use a separately managed and audited "
+            "environment that provides Marimo, Altair, and DuckDB, then run:\n"
+            f"  {marimo_cmd}\n\n"
+            f"Notebook: [path]{target}[/path]",
+            border_style="warn",
+            box=box.ROUNDED,
+        )
+    )
+
+
+def render_marimo_routes(*, target: Path, url: str, runtime_root: Path) -> None:
+    check_cmd = f"uv run marimo check {target}"
+    shared.console.print(
+        Panel.fit(
+            "Review routes:\n"
+            f"  Static check: {check_cmd}\n"
+            f"  Browser review: {url}\n"
+            "  In-app browser: open the URL in a fresh isolated page.\n\n"
+            f"Managed runtime root: [path]{runtime_root}[/path]",
+            border_style="accent",
+            box=box.ROUNDED,
+        )
+    )
+
+
+def _notebook_filename(raw: str) -> str:
+    candidate = Path(raw)
+    if (
+        not raw
+        or raw != raw.strip()
+        or candidate.is_absolute()
+        or len(candidate.parts) != 1
+        or candidate in {Path("."), Path("..")}
+        or candidate.suffix != ".py"
+    ):
+        raise ConfigError("--name must be a non-empty .py filename with no directory components")
+    return raw
+
+
+def _launch_marimo(
+    mode: str,
+    target: Path,
+    *,
+    has_fcs: bool,
+    headless: bool = False,
+    port: int | None = None,
+    repo_root: Path | None = None,
+) -> None:
+    launch = _load("reader_workbench.workbench.notebooks.launch")
+    plan = launch.plan_marimo_launch(
+        mode=mode,
+        target=target,
+        headless=headless,
+        preferred_port=port,
+        base_env=os.environ.copy(),
+        repo_root=repo_root,
+    )
+    if plan.terminated_sessions:
+        shared.console.print(
+            Panel.fit(
+                f"Pruned {len(plan.terminated_sessions)} existing reader-managed Marimo session(s) "
+                "for this experiment before launch.",
+                border_style="warn",
+                box=box.ROUNDED,
+            )
+        )
+    if plan.reused_session is not None:
+        shared.console.print(
+            Panel.fit(
+                f"Notebook already running: [path]{target}[/path]\n[muted]url[/muted]: {plan.url}",
+                border_style="ok",
+                box=box.ROUNDED,
+            )
+        )
+        render_marimo_routes(target=target, url=plan.url, runtime_root=plan.runtime_paths.root)
+        if not headless:
+            launch.open_url(plan.url)
+        return
+    shared.console.print(
+        Panel.fit(
+            f"Launching: {' '.join(plan.cmd)}\n[muted]url[/muted]: {plan.url}",
+            border_style="accent",
+            box=box.ROUNDED,
+        )
+    )
+    render_marimo_routes(target=target, url=plan.url, runtime_root=plan.runtime_paths.root)
+    try:
+        proc = shared.subprocess.Popen(plan.cmd, env=plan.env)
+    except FileNotFoundError:
+        render_marimo_help(target, mode=mode, has_fcs=has_fcs)
+        raise typer.Exit(code=1) from None
+    launch.register_managed_session(
+        registry_path=plan.runtime_paths.registry_path,
+        pid=proc.pid,
+        port=plan.port,
+        host=plan.host,
+        mode=mode,
+        target=target,
+        repo_root=plan.repo_root,
+    )
+    try:
+        returncode = proc.wait()
+    finally:
+        launch.unregister_managed_session(registry_path=plan.runtime_paths.registry_path, pid=proc.pid)
+    if returncode != 0:
+        render_marimo_help(target, mode=mode, has_fcs=has_fcs)
+        raise typer.Exit(code=1)
+
+
+def _scaffold_notebook(
+    *,
+    job: str | None,
+    name: str | None,
+    overwrite: bool,
+    new: bool,
+    refresh: bool,
+    mode: str,
+    headless: bool,
+    port: int | None,
+) -> None:
+    try:
+        if overwrite and new:
+            raise typer.BadParameter("--overwrite cannot be combined with --new.")
+        if refresh:
+            overwrite = True
+        mode_value = (mode or "").strip().lower()
+        if mode_value not in {"edit", "run", "none"}:
+            raise typer.BadParameter("--mode must be one of: edit, run, none.")
+        job_path = infer_job_path(job)
+        exp_dir = job_path.parent
+        _, decl = load_job_models(job_path)
+        layout = decl.experiment_semantics.layout
+        outputs_dir = layout.outputs_dir
+        notebooks_cfg = layout.notebooks_subdir
+        notebook_root = outputs_dir if notebooks_cfg in ("", ".", "./") else outputs_dir / str(notebooks_cfg)
+        try:
+            nb_dir = resolve_confined_sink_root(notebook_root, root=outputs_dir, label="notebooks")
+        except ValueError as exc:
+            raise ConfigError(str(exc)) from exc
+        target_name = default_notebook_name() if name is None else _notebook_filename(name)
+        target_candidate = nb_dir / target_name
+        if target_candidate.is_symlink():
+            raise ConfigError(f"Notebook target must not be a symlink: {target_candidate}")
+        try:
+            target = resolve_path_within_root(target_candidate, root=nb_dir)
+        except ValueError as exc:
+            raise ConfigError(f"Notebook target must stay within the notebooks sink root: {target_candidate}") from exc
+        if new:
+            target = next_available_path(target)
+        has_fcs = any(path.suffix.lower() == ".fcs" for path in exp_dir.rglob("*.fcs"))
+        existed = target.exists()
+        target, created = _load("reader_workbench.workbench.notebooks").write_experiment_notebook(
+            target,
+            experiment_root=decl.experiment.root,
+            notebooks_root=nb_dir,
+            overwrite=overwrite,
+        )
+        if created:
+            if existed and overwrite:
+                status = f"✓ Notebook overwritten: [path]{target}[/path]"
+            else:
+                status = f"✓ Notebook created: [path]{target}[/path]"
+            border_style = "ok"
+        else:
+            action = "opening existing" if mode_value != "none" else "using existing"
+            status = f"Notebook already exists: [path]{target}[/path] {action}."
+            border_style = "warn"
+        shared.console.print(Panel.fit(status, border_style=border_style, box=box.ROUNDED))
+        if mode_value == "none":
+            shared.console.print(str(target))
+            return
+        _launch_marimo(mode_value, target, has_fcs=has_fcs, headless=headless, port=port)
+    except (ConfigError, RecordError) as err:
+        raise typer.BadParameter(str(err)) from err
+
+
+@app.command(help="Scaffold an interactive marimo notebook and open it.")
+def notebook(
+    job: str | None = typer.Argument(
+        None,
+        metavar="CONFIG|DIR|INDEX",
+        help=shared.JOB_ARG_HELP_SHORT,
+    ),
+    name: str | None = typer.Option(
+        None,
+        "--name",
+        help="Notebook filename (created under outputs/notebooks). Defaults to EDA_YYYYMMDD.py.",
+    ),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        "--force",
+        help="Overwrite the selected generated notebook if it already exists.",
+    ),
+    new: bool = typer.Option(
+        False,
+        "--new",
+        help="Create an additional notebook by appending a numeric suffix if needed.",
+    ),
+    refresh: bool = typer.Option(
+        False,
+        "--refresh",
+        help="Regenerate the notebook even if it exists (same as --overwrite).",
+    ),
+    headless: bool = typer.Option(
+        False,
+        "--headless",
+        help="Launch without opening a browser. Reader prints a loopback URL suitable for in-app review.",
+    ),
+    port: int | None = typer.Option(
+        None,
+        "--port",
+        min=1,
+        max=65535,
+        help="Preferred loopback port. Defaults to a reader-managed clean port starting at 2718.",
+    ),
+    mode: str = NOTEBOOK_MODE_OPTION,
+):
+    _scaffold_notebook(
+        job=job,
+        name=name,
+        overwrite=overwrite,
+        new=new,
+        refresh=refresh,
+        headless=headless,
+        port=port,
+        mode=mode,
+    )