cli-consumption 0.3.3__tar.gz → 0.4.0__tar.gz

{cli_consumption-0.3.3 → cli_consumption-0.4.0}/.gitignore

@@ -12,6 +12,12 @@ reports/
 *.sqlite
 *.sqlite3
 .env
+node_modules/
+apps/*/.next/
+playwright-report/
+test-results/
+*.tsbuildinfo
+packages/*/dist/
 
 # Machine-specific orchestration context. These files must never be committed.
 .agents/orchestrator.md

{cli_consumption-0.3.3 → cli_consumption-0.4.0}/CHANGELOG.md

@@ -6,6 +6,39 @@ use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-01
+
+### Added
+
+- Added a blocking browser CI gate that opens detailed and share-safe dashboards
+  directly from `file://`, exercises their controls, and rejects network activity.
+- Defined the versioned, scoped, and bounded contracts for database upload, persistent
+  dashboard reporting, conversation pagination, and standalone web export.
+- Added read-only, migration-free extraction of bounded snapshot-schema-v1 payloads
+  from current local SQLite collection databases, including WAL-consistent reads,
+  exact schema verification, provider grouping, and privacy-safe failures.
+- Added `upload-db` with stable per-snapshot replay keys, required capability
+  negotiation, bounded retries, deterministic partial results, resumable uploads, and
+  strict fail-fast automation.
+- Added scoped `read` and `export` bearer credentials plus strict, bounded reporting
+  endpoints for dashboard datasets, filter options, opaque stable pagination,
+  conversation detail, and self-contained HTML downloads.
+- Added a locked TypeScript workspace with versioned dashboard contracts, pure shared
+  analytics, presentation helpers, Vitest parity coverage, ESM output, and a
+  reproducible network-free browser bundle included in Python wheels.
+- Added an authenticated responsive Next.js dashboard with a server-only collector
+  credential, bounded reporting BFF, URL-safe filters, conversation pagination and
+  detail, shared analytics, accessibility checks, and desktop/mobile browser coverage.
+- Replaced the classic offline renderer with the self-contained React/Tailwind runtime,
+  shared web primitives, streamed bounded dataset injection, reproducible packaged
+  assets, and detailed/share-safe `file://` browser coverage. The temporary
+  `--renderer` migration option was removed.
+- Added persistent-dashboard offline downloads for the exact visible selection, with
+  detailed/share-safe profiles, a credential-isolating bounded BFF, private temporary
+  cleanup, fixed failures, and self-contained browser coverage.
+
+## [0.3.3] - 2026-08-31
+
 ### Added
 
 - Added deterministic, compressed offline snapshot files authenticated with Ed25519,
@@ -131,7 +164,9 @@ use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - Refreshed the provider guide for the first minor release ([#26]).
 
-[Unreleased]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.3.2...HEAD
+[Unreleased]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.3.3...v0.4.0
+[0.3.3]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.2.1...v0.3.0

{cli_consumption-0.3.3 → cli_consumption-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-consumption
-Version: 0.3.3
+Version: 0.4.0
 Summary: Analyze and consolidate AI coding CLI consumption across machines.
 Project-URL: Homepage, https://github.com/Guillaume-Lombardo/cli-consumption
 Project-URL: Documentation, https://github.com/Guillaume-Lombardo/cli-consumption#readme
@@ -97,6 +97,20 @@ uv run cli-consumption export --output reports
 Open `reports/dashboard.html` locally. It makes no network requests. Detailed CSV
 tables are generated only when `--csv` is passed.
 
+Dashboard development lives in the locked npm workspace under `packages/`. It builds
+provider-neutral ESM analytics, shared React presentation primitives, and deterministic
+React/Tailwind browser assets that Python embeds in the wheel. The React runtime is the
+only offline renderer; installing or using the Python CLI does not require Node.js.
+
+The authenticated persistent dashboard lives in `apps/web/`. It reads the same
+minimized reporting contract through a server-side Next.js BFF: the browser never
+receives a collector credential or a database connection string. Its **Export
+offline** action downloads the exact visible selection as a self-contained detailed or
+share-safe HTML file. For a production
+setup, required environment variables, reverse-proxy constraints, and startup commands
+are documented in the
+[deployment guide](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/deployment.md#run-the-persistent-dashboard).
+
 To collect one provider or select another database:
 
 ```bash
@@ -157,7 +171,8 @@ for ingestion, idempotency, migrations, report limits, and collector behavior.
 | `collect` | Collect local or copied provider data into SQL. |
 | `snapshot` | Create or ingest signed, compressed offline snapshot files. |
 | `sync` | Collect and send metadata-only snapshots to a central API. |
-| `serve` | Run the central collection API. |
+| `upload-db` | Upload validated snapshots reconstructed from a local collect database. |
+| `serve` | Run the scoped central ingestion, reporting, and export API. |
 | `export` | Write the HTML dashboard and optional CSV tables. |
 | `providers` | List provider names and compatibility status. |
 | `retention` | Preview or apply deletion outside a retention window. |
@@ -188,6 +203,11 @@ uv run ruff check .
 uv run ty check
 uv run pytest --cov --cov-report=term-missing
 uv build
+npm ci
+npm run verify
+npm audit --audit-level=high
+npm run build:web
+npm run test:e2e
 ```
 
 Development uses short-lived branches and squash-merged pull requests into protected

{cli_consumption-0.3.3 → cli_consumption-0.4.0}/README.md

@@ -58,6 +58,20 @@ uv run cli-consumption export --output reports
 Open `reports/dashboard.html` locally. It makes no network requests. Detailed CSV
 tables are generated only when `--csv` is passed.
 
+Dashboard development lives in the locked npm workspace under `packages/`. It builds
+provider-neutral ESM analytics, shared React presentation primitives, and deterministic
+React/Tailwind browser assets that Python embeds in the wheel. The React runtime is the
+only offline renderer; installing or using the Python CLI does not require Node.js.
+
+The authenticated persistent dashboard lives in `apps/web/`. It reads the same
+minimized reporting contract through a server-side Next.js BFF: the browser never
+receives a collector credential or a database connection string. Its **Export
+offline** action downloads the exact visible selection as a self-contained detailed or
+share-safe HTML file. For a production
+setup, required environment variables, reverse-proxy constraints, and startup commands
+are documented in the
+[deployment guide](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/deployment.md#run-the-persistent-dashboard).
+
 To collect one provider or select another database:
 
 ```bash
@@ -118,7 +132,8 @@ for ingestion, idempotency, migrations, report limits, and collector behavior.
 | `collect` | Collect local or copied provider data into SQL. |
 | `snapshot` | Create or ingest signed, compressed offline snapshot files. |
 | `sync` | Collect and send metadata-only snapshots to a central API. |
-| `serve` | Run the central collection API. |
+| `upload-db` | Upload validated snapshots reconstructed from a local collect database. |
+| `serve` | Run the scoped central ingestion, reporting, and export API. |
 | `export` | Write the HTML dashboard and optional CSV tables. |
 | `providers` | List provider names and compatibility status. |
 | `retention` | Preview or apply deletion outside a retention window. |
@@ -149,6 +164,11 @@ uv run ruff check .
 uv run ty check
 uv run pytest --cov --cov-report=term-missing
 uv build
+npm ci
+npm run verify
+npm audit --audit-level=high
+npm run build:web
+npm run test:e2e
 ```
 
 Development uses short-lived branches and squash-merged pull requests into protected

{cli_consumption-0.3.3 → cli_consumption-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cli-consumption"
-version = "0.3.3"
+version = "0.4.0"
 description = "Analyze and consolidate AI coding CLI consumption across machines."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -54,6 +54,7 @@ dev = [
   "httpx>=0.27",
   "hypothesis>=6.165.10",
   "pip-audit>=2.10.1",
+  "playwright>=1.55",
   "pre-commit>=4.6.2",
   "psycopg[binary]>=3.2",
   "pytest>=8.3",
@@ -110,6 +111,5 @@ select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "S"]
 "tests/**" = ["S101"]
 "tests/smoke_minimal_install.py" = ["S603", "S607"]
 "tests/test_codex_adapter.py" = ["S608"]
-"tests/test_dashboard_calculations.py" = ["S607"]
 "tests/test_demo.py" = ["S603"]
 "tests/test_packaging.py" = ["S603", "S607"]

{cli_consumption-0.3.3 → cli_consumption-0.4.0}/src/cli_consumption/api.py

@@ -27,6 +27,22 @@ from cli_consumption.models import (
     SnapshotPayload,
     SnapshotValidationError,
 )
+from cli_consumption.reporting_api import (
+    CACHE_HEADERS,
+    EXPORT_TIMEOUT_SECONDS,
+    MAX_CONCURRENT_EXPORTS,
+    MAX_CONCURRENT_REPORTS,
+    MAX_CONVERSATION_PAGE_SIZE,
+    MAX_DASHBOARD_RESPONSE_BYTES,
+    MAX_EXPORT_RESPONSE_BYTES,
+    MAX_FILTER_VALUES,
+    MAX_PAGINATION_SESSION_BYTES,
+    MAX_REPORTING_RECORDS,
+    MAX_REPORTING_SCALAR_BYTES,
+    REPORTING_REQUEST_BYTES,
+    REPORTING_TIMEOUT_SECONDS,
+    install_reporting_routes,
+)
 from cli_consumption.schema import CURRENT_DATABASE_REVISION
 from cli_consumption.storage import (
     create_postgresql_readiness_engine,
@@ -73,6 +89,11 @@ SAFE_ROUTES = frozenset(
         "/ready",
         "/api/v1/capabilities",
         "/api/v1/snapshots",
+        "/api/v1/reporting/dashboard",
+        "/api/v1/reporting/filters",
+        "/api/v1/reporting/conversations",
+        "/api/v1/reporting/conversation",
+        "/api/v1/reporting/export",
     }
 )
 SAFE_EXCEPTION_TYPES = frozenset(
@@ -311,10 +332,13 @@ class SafeExceptionBoundary:
                 error=error,
             )
             if not response_started:
+                headers = {"X-Request-ID": request_id}
+                if str(scope.get("path", "")).startswith("/api/v1/reporting/"):
+                    headers.update(CACHE_HEADERS)
                 response = JSONResponse(
                     status_code=500,
                     content={"detail": "internal_server_error"},
-                    headers={"X-Request-ID": request_id},
+                    headers=headers,
                 )
                 await response(scope, receive, send)
 
@@ -330,11 +354,16 @@ class RequestSizeLimitMiddleware:
         if scope["type"] != "http":
             await self.app(scope, receive, send)
             return
+        maximum = (
+            REPORTING_REQUEST_BYTES
+            if str(scope.get("path", "")).startswith("/api/v1/reporting/")
+            else self.maximum
+        )
         headers = dict(scope.get("headers", []))
         content_length = headers.get(b"content-length")
         if content_length is not None:
             try:
-                if int(content_length) > self.maximum:
+                if int(content_length) > maximum:
                     await self._reject(scope, receive, send)
                     return
             except ValueError:
@@ -348,7 +377,7 @@ class RequestSizeLimitMiddleware:
             message = await receive()
             if message["type"] == "http.request":
                 received += len(message.get("body", b""))
-                if received > self.maximum:
+                if received > maximum:
                     raise RequestTooLarge
             return message
 
@@ -359,14 +388,56 @@ class RequestSizeLimitMiddleware:
 
     @staticmethod
     async def _reject(scope: Scope, receive: Receive, send: Send) -> None:
+        headers = (
+            CACHE_HEADERS
+            if str(scope.get("path", "")).startswith("/api/v1/reporting/")
+            else None
+        )
         response = JSONResponse(
             status_code=413,
             content={"detail": "request_too_large"},
+            headers=headers,
         )
         await response(scope, receive, send)
 
 
-def create_app(engine: Engine, api_token: str | None = None) -> SafeExceptionBoundary:
+def _configured_credentials(
+    api_token: str | None,
+    read_token: str | None,
+    export_token: str | None,
+) -> list[tuple[str, frozenset[str]]]:
+    credentials: list[tuple[str, frozenset[str]]] = []
+    configured_values: set[str] = set()
+    for credential, scopes in (
+        (api_token, frozenset({"ingest"})),
+        (read_token, frozenset({"read"})),
+        (export_token, frozenset({"read", "export"})),
+    ):
+        if credential is None:
+            continue
+        if (
+            not credential
+            or len(credential.encode("utf-8")) > 4_096
+            or any(
+                character.isspace() or ord(character) < 32 for character in credential
+            )
+        ):
+            raise ValueError("invalid API credential configuration")
+        if credential in configured_values:
+            raise ValueError("invalid API credential configuration")
+        configured_values.add(credential)
+        credentials.append((credential, scopes))
+    return credentials
+
+
+def create_app(
+    engine: Engine,
+    api_token: str | None = None,
+    *,
+    read_token: str | None = None,
+    export_token: str | None = None,
+) -> SafeExceptionBoundary:
+    credentials = _configured_credentials(api_token, read_token, export_token)
     initialize_database(engine)
     if engine.dialect.name == "postgresql":
         probe_engine = create_postgresql_readiness_engine(
@@ -386,8 +457,14 @@ def create_app(engine: Engine, api_token: str | None = None) -> SafeExceptionBou
 
     @app.exception_handler(RequestValidationError)
     async def invalid_request(
-        _request: Request, error: RequestValidationError
+        request: Request, error: RequestValidationError
     ) -> JSONResponse:
+        if request.url.path.startswith("/api/v1/reporting/"):
+            return JSONResponse(
+                status_code=422,
+                content={"detail": "invalid_reporting_request"},
+                headers=CACHE_HEADERS,
+            )
         code = (
             "unsupported_schema_version"
             if any(
@@ -403,21 +480,42 @@ def create_app(engine: Engine, api_token: str | None = None) -> SafeExceptionBou
 
     @app.exception_handler(Exception)
     async def internal_error(request: Request, error: Exception) -> JSONResponse:
+        headers = {"X-Request-ID": request.state.request_id}
+        if request.url.path.startswith("/api/v1/reporting/"):
+            headers.update(CACHE_HEADERS)
         return JSONResponse(
             status_code=500,
             content={"detail": "internal_server_error"},
-            headers={"X-Request-ID": request.state.request_id},
+            headers=headers,
         )
 
-    def authorize(authorization: Annotated[str | None, Header()] = None) -> None:
-        if api_token is None:
-            return
-        expected = f"Bearer {api_token}"
-        if authorization is None or not secrets.compare_digest(authorization, expected):
-            raise HTTPException(
-                status_code=status.HTTP_401_UNAUTHORIZED,
-                detail="Missing or invalid bearer token",
-            )
+    def require_scopes(*required: str) -> Any:
+        required_scopes = frozenset(required)
+
+        def authorize(authorization: Annotated[str | None, Header()] = None) -> None:
+            if not credentials:
+                return
+            scheme, separator, supplied = (authorization or "").partition(" ")
+            if not separator or scheme.casefold() != "bearer":
+                supplied = ""
+            matched_scopes: set[str] = set()
+            for credential, scopes in credentials:
+                if secrets.compare_digest(supplied, credential):
+                    matched_scopes.update(scopes)
+            if not matched_scopes:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="authentication_required",
+                    headers=CACHE_HEADERS,
+                )
+            if not required_scopes.issubset(matched_scopes):
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail="authorization_denied",
+                    headers=CACHE_HEADERS,
+                )
+
+        return authorize
 
     @app.get("/health")
     def health() -> dict[str, int | str]:
@@ -446,16 +544,31 @@ def create_app(engine: Engine, api_token: str | None = None) -> SafeExceptionBou
         return JSONResponse(content={"status": "ready"})
 
     @app.get("/api/v1/capabilities")
-    def capabilities() -> dict[str, int | bool]:
+    def capabilities() -> dict[str, Any]:
         return {
             "snapshot_schema_min": MIN_SUPPORTED_SNAPSHOT_SCHEMA,
             "snapshot_schema_max": CURRENT_SNAPSHOT_SCHEMA,
             "max_request_bytes": MAX_REQUEST_BYTES,
             "max_snapshot_records": MAX_SNAPSHOT_RECORDS,
             "idempotent_snapshot_uploads": True,
+            "dashboard_query_versions": [1],
+            "dashboard_dataset_versions": [1],
+            "cursor_versions": [1],
+            "max_reporting_request_bytes": REPORTING_REQUEST_BYTES,
+            "max_reporting_filter_values": MAX_FILTER_VALUES,
+            "max_reporting_records": MAX_REPORTING_RECORDS,
+            "max_reporting_scalar_bytes": MAX_REPORTING_SCALAR_BYTES,
+            "max_dashboard_response_bytes": MAX_DASHBOARD_RESPONSE_BYTES,
+            "max_export_response_bytes": MAX_EXPORT_RESPONSE_BYTES,
+            "max_conversation_page_size": MAX_CONVERSATION_PAGE_SIZE,
+            "max_pagination_session_bytes": MAX_PAGINATION_SESSION_BYTES,
+            "max_concurrent_reporting_reads": MAX_CONCURRENT_REPORTS,
+            "max_concurrent_exports": MAX_CONCURRENT_EXPORTS,
+            "reporting_timeout_seconds": REPORTING_TIMEOUT_SECONDS,
+            "export_timeout_seconds": EXPORT_TIMEOUT_SECONDS,
         }
 
-    @app.post("/api/v1/snapshots", dependencies=[Depends(authorize)])
+    @app.post("/api/v1/snapshots", dependencies=[Depends(require_scopes("ingest"))])
     def receive_snapshot(
         payload: SnapshotPayload,
         idempotency_key: Annotated[
@@ -481,4 +594,11 @@ def create_app(engine: Engine, api_token: str | None = None) -> SafeExceptionBou
             "skipped": result.skipped,
         }
 
+    install_reporting_routes(
+        app,
+        engine,
+        authorize_read=require_scopes("read"),
+        authorize_export=require_scopes("read", "export"),
+    )
+
     return SafeExceptionBoundary(app)