quotalens 1.0__tar.gz

quotalens-1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,54 @@
+---
+name: Bug report
+about: Something QuotaLens did that it should not have
+labels: bug
+---
+
+## Before you paste anything
+
+**`quotalens probe` output is your account's data.** It never contains your
+session cookie, and UUID-shaped values are masked by default — but only by
+default. Do not paste output from `probe --no-redact` or from
+`/api/export.json?table=samples&raw=1`; both are unmasked on purpose.
+
+If you need to show a payload, `quotalens probe` (no flags) is the safe form.
+If you are unsure whether something identifies you, leave it out and say so; a
+missing field is easier to ask for than a leaked one is to take back.
+
+Never paste your cookie. Nobody debugging this will ever need it. If you think
+you have pasted one anywhere, sign out of claude.ai on all devices, which
+invalidates it.
+
+## What happened
+
+<!-- What you saw, and what you expected instead. -->
+
+## How to reproduce
+
+<!-- The exact commands, and the URL if it was the dashboard. Every view is a
+     URL, so pasting the address bar captures the range, the lookback and which
+     series were hidden. -->
+
+## Environment
+
+- QuotaLens version: <!-- quotalens --version -->
+- OS and version:
+- Installed with: <!-- pipx / uvx / from source -->
+- Python: <!-- python3 --version -->
+
+## Collector state
+
+<!-- `quotalens status` output. It contains your window percentages and reset
+     times but no identifiers. Trim it if you would rather not share those. -->
+
+```
+```
+
+## Anything in the log
+
+<!-- `quotalens logs -n 50`. The cookie is redacted from logs by design; if you
+     ever find one in there, that is itself the bug and it is a serious one —
+     please report it privately rather than in a public issue. -->
+
+```
+```

quotalens-1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,7 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security issue
+    url: https://github.com/amitshcc/quotalens/security/advisories/new
+    about: >-
+      Anything involving the session cookie, credential storage or redaction.
+      Report it privately, not in a public issue. See SECURITY.md.

quotalens-1.0/.github/ISSUE_TEMPLATE/endpoint_drift.md

@@ -0,0 +1,38 @@
+---
+name: Endpoint drift
+about: QuotaLens says the response shape changed, or a number looks wrong
+labels: drift
+---
+
+## Before you paste anything
+
+`quotalens probe` masks UUID-shaped values by default. Use it without
+`--no-redact`, and do not paste raw sample exports. See the bug report template
+for the longer version; the short version is that the payload is your account's
+data and the safe form is `quotalens probe` with no flags.
+
+## What the dashboard said
+
+<!-- "shape drifted", "could not be parsed", a window missing, a percentage that
+     disagrees with claude.ai's own Settings page, and so on. -->
+
+## The parsed section of `quotalens probe`
+
+<!-- The `== parsed ==` block alone is often enough, and it contains no
+     identifiers at all. Start with that. -->
+
+```
+```
+
+## The raw payload, if the parsed section is not enough
+
+<!-- `quotalens probe` (masked). Delete anything you would rather not share;
+     the top-level key names are the part that matters for drift. -->
+
+```
+```
+
+## What claude.ai's own Settings → Usage page showed at the same moment
+
+<!-- A number to compare against. A screenshot with the account details cropped
+     out is fine. -->

quotalens-1.0/.github/workflows/ci.yml

@@ -0,0 +1,136 @@
+name: CI
+
+# Cross-platform is a headline claim in the README. Until this is green on all
+# three runners it stays a claim, and the README says "Windows untested".
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m pip install "ruff==0.16.*"
+      - run: ruff check src tests qa
+      - run: ruff format --check src tests qa
+
+  # Whether the favicon draws, and what size a cell computes to, are questions
+  # about SVG and CSS rather than about the operating system, so they run once
+  # rather than on all six matrix jobs. A separate job because these are the only
+  # things here that need a browser.
+  render:
+    name: what a browser actually renders
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[test,browser]"
+      - run: python -m playwright install --with-deps chromium
+      - run: python -m pytest tests/test_favicon_render.py tests/test_rendered_type.py -q
+
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false  # a Windows failure must not hide a Linux one
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Build the wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel
+
+      # Installing the wheel rather than the source tree is the point: it is what
+      # a user gets from pipx, and it catches anything missing from the package
+      # data (the stylesheet, the scripts, the favicon).
+      - name: Install from the wheel
+        shell: bash
+        run: |
+          WHEEL=$(ls dist/*.whl)
+          python -m pip install "${WHEEL}[test]"
+
+      - name: Unit tests
+        run: python -m pytest -q
+
+      # The tests mock every HTTP call, so nothing above proves the process can
+      # actually start, poll, write rows and serve them on this platform.
+      - name: Smoke (server against a fake upstream, then the CLI lifecycle)
+        run: python qa/smoke.py
+
+      # Registering a scheduled task is the one thing unit tests cannot prove: the
+      # XML either satisfies Task Scheduler's schema or it does not, and only
+      # Windows can say. Install for real, confirm the task exists, then remove it.
+      # pwsh, not bash: Git Bash rewrites a leading-slash argument into a path, so
+      # `schtasks /Query` would arrive as `schtasks C:/Program Files/Git/Query`.
+      - name: Auto-start at login registers and unregisters (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $data = Join-Path $env:RUNNER_TEMP "svc"
+          python -m quotalens --data-dir $data service install --interval 300
+          if ($LASTEXITCODE -ne 0) { throw "service install failed" }
+          schtasks /Query /TN QuotaLens
+          if ($LASTEXITCODE -ne 0) { throw "install reported success but no task was registered" }
+          python -m quotalens --data-dir $data service status
+          python -m quotalens --data-dir $data service uninstall
+          if ($LASTEXITCODE -ne 0) { throw "service uninstall failed" }
+          schtasks /Query /TN QuotaLens 2>$null
+          if ($LASTEXITCODE -eq 0) { throw "the task survived uninstall" }
+          Write-Host "registered, queried and removed"
+          exit 0  # the query above is meant to fail; without this the step inherits its code
+
+      - name: Package contents
+        shell: bash
+        run: |
+          python - <<'PY'
+          from importlib import resources
+          web = resources.files("quotalens.web")
+          # An asset that works from the source tree and is missing from the
+          # installed wheel is exactly what this step exists to catch.
+          for name in (
+              "tokens.css", "app.css", "app.js", "chart.js",
+              "favicon.svg", "boost-rocket.svg",
+              "mark.png",  # the notification icon
+          ):
+              data = web.joinpath(name).read_bytes()
+              assert data, name
+              print(f"{name}: {len(data)} bytes")
+
+          # Vendor marks are optional by design -- a missing file renders the row
+          # with the name alone -- so this asserts the *directory* ships, and
+          # reports whichever marks are present.
+          from quotalens.status import VENDORS
+          vendor = web.joinpath("vendor")
+          assert vendor.is_dir(), "quotalens/web/vendor/ is missing from the wheel"
+          for v in VENDORS:
+              if not v.logo:
+                  continue
+              path = vendor.joinpath(v.logo)
+              state = f"{len(path.read_bytes())} bytes" if path.is_file() else "absent (name only)"
+              print(f"vendor/{v.logo}: {state}")
+          PY

quotalens-1.0/.github/workflows/release.yml

@@ -0,0 +1,125 @@
+name: Release
+
+# Publishing is the owner's action, so this workflow does nothing on its own:
+# it fires on a tag you push, or on a manual dispatch aimed at TestPyPI.
+#
+# No API token anywhere. Both jobs mint a short-lived credential per run through
+# OIDC (PyPI "trusted publishing"), which is why each has `id-token: write` and
+# names an environment. A token in `secrets.*` would work and would be worse: it
+# does not expire, and it is one leaked log line from being someone else's.
+#
+# A manual dispatch can only reach TestPyPI. Pushing a tag is the only route to
+# PyPI, because that is the only condition under which the tag/__version__/wheel
+# agreement check runs.
+#
+# Before the first real tag, publish once to TestPyPI via workflow_dispatch. The
+# upload is irreversible and a filename can never be reused, even after a
+# deletion — so a bad wheel on PyPI burns `quotalens-1.0-py3-none-any.whl`
+# forever.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        required: true
+        default: testpypi
+        type: choice
+        # TestPyPI only. A dispatch can run from any ref, and the step that
+        # checks the tag, pyproject.toml and __version__ against each other
+        # is gated on refs/tags/v* -- so a dispatch to PyPI would be an
+        # irreversible upload with no version check at all. The tag is the
+        # only route to PyPI.
+        options: [testpypi]
+
+permissions:
+  contents: read
+
+jobs:
+  # The tag is not evidence. Build from the tagged tree, then run the same
+  # checks CI runs, against the artifact that is about to be uploaded rather
+  # than against the source tree.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - run: python -m pip install --upgrade pip build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      # `twine check` reads the metadata PyPI will read. It catches a README
+      # that does not render before the upload does, which is the one class of
+      # error you cannot take back.
+      - name: Check the metadata
+        run: python -m twine check dist/*
+
+      # The version in the tag, the version in pyproject.toml and the version
+      # the installed package reports must be one number. They have disagreed
+      # before, and a release that says 1.0 in two places and 0.1.0 in the
+      # third is worse than no release.
+      - name: The tag, the metadata and __version__ agree
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          WHEEL=$(ls dist/*.whl)
+          python -m pip install "${WHEEL}"
+          PKG=$(python -c "import quotalens; print(quotalens.__version__)")
+          echo "tag=$TAG  package=$PKG  wheel=$WHEEL"
+          [ "$TAG" = "$PKG" ] || { echo "::error::tag v$TAG does not match __version__ $PKG"; exit 1; }
+          case "$WHEEL" in *"quotalens-$TAG-"*) ;; *) echo "::error::wheel filename does not carry $TAG"; exit 1;; esac
+
+      # A wheel that installs but cannot start is what CI's smoke test exists to
+      # catch. Run it here too: this is the artifact being published, not a
+      # rebuild of it.
+      - name: Smoke the built wheel
+        run: |
+          python -m pip install "$(ls dist/*.whl)[test]"
+          python -m pytest -q
+          python qa/smoke.py
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  # Reachable only by pushing a tag, which is also the only condition under
+  # which the version-agreement step above runs. See the dispatch input.
+  pypi:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi        # add a required reviewer on this environment, so a
+                             # tag alone cannot publish without you clicking
+    permissions:
+      id-token: write        # OIDC: this is the whole credential story
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

quotalens-1.0/.gitignore

@@ -0,0 +1,46 @@
+# secrets and local state — never commit
+.env
+.env.*
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+*.sqlite
+*.sqlite3
+probe-output*.json
+scratch/
+
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# editors / os
+.DS_Store
+.idea/
+.vscode/
+
+# local reference checkouts, never committed
+TEMP/
+
+# working prompts and the local agent definition — kept out of the public repo
+# on purpose. The versioned copies live in the private quotalens-web repo under
+# prompts/. Removed from history on 2026-09-06; see that repo for the record.
+design/prompts/
+docs/prompts/
+.claude/
+CLAUDE_CODE_PROMPT.md
+docs/V0.1.0-PROMPT.md
+docs/AUDIT-*.md
+docs/SECURITY-AUDIT-*.md
+docs/LAUNCH-READINESS-*.md
+docs/LAUNCH-TODO.md

quotalens-1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.