Source code for brushline.cli

"""The Brushline command line.

The command surface grows one phase at a time. Phase 0 establishes the entry point and the
version contract; later phases add the build, simulate, plan, monitor, compare, validate, and
serve commands described in ``ROADMAP.md``.
"""

from __future__ import annotations

import json
from pathlib import Path
from typing import Annotated

import typer

from brushline import __version__
from brushline.build.compiler import compile_fixture
from brushline.demo.builder import build_demo_site
from brushline.field.comparison import compare_field_files, write_field_comparison
from brushline.field.validation import validate_field_csv, write_field_validation
from brushline.fixtures.synthetic import DEFAULT_SEED, generate_fixture
from brushline.instance_ops import (
    build_demo_file,
    compile_dataset_file,
    seed_state_file,
    segment_corridor_file,
    validate_aoi_file,
    validate_scenario_file,
)
from brushline.instance_template import install_instance_template
from brushline.model.schema import validate_dataset
from brushline.sim.engine import simulate_dataset

app = typer.Typer(
    name="brushline",
    help="Decision support for vegetation management along linear infrastructure corridors.",
    no_args_is_help=True,
    add_completion=False,
)


def _version_callback(value: bool) -> None:
    """Print the package version and exit when ``--version`` is given.

    Parameters
    ----------
    value : bool
        Whether the eager ``--version`` flag was supplied.

    Raises
    ------
    typer.Exit
        When ``value`` is true.
    """
    if value:
        typer.echo(f"brushline {__version__}")
        raise typer.Exit()


[docs] @app.callback() def main( version: Annotated[ bool, typer.Option( "--version", callback=_version_callback, is_eager=True, help="Show the package version and exit.", ), ] = False, ) -> None: """Run the Brushline command line."""
[docs] @app.command() def status() -> None: """Print the package version and its pre-alpha status.""" typer.echo(f"brushline {__version__} (pre-alpha)") typer.echo( "Planning, monitoring, exchange, public demo, and studio are present. " "See the release notes and known gaps before use." )
[docs] @app.command() def fixture( out: Annotated[ Path, typer.Option("--out", help="Directory for the synthetic corridor fixture."), ], force: Annotated[ bool, typer.Option("--force", help="Overwrite the known fixture files."), ] = False, seed: Annotated[ int, typer.Option("--seed", help="Fixture seed."), ] = DEFAULT_SEED, ) -> None: """Generate the deterministic synthetic corridor fixture. Parameters ---------- out : Path Destination directory. force : bool, optional Overwrite the known fixture files. Defaults to ``False``. seed : int, optional Fixture seed. Defaults to ``DEFAULT_SEED``. Raises ------ typer.Exit With status 1 when the destination is not empty or a contract fails. """ try: result = generate_fixture(out, seed=seed, force=force) except (FileExistsError, RuntimeError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"fixture: {result.root}") typer.echo(f"artifacts: {len(result.artifacts)}") typer.echo(f"content_digest: {result.content_digest}")
instance_app = typer.Typer( help="Manage Brushline instance templates.", no_args_is_help=True, )
[docs] @instance_app.command("template") def instance_template( instance_root: Annotated[ Path, typer.Option("--instance-root", help="FEMIC instance root."), ], force: Annotated[ bool, typer.Option("--force", help="Overwrite existing template files."), ] = False, ) -> None: """Install the Brushline template overlay on a FEMIC instance. Parameters ---------- instance_root : Path FEMIC instance root. It is created when it does not exist. force : bool, optional Overwrite existing template files. Defaults to ``False``. Raises ------ typer.Exit With status 1 when the packaged template is missing. """ try: result = install_instance_template(instance_root, force=force) except FileNotFoundError as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"instance: {result.root}") typer.echo(f"written: {len(result.written)}") typer.echo(f"skipped: {len(result.skipped)}")
[docs] @instance_app.command("validate-aoi") def instance_validate_aoi( aoi: Annotated[Path, typer.Option("--aoi", help="AOI GeoJSON.")], out: Annotated[Path, typer.Option("--out", help="Output directory.")], ) -> None: """Validate an AOI GeoJSON and write the report.""" try: path = validate_aoi_file(aoi, out) except (OSError, ValueError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"aoi_validation: {path}")
[docs] @instance_app.command("segment-corridor") def instance_segment_corridor( corridor: Annotated[Path, typer.Option("--corridor", help="Corridor graph JSON.")], out: Annotated[Path, typer.Option("--out", help="Output directory.")], ) -> None: """Validate a corridor graph and write its segment table.""" try: path = segment_corridor_file(corridor, out) except (OSError, ValueError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"segments: {path}")
[docs] @instance_app.command("compile-dataset") def instance_compile_dataset( fixture: Annotated[Path, typer.Option("--fixture", help="Fixture directory.")], out: Annotated[Path, typer.Option("--out", help="Compiled dataset directory.")], force: Annotated[bool, typer.Option("--force", help="Overwrite the dataset.")] = False, ) -> None: """Compile a fixture into a validated Brushline dataset.""" try: result = compile_dataset_file(fixture, out, force=force) except (OSError, ValueError, FileExistsError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"dataset: {result.root}") typer.echo(f"content_digest: {result.manifest.content_digest}")
[docs] @instance_app.command("seed-state") def instance_seed_state( state: Annotated[Path, typer.Option("--state", help="State contract JSON.")], out: Annotated[Path, typer.Option("--out", help="Output directory.")], ) -> None: """Validate a state contract and write the seed state artifact.""" try: path = seed_state_file(state, out) except (OSError, ValueError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"state: {path}")
[docs] @instance_app.command("validate-scenario") def instance_validate_scenario( scenario: Annotated[Path, typer.Option("--scenario", help="Scenario YAML.")], targets: Annotated[Path, typer.Option("--targets", help="Targets YAML.")], out: Annotated[Path, typer.Option("--out", help="Output directory.")], ) -> None: """Validate the scenario and targets YAML.""" try: path = validate_scenario_file(scenario, targets, out) except (OSError, ValueError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"scenario_validation: {path}")
[docs] @instance_app.command("build-demo") def instance_build_demo( demo: Annotated[Path, typer.Option("--demo", help="Demo manifest JSON.")], out: Annotated[Path, typer.Option("--out", help="Output directory.")], ) -> None: """Validate a demo manifest and write the demo artifact.""" try: path = build_demo_file(demo, out) except (OSError, ValueError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"demo: {path}")
[docs] @app.command() def build( fixture: Annotated[ Path, typer.Option("--fixture", help="Fixture directory to compile."), ], out: Annotated[ Path, typer.Option("--out", help="Compiled dataset directory."), ], force: Annotated[ bool, typer.Option("--force", help="Overwrite an existing compiled dataset."), ] = False, ) -> None: """Compile a fixture into a validated Brushline dataset. Parameters ---------- fixture : Path Fixture directory. out : Path Compiled dataset directory. force : bool, optional Overwrite an existing dataset. Defaults to ``False``. Raises ------ typer.Exit With status 1 when the compile fails. """ try: result = compile_fixture(fixture, out, force=force) except (FileExistsError, ValueError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"dataset: {result.root}") typer.echo(f"segments: {len(result.segments)}") typer.echo(f"states: {len(result.states)}") typer.echo(f"content_digest: {result.manifest.content_digest}")
[docs] @app.command() def simulate( dataset: Annotated[ Path, typer.Option("--dataset", help="Compiled dataset directory."), ], out: Annotated[ Path, typer.Option("--out", help="Run directory."), ], plan: Annotated[ Path | None, typer.Option("--plan", help="Plan artifact to replay."), ] = None, schedule: Annotated[ Path | None, typer.Option("--schedule", help="Schedule CSV to replay."), ] = None, years: Annotated[ int, typer.Option("--years", min=1, max=50, help="Simulation years."), ] = 5, start_year: Annotated[ int, typer.Option("--start-year", help="First simulation year."), ] = 2026, force: Annotated[ bool, typer.Option("--force", help="Overwrite an existing run directory."), ] = False, ) -> None: """Replay a plan or schedule against a compiled dataset. Parameters ---------- dataset : Path Compiled dataset directory. out : Path Run directory. plan : Path or None, optional Plan artifact. Exactly one of ``plan`` and ``schedule`` is required. schedule : Path or None, optional Schedule CSV. Exactly one of ``plan`` and ``schedule`` is required. years : int, optional Simulation years. Defaults to ``5``. start_year : int, optional First simulation year. Defaults to ``2026``. force : bool, optional Overwrite an existing run. Defaults to ``False``. Raises ------ typer.Exit With status 1 when the simulation fails. """ try: result = simulate_dataset( dataset, out, plan=plan, schedule=schedule, years=years, start_year=start_year, force=force, ) except (FileExistsError, ValueError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"run: {result.run_dir}") typer.echo(f"total_cost: {result.summary['total_cost']}") typer.echo(f"final_mean_height_m: {result.summary['final_mean_height_m']}")
[docs] @app.command() def prototype( fixture: Annotated[ Path, typer.Option("--fixture", help="Fixture directory."), ], out: Annotated[ Path, typer.Option("--out", help="Prototype output directory."), ], years: Annotated[ int, typer.Option("--years", min=1, max=50, help="Simulation years."), ] = 5, ) -> None: """Compile and simulate the synthetic fixture end to end. Parameters ---------- fixture : Path Fixture directory. out : Path Output directory. The dataset is written under ``dataset`` and the run under ``run``. years : int, optional Simulation years. Defaults to ``5``. Raises ------ typer.Exit With status 1 when the compile or simulation fails. """ try: compiled = compile_fixture(fixture, out / "dataset", force=True) result = simulate_dataset( compiled.root, out / "run", plan=Path(fixture) / "plan.json", years=years, force=True, ) except (FileExistsError, ValueError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc typer.echo(f"dataset: {compiled.root}") typer.echo(f"run: {result.run_dir}") typer.echo(f"total_cost: {result.summary['total_cost']}")
[docs] @app.command() def validate( dataset: Annotated[ Path, typer.Option("--dataset", help="Compiled dataset directory to validate."), ], json_output: Annotated[ bool, typer.Option("--json", help="Print the validation report as JSON."), ] = False, ) -> None: """Validate a compiled corridor dataset against its manifest. Parameters ---------- dataset : Path Dataset directory that contains ``manifest.json``. json_output : bool, optional Print the JSON report instead of the text summary. Raises ------ typer.Exit With status 1 when the dataset is invalid. """ report = validate_dataset(dataset) if json_output: typer.echo(json.dumps(report.to_dict(), indent=2)) else: typer.echo(f"dataset: {report.dataset}") typer.echo(f"tables: {len(report.tables)}") for name, rows in sorted(report.tables.items()): typer.echo(f" {name}: {rows} rows") if report.warnings: typer.echo("warnings:") for message in report.warnings: typer.echo(f" {message}") if report.errors: typer.echo("errors:") for message in report.errors: typer.echo(f" {message}") typer.echo("VALID" if report.is_valid else "INVALID") if not report.is_valid: raise typer.Exit(code=1)
field_app = typer.Typer(help="Validate field observations for a planned campaign.")
[docs] @field_app.command("validate") def field_validate( observations: Annotated[ Path, typer.Option("--csv", help="Field observations CSV exported from the field kit.") ], plots: Annotated[Path, typer.Option("--plots", help="Planned plot points as GeoJSON.")], out: Annotated[ Path | None, typer.Option("--out", help="Write normalized observations to JSON.") ] = None, json_output: Annotated[ bool, typer.Option("--json", help="Print the validation report as JSON.") ] = False, ) -> None: """Validate field observations and optionally write normalized JSON. Parameters ---------- observations : Path Field observations CSV. plots : Path Planned plot references GeoJSON. out : Path, optional Normalized JSON output. json_output : bool, optional Print JSON instead of a text summary. Raises ------ typer.Exit With status 1 when the observations are invalid. """ try: report = validate_field_csv(observations, plots) except (OSError, ValueError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc if out is not None: write_field_validation(report, out) if json_output: typer.echo(report.model_dump_json(indent=2)) else: typer.echo(f"observations: {report.source_csv}") typer.echo(f"plots_expected: {report.plots_expected}") typer.echo(f"observations_valid: {len(report.observations)}") if report.warnings: typer.echo("warnings:") for message in report.warnings: typer.echo(f" {message}") if report.errors: typer.echo("errors:") for message in report.errors: typer.echo(f" {message}") typer.echo("VALID" if report.valid else "INVALID") if not report.valid: raise typer.Exit(code=1)
[docs] @field_app.command("compare") def field_compare( observations: Annotated[ Path, typer.Option("--observations", help="Validated field observation JSON.") ], plots: Annotated[Path, typer.Option("--plots", help="Planned plot targets as GeoJSON.")], out: Annotated[ Path | None, typer.Option("--out", help="Write the comparison report to JSON.") ] = None, json_output: Annotated[ bool, typer.Option("--json", help="Print the comparison report as JSON.") ] = False, ) -> None: """Compare field observations with LiDAR plot targets. Parameters ---------- observations : Path Validated field observation JSON. plots : Path Planned plot targets as GeoJSON. out : Path, optional Comparison JSON output. json_output : bool, optional Print JSON instead of a text summary. Raises ------ typer.Exit With status 1 when the inputs are invalid. """ try: report = compare_field_files(observations, plots) except (OSError, ValueError) as exc: typer.echo(f"error: {exc}", err=True) raise typer.Exit(code=1) from exc if out is not None: write_field_comparison(report, out) if json_output: typer.echo(report.model_dump_json(indent=2)) else: typer.echo(f"observations_compared: {report.observations_compared}") typer.echo(f"plots_compared: {report.plots_compared}") typer.echo(f"status: {report.status}") typer.echo(f"cover_multiplier: {report.calibration.cover_multiplier}") typer.echo(f"height_multiplier: {report.calibration.height_multiplier}") if report.warnings: typer.echo("warnings:") for message in report.warnings: typer.echo(f" {message}") if report.recommendations: typer.echo("recommendations:") for message in report.recommendations: typer.echo(f" {message}")
app.add_typer(field_app, name="field") app.add_typer(instance_app, name="instance") demo_app = typer.Typer(help="Build the public demo portal.")
[docs] @demo_app.command("build") def demo_build( out: Annotated[Path, typer.Option("--out", help="Destination directory.")] = Path("build/demo"), artifact_root: Annotated[ Path, typer.Option("--artifact-root", help="Run artifact root.") ] = Path("examples/synthetic-corridor"), ) -> None: """Build the static public demo site.""" root = build_demo_site(out, artifact_root=artifact_root) typer.echo(f"demo: {root}")
app.add_typer(demo_app, name="demo")