cli-consumption 0.3.0__tar.gz → 0.3.1__tar.gz

{cli_consumption-0.3.0 → cli_consumption-0.3.1}/CHANGELOG.md

@@ -6,6 +6,43 @@ use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-08-31
+
+### Changed
+
+- Python 3.11 is now supported and tested alongside Python 3.12, 3.13, and 3.14.
+- Collection errors now distinguish provider limits, incompatible formats, invalid
+  snapshots, and unexpected adapter failures with privacy-safe human messages and
+  deterministic JSON codes.
+- A pinned, privacy-preserving single-host production deployment example now covers
+  the central collector, PostgreSQL, and automatic TLS proxy operations.
+- The README now leads with a reproducible synthetic dashboard preview and routes
+  operational and provider-qualification detail to dedicated guides.
+- CI now performs scheduled Python security, locked dependency, and offline workflow
+  audits; third-party actions are pinned to immutable commits with least privileges.
+- Provider adapters now carry auditable format qualification metadata backed by
+  synthetic fixtures, with a weekly check that flags qualifications older than 90
+  days and homogeneous privacy-minimized compatibility criteria.
+- Linear is now the source of truth for new repository tasks and their progress, while
+  the roadmap remains focused on durable product direction.
+- Dashboard token totals now include conversation aggregates and latest-context
+  snapshots for conversations overlapping the selected period, with explicit labels
+  distinguishing them from additive usage.
+- Dashboard selection, period, aggregation, percentile, and comparison calculations
+  now use an independently tested JavaScript contract embedded in the offline report.
+- Each detailed CSV export now uses a synchronized temporary file and atomic
+  replacement, preserving that table's previous file when generation fails early.
+- Multi-provider sync now reuses one HTTP client, negotiates capabilities once, and
+  performs bounded idempotent retries when the collector advertises replay receipts.
+- Sync automation now supports strict preflight refusal and deterministic JSON with
+  malformed/duplicate diagnostics, explicit partial success, and generic remote
+  errors that do not expose response or provider content.
+
+### Fixed
+
+- Reject timezone-naive provider timestamps instead of interpreting them in the host
+  timezone.
+
 ## [0.3.0] - 2026-08-29
 
 ### Added
@@ -65,7 +102,8 @@ 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.0...HEAD
+[Unreleased]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.3.1...HEAD
+[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
 [0.2.1]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/Guillaume-Lombardo/cli-consumption/compare/v0.1.1...v0.2.0

cli_consumption-0.3.1/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: cli-consumption
+Version: 0.3.1
+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
+Project-URL: Changelog, https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Guillaume-Lombardo/cli-consumption/issues
+Project-URL: Repository, https://github.com/Guillaume-Lombardo/cli-consumption.git
+Author-email: Guillaume Lombardo <lombardo.guillaume@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai,cli,codex,observability,tokens,usage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.14
+Requires-Dist: pydantic>=2.10
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: typer>=0.15
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: uvicorn>=0.34; extra == 'server'
+Provides-Extra: sync
+Requires-Dist: httpx>=0.27; extra == 'sync'
+Description-Content-Type: text/markdown
+
+# CLI Consumption
+
+CLI Consumption turns local AI coding CLI metadata into one private, self-contained
+view of models, tokens, tools, conversations, turns, context pressure, and workflow
+health. It can consolidate trusted offline copies from several machines or send
+metadata-only snapshots to a central collector.
+
+It never stores prompts, responses, tool arguments, credentials, or raw provider
+events. Local token counters are usage metadata, not billing records. Read the
+[privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
+before sharing a database or report.
+
+[![Synthetic CLI Consumption dashboard](https://raw.githubusercontent.com/Guillaume-Lombardo/cli-consumption/main/docs/demo/dashboard.png)](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/demo/dashboard.html)
+
+The preview and
+[self-contained demo dashboard](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/demo/dashboard.html)
+contain only
+deterministic synthetic records. Rebuild the HTML with:
+
+```bash
+uv run python docs/demo/generate.py
+```
+
+The generator never reads provider directories and creates its temporary SQLite
+database outside the repository. The demo HTML, image, documentation, tests, and other
+repository assets are excluded from Python distribution artifacts.
+
+## Installation
+
+CLI Consumption requires Python 3.11 or newer. Run it directly from PyPI with `uv`:
+
+```bash
+uv tool run cli-consumption providers
+```
+
+The default package covers local collection, SQLite storage, and exports. Install only
+the optional runtime capabilities you use:
+
+- `cli-consumption[sync]` for the sync client;
+- `cli-consumption[server]` for the collector service;
+- `cli-consumption[postgres]` for PostgreSQL.
+
+Extras can be combined, for example `cli-consumption[server,postgres]` on a central
+collector.
+
+## Quick start
+
+From a checkout, detect supported local CLIs, collect their metadata, and create an
+offline dashboard:
+
+```bash
+uv sync --all-extras
+uv run cli-consumption collect --provider all
+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.
+
+To collect one provider or select another database:
+
+```bash
+uv run cli-consumption collect --provider codex --database usage.sqlite
+```
+
+Use `--source [LABEL=]PATH` for trusted offline copies and repeated
+`--project NAME=PATH_PREFIX` mappings for stable project labels. See the
+[usage and operations guide](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
+for multi-machine collection, reporting,
+PostgreSQL, retention, synchronization, readiness, and automation.
+
+## Supported CLIs
+
+The current registry supports Aider, Amazon Q Developer CLI, Amp, Claude Code, Cline,
+Codex, Continue, Crush, Cursor CLI, Gemini CLI, GitHub Copilot CLI, Goose, Grok Build,
+Kilo Code, Kimi Code CLI, Mistral Vibe CLI, OpenCode, OpenHands CLI, Pi, Plandex, and
+Qwen Code.
+
+Provider formats are internal and can change without notice. Exact source locations,
+token semantics, extraction limits, synthetic qualification fixtures, provenance, and
+known gaps live in the
+[provider support ledger](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/provider-support.md).
+Inspect the
+local registry without exposing paths or content:
+
+```bash
+uv run cli-consumption providers --json
+```
+
+## Essential limits
+
+- Provider files are untrusted. Collection enforces discovery, file, line, SQLite row,
+  structured-field, and total normalized-record limits; direct provider-file symlinks
+  are refused.
+- `collect --strict` and `sync --strict` refuse a batch when any provider skipped
+  malformed records. Collection distinguishes `provider_limit_exceeded`,
+  `provider_format_incompatible`, `invalid_snapshot`, and the unexpected-failure
+  fallback `provider_collection_failed`; machine-readable results use these fixed codes
+  without paths, payloads, response bodies, tokens, or exception text.
+- Dashboards are self-contained and network-free. Share-safe mode pseudonymizes
+  labels, groups tools, rounds timestamps, and hides small cohorts, but still exposes
+  aggregate work patterns.
+- CSV and normalized databases remain detailed private operational data. Never treat a
+  technically completed turn as a measure of quality or productivity.
+- Central collection requires TLS, token rotation, backups, limits, monitoring, and a
+  reverse proxy. The application does not replace those operator controls.
+
+See [Privacy](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
+for the exact data boundary and
+[Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md)
+for ingestion, idempotency, migrations, report limits, and collector behavior.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `collect` | Collect local or copied provider data into SQL. |
+| `sync` | Collect and send metadata-only snapshots to a central API. |
+| `serve` | Run the central collection 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. |
+
+Run `uv run cli-consumption COMMAND --help` for every option. The
+[usage guide](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
+contains copy-ready examples.
+
+## Documentation
+
+- [Usage and operations](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
+- [Production deployment](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/deployment.md)
+- [Provider support and qualification](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/provider-support.md)
+- [Privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
+- [Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md)
+- [Roadmap](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/roadmap.md)
+- [Contributing](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CONTRIBUTING.md)
+- [Security policy](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/SECURITY.md)
+
+## Development
+
+```bash
+uv sync --all-extras --all-groups
+uv run pre-commit install
+uv run pre-commit run --all-files
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest --cov --cov-report=term-missing
+uv build
+```
+
+Development uses short-lived branches and squash-merged pull requests into protected
+`main`. Read
+[CONTRIBUTING.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CONTRIBUTING.md)
+and [AGENTS.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/AGENTS.md)
+before changing the project.
+
+## License
+
+Licensed under the
+[Apache License 2.0](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/LICENSE).

cli_consumption-0.3.1/README.md

@@ -0,0 +1,161 @@
+# CLI Consumption
+
+CLI Consumption turns local AI coding CLI metadata into one private, self-contained
+view of models, tokens, tools, conversations, turns, context pressure, and workflow
+health. It can consolidate trusted offline copies from several machines or send
+metadata-only snapshots to a central collector.
+
+It never stores prompts, responses, tool arguments, credentials, or raw provider
+events. Local token counters are usage metadata, not billing records. Read the
+[privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
+before sharing a database or report.
+
+[![Synthetic CLI Consumption dashboard](https://raw.githubusercontent.com/Guillaume-Lombardo/cli-consumption/main/docs/demo/dashboard.png)](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/demo/dashboard.html)
+
+The preview and
+[self-contained demo dashboard](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/demo/dashboard.html)
+contain only
+deterministic synthetic records. Rebuild the HTML with:
+
+```bash
+uv run python docs/demo/generate.py
+```
+
+The generator never reads provider directories and creates its temporary SQLite
+database outside the repository. The demo HTML, image, documentation, tests, and other
+repository assets are excluded from Python distribution artifacts.
+
+## Installation
+
+CLI Consumption requires Python 3.11 or newer. Run it directly from PyPI with `uv`:
+
+```bash
+uv tool run cli-consumption providers
+```
+
+The default package covers local collection, SQLite storage, and exports. Install only
+the optional runtime capabilities you use:
+
+- `cli-consumption[sync]` for the sync client;
+- `cli-consumption[server]` for the collector service;
+- `cli-consumption[postgres]` for PostgreSQL.
+
+Extras can be combined, for example `cli-consumption[server,postgres]` on a central
+collector.
+
+## Quick start
+
+From a checkout, detect supported local CLIs, collect their metadata, and create an
+offline dashboard:
+
+```bash
+uv sync --all-extras
+uv run cli-consumption collect --provider all
+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.
+
+To collect one provider or select another database:
+
+```bash
+uv run cli-consumption collect --provider codex --database usage.sqlite
+```
+
+Use `--source [LABEL=]PATH` for trusted offline copies and repeated
+`--project NAME=PATH_PREFIX` mappings for stable project labels. See the
+[usage and operations guide](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
+for multi-machine collection, reporting,
+PostgreSQL, retention, synchronization, readiness, and automation.
+
+## Supported CLIs
+
+The current registry supports Aider, Amazon Q Developer CLI, Amp, Claude Code, Cline,
+Codex, Continue, Crush, Cursor CLI, Gemini CLI, GitHub Copilot CLI, Goose, Grok Build,
+Kilo Code, Kimi Code CLI, Mistral Vibe CLI, OpenCode, OpenHands CLI, Pi, Plandex, and
+Qwen Code.
+
+Provider formats are internal and can change without notice. Exact source locations,
+token semantics, extraction limits, synthetic qualification fixtures, provenance, and
+known gaps live in the
+[provider support ledger](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/provider-support.md).
+Inspect the
+local registry without exposing paths or content:
+
+```bash
+uv run cli-consumption providers --json
+```
+
+## Essential limits
+
+- Provider files are untrusted. Collection enforces discovery, file, line, SQLite row,
+  structured-field, and total normalized-record limits; direct provider-file symlinks
+  are refused.
+- `collect --strict` and `sync --strict` refuse a batch when any provider skipped
+  malformed records. Collection distinguishes `provider_limit_exceeded`,
+  `provider_format_incompatible`, `invalid_snapshot`, and the unexpected-failure
+  fallback `provider_collection_failed`; machine-readable results use these fixed codes
+  without paths, payloads, response bodies, tokens, or exception text.
+- Dashboards are self-contained and network-free. Share-safe mode pseudonymizes
+  labels, groups tools, rounds timestamps, and hides small cohorts, but still exposes
+  aggregate work patterns.
+- CSV and normalized databases remain detailed private operational data. Never treat a
+  technically completed turn as a measure of quality or productivity.
+- Central collection requires TLS, token rotation, backups, limits, monitoring, and a
+  reverse proxy. The application does not replace those operator controls.
+
+See [Privacy](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
+for the exact data boundary and
+[Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md)
+for ingestion, idempotency, migrations, report limits, and collector behavior.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `collect` | Collect local or copied provider data into SQL. |
+| `sync` | Collect and send metadata-only snapshots to a central API. |
+| `serve` | Run the central collection 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. |
+
+Run `uv run cli-consumption COMMAND --help` for every option. The
+[usage guide](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
+contains copy-ready examples.
+
+## Documentation
+
+- [Usage and operations](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/usage.md)
+- [Production deployment](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/deployment.md)
+- [Provider support and qualification](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/provider-support.md)
+- [Privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
+- [Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md)
+- [Roadmap](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/roadmap.md)
+- [Contributing](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CONTRIBUTING.md)
+- [Security policy](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/SECURITY.md)
+
+## Development
+
+```bash
+uv sync --all-extras --all-groups
+uv run pre-commit install
+uv run pre-commit run --all-files
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest --cov --cov-report=term-missing
+uv build
+```
+
+Development uses short-lived branches and squash-merged pull requests into protected
+`main`. Read
+[CONTRIBUTING.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CONTRIBUTING.md)
+and [AGENTS.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/AGENTS.md)
+before changing the project.
+
+## License
+
+Licensed under the
+[Apache License 2.0](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/LICENSE).

{cli_consumption-0.3.0 → cli_consumption-0.3.1}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cli-consumption"
-version = "0.3.0"
+version = "0.3.1"
 description = "Analyze and consolidate AI coding CLI consumption across machines."
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.11"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 authors = [{ name = "Guillaume Lombardo", email = "lombardo.guillaume@gmail.com" }]
@@ -17,6 +17,7 @@ classifiers = [
   "Environment :: Console",
   "License :: OSI Approved :: Apache Software License",
   "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
@@ -49,6 +50,7 @@ dev = [
   "fastapi>=0.115",
   "httpx>=0.27",
   "hypothesis>=6.165.10",
+  "pip-audit>=2.10.1",
   "pre-commit>=4.6.2",
   "psycopg[binary]>=3.2",
   "pytest>=8.3",
@@ -56,6 +58,7 @@ dev = [
   "ruff>=0.11",
   "ty>=0.0.74",
   "uvicorn>=0.34",
+  "zizmor>=1.29.0",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -86,10 +89,24 @@ show_missing = true
 
 [tool.ruff]
 line-length = 88
-target-version = "py312"
+target-version = "py311"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "S"]
 
 [tool.ruff.lint.per-file-ignores]
-"src/cli_consumption/dashboard.py" = ["E501"]
+"src/cli_consumption/adapters/_shared.py" = ["S608"]
+"src/cli_consumption/adapters/cline.py" = ["S608"]
+"src/cli_consumption/adapters/crush.py" = ["S608"]
+"src/cli_consumption/adapters/kilo.py" = ["S608"]
+"src/cli_consumption/adapters/opencode.py" = ["S608"]
+"src/cli_consumption/adapters/registry.py" = ["S105", "S106"]
+"src/cli_consumption/api.py" = ["S608"]
+"src/cli_consumption/cli.py" = ["S107"]
+"src/cli_consumption/dashboard.py" = ["E501", "S608"]
+"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.0 → cli_consumption-0.3.1}/src/cli_consumption/adapters/_shared.py

@@ -144,7 +144,10 @@ def timestamp(value: object) -> datetime | None:
             scale = 1000 if abs(value) > 10_000_000_000 else 1
             return datetime.fromtimestamp(value / scale, UTC)
         if isinstance(value, str) and value:
-            return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(UTC)
+            parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+            if parsed.tzinfo is None or parsed.utcoffset() is None:
+                return None
+            return parsed.astimezone(UTC)
     except (OSError, OverflowError, ValueError):
         pass
     return None