cloudexit 2.0: platform uploads via API v2, out-of-repo configuration, a versioned catalogue, and a restructured, hardened codebase

.gitattributes

@@ -0,0 +1,7 @@
+# The definition copy is compared by file hash, so it must not get CRLF line endings
+docs/api-v2/** text eol=lf
+
+# The bundled driver.js files are checked against a pinned hash and shipped
+# unmodified, so no line ending conversion may touch them
+cloudexit/assets/js/** -text
+cloudexit/assets/css/driver.css -text

.github/workflows/pr-checks.yml

@@ -29,7 +29,7 @@ jobs:
           pip install -r requirements-dev.txt
 
       - name: Ruff
-        run: ruff check main.py core utils tests
+        run: ruff check main.py cloudexit tests
 
   check-types:
     if: github.event.pull_request.draft == false
@@ -49,18 +49,28 @@ jobs:
           pip install -r requirements-dev.txt
 
       - name: Black
-        run: black --check main.py core utils tests
+        run: black --check main.py cloudexit tests
 
   check-tests:
     if: github.event.pull_request.draft == false
-    runs-on: ubuntu-latest
+    name: tests (${{ matrix.os }}, Python ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, python: "3.12" }
+          - { os: ubuntu-latest, python: "3.13" }
+          - { os: ubuntu-latest, python: "3.14", coverage: true }
+          - { os: macos-latest, python: "3.14" }
+          - { os: windows-latest, python: "3.14" }
     steps:
       - uses: actions/checkout@v5
 
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: ${{ matrix.python }}
           cache: pip
 
       - name: Install dependencies
@@ -69,4 +79,154 @@ jobs:
           pip install -r requirements-dev.txt
 
       - name: Unit tests
-        run: python -m unittest discover -s tests
+        if: ${{ !matrix.coverage }}
+        run: python -m unittest discover -s tests -t .
+
+      - name: Unit tests with coverage
+        if: ${{ matrix.coverage }}
+        run: |
+          coverage run -m unittest discover -s tests -t .
+          coverage report
+
+  install-smoke:
+    if: github.event.pull_request.draft == false
+    name: install smoke (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Locate the virtual environment
+        run: |
+          if [ "$RUNNER_OS" = "Windows" ]; then bin=Scripts; else bin=bin; fi
+          echo "VENV_BIN=$RUNNER_TEMP/venv/$bin" >> "$GITHUB_ENV"
+
+      - name: Install the package (not editable)
+        run: |
+          python -m venv "$RUNNER_TEMP/venv"
+          "$VENV_BIN/python" -m pip install --upgrade pip
+          "$VENV_BIN/python" -m pip install .
+
+      - name: Build the smoke dataset
+        run: '"$VENV_BIN/python" -m tests.make_smoke_dataset "$RUNNER_TEMP/smoke.db"'
+
+      - name: Run from an unrelated directory
+        env:
+          ESC_EXIT_STRATEGY: "1"
+          ESC_ASSESSMENT_TYPE: "1"
+        run: |
+          cloudexit="$VENV_BIN/cloudexit"
+          workdir="$(mktemp -d)"
+          cd "$workdir"
+
+          "$cloudexit" --version
+          "$cloudexit" config path
+          "$VENV_BIN/python" - <<'PY'
+          from cloudexit.providers.azure.clients import (
+              create_cost_client,
+              create_resource_client,
+              create_subscription_client,
+          )
+
+
+          class Credential:
+              def get_token(self, *scopes, **kwargs):
+                  raise RuntimeError("no network in this check")
+
+
+          create_resource_client(Credential(), "00000000-0000-0000-0000-000000000000")
+          create_subscription_client(Credential())
+          create_cost_client(Credential())
+          print("the Azure clients import and build")
+          PY
+          "$cloudexit" aws \
+            --tfstate "$GITHUB_WORKSPACE/tests/fixtures/smoke/aws.tfstate" \
+            --catalogue "$RUNNER_TEMP/smoke.db" \
+            --non-interactive
+
+          report="$(ls -d reports/*/ | head -n 1)"
+          test -f "${report}index.html"
+          test -f "${report}report.pdf"
+          test -d "${report}assets/css"
+          test -d "${report}assets/img"
+          test -n "$(find "${report}assets/icons/aws" -name '*.png' | head -n 1)"
+          test "$(wc -c < "${report}report.pdf")" -gt 10000
+
+  upgrade-smoke:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install the 1.1.7 environment
+        run: |
+          python -m venv "$RUNNER_TEMP/venv"
+          "$RUNNER_TEMP/venv/bin/python" -m pip install --upgrade pip
+          git show v1.1.7:requirements.txt > "$RUNNER_TEMP/req-1.1.7.txt"
+          "$RUNNER_TEMP/venv/bin/python" -m pip install -r "$RUNNER_TEMP/req-1.1.7.txt"
+
+      - name: Upgrade it to this branch
+        run: '"$RUNNER_TEMP/venv/bin/python" -m pip install .'
+
+      - name: Build the smoke dataset
+        run: '"$RUNNER_TEMP/venv/bin/python" -m tests.make_smoke_dataset "$RUNNER_TEMP/smoke.db"'
+
+      - name: Run from an unrelated directory
+        env:
+          ESC_EXIT_STRATEGY: "1"
+          ESC_ASSESSMENT_TYPE: "1"
+        run: |
+          cloudexit="$RUNNER_TEMP/venv/bin/cloudexit"
+          workdir="$(mktemp -d)"
+          cd "$workdir"
+
+          "$cloudexit" --version
+          "$cloudexit" config path
+          "$RUNNER_TEMP/venv/bin/python" - <<'PY'
+          from cloudexit.providers.azure.clients import (
+              create_cost_client,
+              create_resource_client,
+              create_subscription_client,
+          )
+
+
+          class Credential:
+              def get_token(self, *scopes, **kwargs):
+                  raise RuntimeError("no network in this check")
+
+
+          create_resource_client(Credential(), "00000000-0000-0000-0000-000000000000")
+          create_subscription_client(Credential())
+          create_cost_client(Credential())
+          print("the Azure clients import and build")
+          PY
+          "$cloudexit" aws \
+            --tfstate "$GITHUB_WORKSPACE/tests/fixtures/smoke/aws.tfstate" \
+            --catalogue "$RUNNER_TEMP/smoke.db" \
+            --non-interactive
+
+          report="$(ls -d reports/*/ | head -n 1)"
+          test -f "${report}index.html"
+          test -f "${report}report.pdf"
+          test -d "${report}assets/css"
+          test -d "${report}assets/img"
+          test -n "$(find "${report}assets/icons/aws" -name '*.png' | head -n 1)"
+          test "$(wc -c < "${report}report.pdf")" -gt 10000

.github/workflows/release.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Version, no leading v (e.g. 1.1.5)"
+        description: "Version, no leading v (e.g. 1.1.5, or 2.0.0-rc.1 from a release branch)"
         required: true
 
 permissions:
@@ -18,31 +18,38 @@ jobs:
         with:
           token: ${{ secrets.RELEASE_TOKEN }}
 
-      - name: Guard against non-main dispatch
+      - name: Validate branch, version and guard against existing tag
+        env:
+          VERSION: ${{ inputs.version }}
         run: |
-          if [ "${{ github.ref }}" != "refs/heads/main" ]; then
-            echo "Release must be dispatched from main, got ${{ github.ref }}"; exit 1
+          case "$GITHUB_REF" in
+            refs/heads/main)
+              echo "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' || { echo "Final versions (X.Y.Z) only from main, got: $VERSION"; exit 1; }
+              ;;
+            refs/heads/release/*)
+              echo "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$' || { echo "Only release candidates (X.Y.Z-rc.N) from a release branch, got: $VERSION"; exit 1; }
+              ;;
+            *)
+              echo "Release must be dispatched from main or a release/* branch, got $GITHUB_REF"; exit 1
+              ;;
+          esac
+          if git ls-remote --exit-code --tags origin "refs/tags/v$VERSION" >/dev/null 2>&1; then
+            echo "Tag v$VERSION already exists on origin"; exit 1
           fi
 
-      - name: Validate version and guard against existing tag
+      - name: Bump cloudexit/version.py
+        env:
+          VERSION: ${{ inputs.version }}
         run: |
-          v="${{ inputs.version }}"
-          echo "$v" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' || { echo "Bad version format: $v"; exit 1; }
-          if git ls-remote --exit-code --tags origin "refs/tags/v$v" >/dev/null 2>&1; then
-            echo "Tag v$v already exists on origin"; exit 1
-          fi
-
-      - name: Bump utils/version.py
-        run: |
-          v="${{ inputs.version }}"
-          sed -i "s/^__version__ = .*/__version__ = \"$v\"/" utils/version.py
-          grep -q "^__version__ = \"$v\"$" utils/version.py || { echo "sed did not update version"; exit 1; }
+          sed -i "s/^__version__ = .*/__version__ = \"$VERSION\"/" cloudexit/version.py
+          grep -q "^__version__ = \"$VERSION\"$" cloudexit/version.py || { echo "sed did not update version"; exit 1; }
 
-      - name: Commit, tag, and push to main
+      - name: Commit, tag, and push to the dispatched branch
+        env:
+          VERSION: ${{ inputs.version }}
         run: |
-          v="${{ inputs.version }}"
           git config user.name  "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git commit -am "Release v$v"
-          git tag -a "v$v" -m "Release v$v"
-          git push origin HEAD "refs/tags/v$v"
+          git commit -am "Release v$VERSION"
+          git tag -a "v$VERSION" -m "Release v$VERSION"
+          git push origin HEAD "refs/tags/v$VERSION"

.gitignore

@@ -100,9 +100,18 @@ web_modules/
 # Generated reports
 reports/
 
-# Generated reports
-config/aws.json
-config/azure.json
+# Rendered sample reports (python -m tests.samples)
+/samples/
+
+# Local configs (only the example templates are tracked)
+config/*
+!config/*_example.json
+
+# Terraform state and downloaded datasets
+*.tfstate
+!tests/fixtures/smoke/aws.tfstate
+!tests/fixtures/samples/tfstate/*.tfstate
+datasets/
 
 # TypeScript cache
 *.tsbuildinfo
@@ -404,3 +413,6 @@ $RECYCLE.BIN/
 output/
 logs/
 *.xlsx
+
+# Local platform credentials (deprecated)
+/config.py

AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md
+
+## What this is
+
+cloudexit is an offline-first CLI. It collects cloud inventory and cost data with the user's own credentials, builds a local report, and can optionally upload the results to a platform through API v2. Cloud credentials stay on the user's machine and are never sent anywhere.
+
+## Setup
+
+- Develop on Python 3.14. CI also tests 3.12 and 3.13 on Linux and 3.14 on macOS and Windows, because `requires-python` is `>=3.12`: don't use anything newer than 3.12 (for example `uuid.uuid7` only behind a fallback).
+- Create and activate a virtualenv, then `pip install -r requirements-dev.txt`.
+- Run the CLI with `python3 main.py`, or `pip install -e .` and use the `cloudexit` command.
+- Local configs go in `config/` (start from a `*_example.json` template). They are never committed.
+
+## Lint and format
+
+CI runs exactly these, with the tool versions pinned in `requirements-dev.txt`:
+
+```bash
+ruff check main.py cloudexit tests
+black --check main.py cloudexit tests
+```
+
+Fix with `ruff check --fix main.py cloudexit tests` and `black main.py cloudexit tests`. Don't add a `# noqa` or an ignore without a code comment saying why.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+- Add or update tests with every behaviour change. Tests sit in sub-directories that mirror the source layout (`tests/platform/`, `tests/report/`, ...); shared builders are in `tests/support/` and data files in `tests/fixtures/`.
+- Always discover with `-t .`: without it `tests/` itself becomes the top-level directory and `tests/platform/` would be imported as `platform`, shadowing the standard library.
+- Tests never call real cloud APIs or real platforms. Mock `boto3`, the Azure SDK and HTTP.
+- Tests that cannot run on a platform (POSIX file modes on Windows) are skipped with `unittest.skipIf` or `skipUnless` and a reason, never deleted.
+- The Ubuntu 3.14 job runs the suite under `coverage` and prints the report. There is no threshold.
+
+## Branches
+
+- Name branches `task/<snake_case>`, one topic per branch.
+- During 2.0 development, branch from and target `release/2.0`. `main` only gets hotfixes and Dependabot PRs (Dependabot always targets `main`).
+- Before each release candidate, bring `main` into `release/2.0` with a PR from a branch `task/sync_main` (`git merge origin/main`). Merge it with a merge commit, not a squash.
+- After the 2.0 release, branch from and target `main`.
+
+## Commits
+
+One line, lowercase, no trailing period, plain words about what changed, for example `load the egress resource registry from master data`.
+
+## Pull requests
+
+- A sentence-case title.
+- A description with a Summary, a Changes section grouped by area, and a closing line on user-visible impact.
+- State compatibility explicitly: config, exit codes, report output, the dataset and the API v2 definition copy.
+- Wait for PR Checks to pass, then squash-merge (except `task/sync_main`, see Branches).
+
+## Never commit
+
+- Real values in `config.py`.
+- Anything in `config/` except the `*_example.json` templates.
+- `*.tfstate` files.
+- `datasets/` and `reports/`.
+- `.env` files, or credentials of any kind.
+
+## Compatibility rules
+
+- The CLI must keep working fully offline, without an account.
+- The public contract is the `cloudexit` command, `python -m cloudexit` and `cloudexit.cli:main`. Everything else under `cloudexit.*` is internal and may move in any 2.x release. `python3 main.py` works from a checkout through a small root script that is not installed.
+- `docs/api-v2/` is a vendored copy of the API v2 definition. Never edit it here; the version check test enforces this.
+- The dataset is read only by column name. The CLI must tolerate extra tables and columns.
+
+## Security
+
+Never log API keys, cloud credentials, the `Authorization` header or full request and response payloads. Never add telemetry.