ai-dev-cli-tools 1.2.2__tar.gz → 1.3.0__tar.gz

ai_dev_cli_tools-1.3.0/.dockerignore

@@ -0,0 +1,26 @@
+.git
+.gitignore
+.venv
+venv
+env
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.coverage
+.coverage.*
+build
+dist
+*.egg-info
+.tmp-*
+.ai
+*.db
+*.sqlite
+*.sqlite3
+collector/tests
+tests
+docs
+examples

{ai_dev_cli_tools-1.2.2 → ai_dev_cli_tools-1.3.0}/.github/workflows/ci.yml

@@ -8,8 +8,8 @@ jobs:
   launcher-smoke:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
       - run: python scripts/dev.py --diagnose
@@ -24,8 +24,8 @@ jobs:
         python-version: ["3.11", "3.12", "3.13", "3.14"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
       - run: python -m pip install --upgrade pip
@@ -55,14 +55,14 @@ jobs:
   toolchain-e2e:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: "22"
-      - uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c # v6.0.0
+      - uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
         with:
           distribution: temurin
           java-version: "17"
@@ -84,10 +84,10 @@ jobs:
   agent-corpus:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
       - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
@@ -110,11 +110,11 @@ jobs:
       contents: read
       security-events: write
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
       - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
@@ -126,6 +126,53 @@ jobs:
         run: cat .ai/reports/agent-plan.md >> "$GITHUB_STEP_SUMMARY"
       - name: Upload SARIF to GitHub code scanning
         if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
-        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
+        uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
         with:
           sarif_file: .ai/reports/ai-dev.sarif
+
+  collector-postgres-e2e:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_DB: telemetry
+          POSTGRES_USER: telemetry_user
+          POSTGRES_PASSWORD: test_ci_password_123
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -r collector/requirements.txt -e .
+      - name: Test Alembic migration against PostgreSQL
+        env:
+          DATABASE_URL: postgresql+psycopg://telemetry_user:test_ci_password_123@localhost:5432/telemetry
+        run: |
+          python -m alembic -c collector/alembic.ini upgrade head
+          python -m alembic -c collector/alembic.ini current
+      - name: Build Docker collector image
+        run: docker build -f collector/Dockerfile -t ai-dev-collector:test .
+      - name: Run Docker collector container E2E ingestion test
+        env:
+          DATABASE_URL: postgresql+psycopg://telemetry_user:test_ci_password_123@localhost:5432/telemetry
+          COLLECTOR_URL: http://127.0.0.1:8000
+          PYTHONPATH: .
+        run: |
+          docker run -d --name test-collector --network host \
+            -e DATABASE_URL=postgresql+psycopg://telemetry_user:test_ci_password_123@localhost:5432/telemetry \
+            -e ENVIRONMENT=production \
+            ai-dev-collector:test
+          sleep 3
+          docker logs test-collector
+          python scripts/test_collector_postgres_e2e.py
+          docker stop test-collector
+          docker rm test-collector

{ai_dev_cli_tools-1.2.2 → ai_dev_cli_tools-1.3.0}/.github/workflows/codeql.yml

@@ -17,12 +17,12 @@ jobs:
     name: Analyze Python
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
+      - uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
         with:
           languages: python
           build-mode: none
           queries: security-extended
-      - uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
+      - uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4

{ai_dev_cli_tools-1.2.2 → ai_dev_cli_tools-1.3.0}/.github/workflows/docs.yml

@@ -8,8 +8,8 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
       - run: python -m pip install -c requirements-dev.lock -e ".[dev]"

{ai_dev_cli_tools-1.2.2 → ai_dev_cli_tools-1.3.0}/.github/workflows/publish-pypi.yml

@@ -14,11 +14,11 @@ jobs:
     name: Validate manually promoted release artifacts
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           ref: ${{ github.event.release.tag_name }}
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
       - name: Download artifacts attached by the TestPyPI workflow
@@ -71,11 +71,11 @@ jobs:
     needs: publish-pypi
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           ref: ${{ github.event.release.tag_name }}
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
       - name: Install and smoke test from PyPI through pipx

{ai_dev_cli_tools-1.2.2 → ai_dev_cli_tools-1.3.0}/.github/workflows/release.yml

@@ -13,10 +13,10 @@ jobs:
     name: Build and validate distribution
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
       - name: Validate tag and source version
@@ -65,10 +65,10 @@ jobs:
     needs: publish-testpypi
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
       - name: Install and smoke test from TestPyPI
@@ -84,7 +84,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Download TestPyPI-verified distribution artifact

{ai_dev_cli_tools-1.2.2 → ai_dev_cli_tools-1.3.0}/.gitignore

@@ -18,3 +18,6 @@ dist/
 *.egg-info/
 __pycache__/
 *.py[cod]
+*.db
+*.sqlite
+*.sqlite3

{ai_dev_cli_tools-1.2.2 → ai_dev_cli_tools-1.3.0}/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## Unreleased
+## 1.3.0 - 2026-09-15
+
+- **Community Telemetry**: Add privacy-preserving, voluntary, opt-in telemetry (`OFF`, `BASIC`, `RESEARCH`).
+  - Strict client allowlist schema; source code, prompts, model responses, repository names, file paths, user identifiers, and credentials are never collected.
+  - Transparent user control via `ai-dev telemetry sharing` commands (`status`, `enable basic`, `enable research`, `disable`, `preview`, `flush`).
+  - Bounded local disk queue with automatic retention pruning (max 1,000 events, max 7 days, max 32 KB per event).
+  - Single-flight non-blocking background transport worker.
+  - Support for research-level provider usage metrics collected via MCP tool (`record_usage`) and CLI usage imports.
+- **Production Telemetry Collector**: Introduce the self-contained production backend collector (`collector/`):
+  - Fast, auditable FastAPI ingestion endpoint (`POST /v1/events`) with liveness (`/health`) and readiness (`/ready`) probes.
+  - Fail-closed payload validation and streaming body size enforcement (32 KB limit).
+  - In-memory bounded sliding-window rate limiter with single-IP trusted reverse proxy sanitization.
+  - Idempotent deduplication on primary key `event_id`.
+  - PostgreSQL 16 storage backed by versioned Alembic migrations.
+  - Automated 90-day retention cleanup.
+  - Privacy-safe logging with zero client input, path, or credential leakage.
+  - Configured default HTTPS production endpoint (`https://35.209.177.185.sslip.io/v1/events`).
+- **Validation & Runner Hardening**:
+  - Fix #78: Recognize Node spec/TAP summaries without matching `recoverable` as coverage.
+  - Fix #79: Execute selected `.mjs`/`.cjs` tests, retain broad fallback commands, and fail explicitly when selected tests have no runnable validation plan.
+  - Fix #80: Preserve source prefixes under small content budgets, document content-only `max_chars`, measure actual artifact sizes, and distinguish receipt/content truncation.
+  - Preserve numeric parser error counts and restrict pytest arguments to Python selections.
+  - Prevent `finish` from approving incomplete, blocked, or invalid validation.
+  - Drain cancellable subprocess pipes while waiting and preserve output captured before timeout.
 
 ## 1.2.2 - 2026-09-08
 

{ai_dev_cli_tools-1.2.2 → ai_dev_cli_tools-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ai-dev-cli-tools
-Version: 1.2.2
+Version: 1.3.0
 Summary: Cross-platform CLI helpers that give AI coding agents concise, deterministic development reports.
 Project-URL: Homepage, https://github.com/MatthiasLew/ai-dev-cli-tools
 Project-URL: Repository, https://github.com/MatthiasLew/ai-dev-cli-tools
@@ -21,12 +21,25 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.11
 Requires-Dist: watchdog<7,>=4
+Provides-Extra: collector
+Requires-Dist: alembic>=1.13; extra == 'collector'
+Requires-Dist: fastapi>=0.115; extra == 'collector'
+Requires-Dist: httpx>=0.27; extra == 'collector'
+Requires-Dist: pydantic>=2.8; extra == 'collector'
+Requires-Dist: sqlalchemy>=2.0; extra == 'collector'
+Requires-Dist: uvicorn>=0.30; extra == 'collector'
 Provides-Extra: dev
+Requires-Dist: alembic>=1.13; extra == 'dev'
 Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
+Requires-Dist: fastapi>=0.115; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pydantic>=2.8; extra == 'dev'
 Requires-Dist: pytest>=8.3; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: sqlalchemy>=2.0; extra == 'dev'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
 Provides-Extra: semantic
 Requires-Dist: tree-sitter-language-pack>=0.9; extra == 'semantic'
 Provides-Extra: tokenizers
@@ -54,11 +67,59 @@ artifacts may be removed when no longer needed; cache, runtime, and temporary st
 be safe for `ai-dev` to recreate.
 ```
 
+## Help improve ai-dev
+
+`ai-dev` is being evaluated on real-world coding-agent workflows.
+
+If you want to support development, you can optionally enable privacy-preserving opt-in telemetry without persistent user identifiers.
+
+Community Telemetry is **OFF by default**. Installation never automatically activates it.
+
+### Commands
+
+```bash
+ai-dev telemetry sharing status
+ai-dev telemetry sharing enable basic
+ai-dev telemetry sharing enable research
+ai-dev telemetry sharing disable
+ai-dev telemetry sharing preview
+ai-dev telemetry sharing flush
+```
+
+- **OFF**: Nothing is collected or sent.
+- **BASIC**: Minimal operational metrics (command name, category, outcome, duration bucket, OS family, Python version).
+- **RESEARCH**: BASIC metrics plus model provider usage (model name, token counts, task outcome, repo size bucket).
+
+Default production endpoint: `https://35.209.177.185.sslip.io/v1/events` (can be overridden with `AI_DEV_COMMUNITY_TELEMETRY_ENDPOINT`).
+
+Never shared:
+- source code
+- prompts
+- model responses
+- repository names
+- file names or paths
+- usernames/emails
+- secrets/API keys
+
+Preview what data fields would be shared from your repository:
+
+```bash
+ai-dev telemetry sharing preview --level research
+```
+
+Or view a synthetic example payload:
+
+```bash
+ai-dev telemetry sharing preview --level research --sample
+```
+
+For complete details on data handling, allowed scalar metrics, and local queueing, see [docs/community-telemetry.md](docs/community-telemetry.md).
+
 ## Install
 
 ```bash
 python -m pip install --upgrade pipx
-pipx install ai-dev-cli-tools==1.2.2
+pipx install ai-dev-cli-tools==1.3.0
 ai-dev --help
 ```
 

{ai_dev_cli_tools-1.2.2 → ai_dev_cli_tools-1.3.0}/README.md

@@ -19,11 +19,59 @@ artifacts may be removed when no longer needed; cache, runtime, and temporary st
 be safe for `ai-dev` to recreate.
 ```
 
+## Help improve ai-dev
+
+`ai-dev` is being evaluated on real-world coding-agent workflows.
+
+If you want to support development, you can optionally enable privacy-preserving opt-in telemetry without persistent user identifiers.
+
+Community Telemetry is **OFF by default**. Installation never automatically activates it.
+
+### Commands
+
+```bash
+ai-dev telemetry sharing status
+ai-dev telemetry sharing enable basic
+ai-dev telemetry sharing enable research
+ai-dev telemetry sharing disable
+ai-dev telemetry sharing preview
+ai-dev telemetry sharing flush
+```
+
+- **OFF**: Nothing is collected or sent.
+- **BASIC**: Minimal operational metrics (command name, category, outcome, duration bucket, OS family, Python version).
+- **RESEARCH**: BASIC metrics plus model provider usage (model name, token counts, task outcome, repo size bucket).
+
+Default production endpoint: `https://35.209.177.185.sslip.io/v1/events` (can be overridden with `AI_DEV_COMMUNITY_TELEMETRY_ENDPOINT`).
+
+Never shared:
+- source code
+- prompts
+- model responses
+- repository names
+- file names or paths
+- usernames/emails
+- secrets/API keys
+
+Preview what data fields would be shared from your repository:
+
+```bash
+ai-dev telemetry sharing preview --level research
+```
+
+Or view a synthetic example payload:
+
+```bash
+ai-dev telemetry sharing preview --level research --sample
+```
+
+For complete details on data handling, allowed scalar metrics, and local queueing, see [docs/community-telemetry.md](docs/community-telemetry.md).
+
 ## Install
 
 ```bash
 python -m pip install --upgrade pipx
-pipx install ai-dev-cli-tools==1.2.2
+pipx install ai-dev-cli-tools==1.3.0
 ai-dev --help
 ```
 

ai_dev_cli_tools-1.3.0/collector/.dockerignore

@@ -0,0 +1,27 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+pip-log.txt
+pip-delete-this-directory.txt
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.git
+.gitignore
+.mypy_cache
+.pytest_cache
+.ruff_cache
+tests/
+*.db
+*.sqlite
+.env

ai_dev_cli_tools-1.3.0/collector/.env.example

@@ -0,0 +1,19 @@
+# Community Telemetry Collector Environment Configuration
+# Copy this file to .env and configure your values. Never commit credentials to version control.
+
+# Database connection URL
+# For SQLite (local dev/testing): sqlite:///./telemetry.db
+# For PostgreSQL (production): postgresql+psycopg://username:password@hostname:5432/dbname
+DATABASE_URL=sqlite:///./telemetry.db
+
+# In-memory rate limit per client IP (requests per minute)
+RATE_LIMIT_PER_MINUTE=60
+
+# Raw event retention period (days)
+RETENTION_DAYS=90
+
+# Environment mode (development / production)
+ENVIRONMENT=development
+
+# Server port (default 8000)
+PORT=8000

ai_dev_cli_tools-1.3.0/collector/Dockerfile

@@ -0,0 +1,59 @@
+# Multi-stage minimal production Dockerfile for Community Telemetry Collector
+# Build context MUST be the repository root:
+#   docker build -f collector/Dockerfile -t ai-dev-collector:latest .
+
+FROM python:3.13-slim AS builder
+
+WORKDIR /build
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# 1. Install collector dependencies
+COPY collector/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 2. Build and install ai-dev-cli-tools package for schema validation without external dev tools
+COPY pyproject.toml README.md ./
+COPY src/ ./src/
+RUN pip install --no-cache-dir build hatchling && \
+    python -m build --wheel --no-isolation --outdir /wheels . && \
+    pip install --no-cache-dir --no-deps /wheels/*.whl
+
+
+FROM python:3.13-slim AS runner
+
+# Security: Create non-root user
+RUN groupadd -r appuser && useradd -r -g appuser -d /app -s /sbin/nologin -c "Docker image user" appuser
+
+WORKDIR /app
+
+# Copy virtualenv from builder
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+ENV PYTHONPATH="/app"
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Copy application source & Alembic migrations
+COPY collector/app/ /app/collector/app/
+COPY collector/alembic/ /app/collector/alembic/
+COPY collector/alembic.ini /app/collector/alembic.ini
+
+# Set ownership to non-root user
+RUN chown -R appuser:appuser /app
+
+USER appuser
+
+EXPOSE 8000
+
+# Health check without curl dependency (probes liveness endpoint)
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+# Start uvicorn with access logging disabled (privacy preservation for client IPs)
+CMD ["uvicorn", "collector.app.main:app", "--host", "0.0.0.0", "--port", "8000", "--no-access-log"]

ai_dev_cli_tools-1.3.0/collector/README.md

@@ -0,0 +1,115 @@
+# ai-dev Community Telemetry Collector
+
+Lightweight, privacy-preserving, fail-closed production collector for `ai-dev` Community Telemetry (`schema_version = 1`).
+
+---
+
+## Key Privacy & Security Guarantees
+
+1. **No User Tracking**: Does not assign, store, or generate user IDs, device fingerprints, or machine identifiers.
+2. **No Persistent IP Logging**: IP addresses are used solely in transient in-memory token buckets for rate limiting and are never written to disk or database. Access logs must be disabled or sanitized at the edge reverse proxy.
+3. **Strict Trusted Proxy Model & Single-IP Defense-in-Depth**: By default, `TRUST_PROXY_HEADERS=false` and client IP is extracted from the direct peer (`request.client.host`). `X-Forwarded-For` is only parsed if explicitly enabled and the connecting peer IP matches `TRUSTED_PROXY_IPS` networks. Furthermore, the reverse proxy must sanitize `X-Forwarded-For: $remote_addr;` and the collector strictly accepts only a single forwarded IP (any multi-value comma-separated header is rejected and falls back to peer IP).
+4. **Hard-Bounded Rate Limiter**: Rate limiter state is backed by an `OrderedDict` with LRU and stale eviction, guaranteeing `len(_buckets) <= MAX_ENTRIES` (bounds: 100 to 1,000,000) under adversarial key generation.
+5. **Streaming Body Limit**: Request body is read incrementally via streaming chunks. Payloads exceeding 32 KB (`32,768 bytes`) are aborted immediately with `413 Content Too Large` without full buffer allocation.
+6. **Explicit Schema Migrations**: Managed by Alembic (`collector/alembic/`). Production startup never performs silent `create_all()` mutations.
+7. **No Code, Prompts, or Paths**: Strict fail-closed schema validation automatically rejects any payload containing unknown keys, file paths, code snippets, or prompt text.
+8. **Privacy-Safe Application Logging**: Application logs never record raw payload contents, field values, model names, paths, emails, client IPs, or database credentials. Validation errors log controlled category codes only, and storage failures log exception type names only.
+9. **90-Day Raw Retention**: Automated retention script purges raw records older than 90 days based strictly on server `received_at` timestamp.
+10. **Idempotent Ingestion**: `event_id` is an RFC 4122 UUIDv4 used exclusively as a deduplication primary key (`ON CONFLICT DO NOTHING`). Duplicate submissions return `200 OK` (`{"status": "accepted", "duplicate": true}`) without duplicate writes.
+
+---
+
+## API Endpoints
+
+### 1. Liveness Probe: `GET /health`
+Confirms the collector process is running and responsive.
+- **Response** (`200 OK`):
+  ```json
+  {
+    "status": "ok",
+    "schema_version": 1
+  }
+  ```
+
+### 2. Readiness Probe: `GET /ready`
+Confirms connectivity to the backing database.
+- **Response** (`200 OK`):
+  ```json
+  {
+    "status": "ready",
+    "database": "connected"
+  }
+  ```
+- **Error Response** (`503 Service Unavailable`):
+  ```json
+  {
+    "status": "degraded",
+    "error": "database_unavailable"
+  }
+  ```
+
+### 3. Ingest Event: `POST /v1/events`
+- **Headers**:
+  - `Content-Type: application/json`
+  - `X-Content-Type-Options: nosniff` (applied to response)
+- **Limits**: Body size $\le 32\text{ KB}$, 60 req/min per transient client IP.
+- **Success Response** (`202 Accepted`):
+  ```json
+  {
+    "status": "accepted",
+    "duplicate": false
+  }
+  ```
+- **Duplicate Response** (`200 OK`):
+  ```json
+  {
+    "status": "accepted",
+    "duplicate": true
+  }
+  ```
+- **Error Responses**:
+  - `400 Bad Request`: `{"status": "rejected", "error": "validation_failed"}`
+  - `413 Content Too Large`: `{"status": "rejected", "error": "payload_too_large"}`
+  - `415 Unsupported Media Type`: `{"status": "rejected", "error": "unsupported_media_type"}`
+  - `429 Too Many Requests`: `{"status": "rejected", "error": "rate_limited"}` (with `Retry-After` header)
+  - `500 Server Error`: `{"status": "error", "error": "storage_failed"}`
+
+---
+
+## Local Development vs. Production
+
+### Local Development (SQLite or Docker Compose)
+In development, SQLite is permitted and the database can be initialized automatically or via Alembic:
+```bash
+# 1. Run migrations locally
+python -m alembic -c collector/alembic.ini upgrade head
+
+# 2. Run collector locally
+uvicorn collector.app.main:app --host 127.0.0.1 --port 8000
+```
+Or with Docker Compose:
+```bash
+docker compose -f collector/docker-compose.yml up -d --build
+```
+
+### Production Deployment (PostgreSQL Required)
+In production (`ENVIRONMENT=production`):
+- `DATABASE_URL` **must** be a PostgreSQL connection string (`postgresql+psycopg://...`). SQLite will fail fast on startup.
+- Migrations **must** be executed before launching the collector:
+  ```bash
+  alembic -c collector/alembic.ini upgrade head
+  ```
+- Set `TRUST_PROXY_HEADERS=true` only if deployed behind a verified reverse proxy (e.g. Caddy / Nginx) and configure `TRUSTED_PROXY_IPS`.
+
+---
+
+## Running Retention Cleanup
+
+To purge events older than 90 days:
+```bash
+python -m collector.app.retention --days 90
+```
+Dry run mode (preview without deletion):
+```bash
+python -m collector.app.retention --days 90 --dry-run
+```

ai_dev_cli_tools-1.3.0/collector/__init__.py

@@ -0,0 +1 @@
+"""Community Telemetry Collector package."""