fix(nextflow): move stage CLIs into module bins

Author: edmundmiller

modules/local/aggregate_benchmark_report_data/AGENTS.md

@@ -5,9 +5,14 @@ Purpose
 
 Owns
 - `AGGREGATE_BENCHMARK_REPORT_DATA` in `main.nf`
-- Python aggregation logic in `bin/benchmark_report_aggregate.py`
+- Module-local CLI entrypoint in `bin/benchmark_report.py`
+- Shared aggregation logic in repo-root `bin/benchmark_report_aggregate.py`
 - Stage-scoped tests under `tests/`
 
+Run directly
+- `nextflow run modules/local/aggregate_benchmark_report_data/main.nf -profile docker,arm --jsonl_bundle <jsonl_bundle_dir>`
+- The direct `nextflow run modules/local/...` path depends on the module-local `bin/benchmark_report.py` shim/CLI; keep that invocation shape working if you refactor the stage.
+
 Inputs
 - `jsonl_bundle/` from `normalize_benchmark_jsonl`
 

modules/local/aggregate_benchmark_report_data/bin/benchmark_report.py

@@ -1,28 +1,52 @@
 #!/usr/bin/env python3
-"""Module-local shim for direct `nextflow run modules/local/...` execution.
+"""Aggregate benchmark JSONL datasets into report_data.json.
 
-This delegates to the repo-root benchmark_report.py so the shared CLI and
-assets/template lookup continue to work from the canonical implementation.
+This module-local entrypoint is the actual stage CLI used by
+`nextflow run modules/local/aggregate_benchmark_report_data/main.nf`.
 """
 
 from __future__ import annotations
 
-import runpy
+import argparse
 import sys
 from pathlib import Path
 
 
-def _find_repo_root() -> Path:
-    here = Path(__file__).resolve()
-    for parent in here.parents:
-        candidate = parent / "bin" / "benchmark_report.py"
-        if candidate.exists() and candidate != here:
-            return parent
-    raise RuntimeError(f"Could not locate repo root from {here}")
+def _add_repo_bin_to_path() -> None:
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "bin" / "benchmark_report_aggregate.py"
+        if candidate.exists():
+            sys.path.insert(0, str(parent / "bin"))
+            return
+    raise RuntimeError("Unable to locate the repository root for benchmark report helpers")
 
 
-REPO_ROOT = _find_repo_root()
-REPO_BIN = REPO_ROOT / "bin"
-sys.path.insert(0, str(REPO_BIN))
-sys.argv[0] = str(REPO_BIN / "benchmark_report.py")
-runpy.run_path(str(REPO_BIN / "benchmark_report.py"), run_name="__main__")
+_add_repo_bin_to_path()
+
+from benchmark_report_aggregate import aggregate_report_data  # noqa: E402
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="benchmark_report.py", description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    p = subparsers.add_parser("aggregate-report-data", help="Aggregate JSONL into report_data.json")
+    p.add_argument("--jsonl-dir", type=Path, required=True, help="Directory containing JSONL bundle")
+    p.add_argument(
+        "--output",
+        type=Path,
+        default=Path("report_data.json"),
+        help="Output report_data.json path",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _build_parser().parse_args(argv)
+    if args.command == "aggregate-report-data":
+        aggregate_report_data(jsonl_dir=args.jsonl_dir, output=args.output)
+        print(f"Report data written to {args.output}")
+
+
+if __name__ == "__main__":
+    main()

modules/local/normalize_benchmark_jsonl/AGENTS.md

@@ -5,9 +5,14 @@ Purpose
 
 Owns
 - `NORMALIZE_BENCHMARK_JSONL` in `main.nf`
-- Python stage logic in `bin/benchmark_report_normalize.py`
+- Module-local CLI entrypoint in `bin/benchmark_report.py`
+- Shared normalization logic in repo-root `bin/benchmark_report_normalize.py`
 - Stage-scoped tests under `tests/`
 
+Run directly
+- `nextflow run modules/local/normalize_benchmark_jsonl/main.nf -profile docker,arm --data_dir <dir> --benchmark_aws_cur_report <parquet-or-NO_FILE>`
+- The direct `nextflow run modules/local/...` path depends on the module-local `bin/benchmark_report.py` shim/CLI; keep that invocation shape working if you refactor the stage.
+
 Inputs
 - `data_dir/` of per-run JSON payloads
 - optional CUR parquet

modules/local/normalize_benchmark_jsonl/bin/benchmark_report.py

@@ -1,28 +1,52 @@
 #!/usr/bin/env python3
-"""Module-local shim for direct `nextflow run modules/local/...` execution.
+"""Normalize raw benchmark run JSON files into JSONL datasets.
 
-This delegates to the repo-root benchmark_report.py so the shared CLI and
-assets/template lookup continue to work from the canonical implementation.
+This module-local entrypoint is the actual stage CLI used by
+`nextflow run modules/local/normalize_benchmark_jsonl/main.nf`.
 """
 
 from __future__ import annotations
 
-import runpy
+import argparse
 import sys
 from pathlib import Path
 
 
-def _find_repo_root() -> Path:
-    here = Path(__file__).resolve()
-    for parent in here.parents:
-        candidate = parent / "bin" / "benchmark_report.py"
-        if candidate.exists() and candidate != here:
-            return parent
-    raise RuntimeError(f"Could not locate repo root from {here}")
+def _add_repo_bin_to_path() -> None:
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "bin" / "benchmark_report_normalize.py"
+        if candidate.exists():
+            sys.path.insert(0, str(parent / "bin"))
+            return
+    raise RuntimeError("Unable to locate the repository root for benchmark report helpers")
 
 
-REPO_ROOT = _find_repo_root()
-REPO_BIN = REPO_ROOT / "bin"
-sys.path.insert(0, str(REPO_BIN))
-sys.argv[0] = str(REPO_BIN / "benchmark_report.py")
-runpy.run_path(str(REPO_BIN / "benchmark_report.py"), run_name="__main__")
+_add_repo_bin_to_path()
+
+from benchmark_report_normalize import normalize_jsonl  # noqa: E402
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="benchmark_report.py", description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    p = subparsers.add_parser("normalize-jsonl", help="Normalize raw run JSON into JSONL files")
+    p.add_argument("--data-dir", type=Path, required=True, help="Directory containing run JSON files")
+    p.add_argument(
+        "--output-dir",
+        type=Path,
+        default=Path("jsonl_bundle"),
+        help="Output JSONL bundle directory",
+    )
+    p.add_argument("--costs", type=Path, default=None, help="Optional AWS CUR parquet file")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _build_parser().parse_args(argv)
+    if args.command == "normalize-jsonl":
+        normalize_jsonl(data_dir=args.data_dir, output_dir=args.output_dir, costs_parquet=args.costs)
+
+
+if __name__ == "__main__":
+    main()

modules/local/render_benchmark_report/AGENTS.md

@@ -5,9 +5,14 @@ Purpose
 
 Owns
 - `RENDER_BENCHMARK_REPORT` in `main.nf`
-- Python render logic in `bin/benchmark_report_render.py`
+- Module-local CLI entrypoint in `bin/benchmark_report.py`
+- Shared render logic in repo-root `bin/benchmark_report_render.py`
 - Stage-scoped tests under `tests/`
 
+Run directly
+- `nextflow run modules/local/render_benchmark_report/main.nf -profile docker,arm --report_data_json <report_data.json> --brand_yml <brand.yml-or-NO_FILE> --logo_svg <logo.svg-or-NO_FILE>`
+- The direct `nextflow run modules/local/...` path depends on the module-local `bin/benchmark_report.py` shim/CLI; keep that invocation shape working if you refactor the stage.
+
 Inputs
 - `report_data.json`
 - optional `brand.yml`

modules/local/render_benchmark_report/bin/benchmark_report.py

@@ -1,28 +1,49 @@
 #!/usr/bin/env python3
-"""Module-local shim for direct `nextflow run modules/local/...` execution.
+"""Render benchmark report HTML from report_data.json.
 
-This delegates to the repo-root benchmark_report.py so the shared CLI and
-assets/template lookup continue to work from the canonical implementation.
+This module-local entrypoint is the actual stage CLI used by
+`nextflow run modules/local/render_benchmark_report/main.nf`.
 """
 
 from __future__ import annotations
 
-import runpy
+import argparse
 import sys
 from pathlib import Path
 
 
-def _find_repo_root() -> Path:
-    here = Path(__file__).resolve()
-    for parent in here.parents:
-        candidate = parent / "bin" / "benchmark_report.py"
-        if candidate.exists() and candidate != here:
-            return parent
-    raise RuntimeError(f"Could not locate repo root from {here}")
+def _add_repo_bin_to_path() -> None:
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "bin" / "benchmark_report_render.py"
+        if candidate.exists():
+            sys.path.insert(0, str(parent / "bin"))
+            return
+    raise RuntimeError("Unable to locate the repository root for benchmark report helpers")
 
 
-REPO_ROOT = _find_repo_root()
-REPO_BIN = REPO_ROOT / "bin"
-sys.path.insert(0, str(REPO_BIN))
-sys.argv[0] = str(REPO_BIN / "benchmark_report.py")
-runpy.run_path(str(REPO_BIN / "benchmark_report.py"), run_name="__main__")
+_add_repo_bin_to_path()
+
+from benchmark_report_render import render_report_from_json  # noqa: E402
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="benchmark_report.py", description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    p = subparsers.add_parser("render-html", help="Render report_data.json to HTML")
+    p.add_argument("--data", type=Path, required=True, help="report_data.json path")
+    p.add_argument("--output", type=Path, default=Path("benchmark_report.html"), help="Output HTML file")
+    p.add_argument("--brand", type=Path, default=None, help="Brand YAML file")
+    p.add_argument("--logo", type=Path, default=None, help="SVG logo file")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _build_parser().parse_args(argv)
+    if args.command == "render-html":
+        render_report_from_json(report_data_path=args.data, output=args.output, brand_path=args.brand, logo_path=args.logo)
+        print(f"Report written to {args.output}")
+
+
+if __name__ == "__main__":
+    main()