Add structured compiler diagnostics

src/docforge/cli.py

@@ -15,12 +15,18 @@ from .index import ProjectIndex
 from .onboarding import assess_project, scaffold_project
 from .project import Project, project_root_fingerprint
 from .rendering import RenderService
+from .telemetry import request
 from .viewer_manager import ViewerManagerClient
 
 
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="docforge")
     parser.add_argument("--project-root", type=Path, required=True)
+    parser.add_argument(
+        "--diagnostics",
+        action="store_true",
+        help="Attach bounded request-local stage timings and counters",
+    )
     commands = parser.add_subparsers(dest="command", required=True)
     onboard = commands.add_parser("onboard")
     onboard.add_argument("--language", action="append", default=[])
@@ -214,12 +220,20 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
 def main(argv: list[str] | None = None) -> int:
     parser = _parser()
     arguments = parser.parse_args(argv)
-    try:
-        result = _run(arguments)
-        code = 0
-    except DocForgeError as error:
-        result = {"status": "error", "error": error.as_dict()}
-        code = 2
+    with request(
+        f"cli.{arguments.command}",
+        enabled=arguments.diagnostics,
+    ) as collector:
+        try:
+            result = _run(arguments)
+            code = 0
+        except DocForgeError as error:
+            result = {"status": "error", "error": error.as_dict()}
+            code = 2
+    if collector is not None:
+        result["diagnostics"] = collector.as_dict(
+            outcome="ok" if code == 0 else "error",
+        )
     print(json.dumps(result, sort_keys=True, indent=2))
     return code