utec-client 0.5.0__tar.gz

utec_client-0.5.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  # Python dependencies (from pyproject.toml), weekly, no auto-merge.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels: ["dependencies"]
+  # GitHub Actions, weekly, no auto-merge. Dependabot may update the pinned
+  # action revisions in workflows when new versions are released.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels: ["dependencies"]

utec_client-0.5.0/.github/workflows/manual-release.yml

@@ -0,0 +1,88 @@
+name: Manual release
+
+# Manual dispatch accepting a custom stable version (X.Y.Z / vX.Y.Z). Always
+# validates from and releases at the tip of main (dispatching from another
+# ref is rejected: the workflow checks out main and compares the pinned HEAD
+# against the fetched origin/main tip). Can create the first fork release,
+# permits intentional minor/major choices, and refuses reused, lower, or
+# non-stable versions. After creating the tag and release it dispatches the
+# common validated publishing path (publish.yml), which builds and checks
+# the exact tagged source.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Stable version to release, e.g. 1.2.3 or v1.2.3"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: utec-client-release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the tag and release
+      actions: write # explicitly dispatch the publish workflow
+    env:
+      GH_TOKEN: ${{ github.token }}
+      REQUESTED_VERSION: ${{ inputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Validate requested version at the tip of main
+        id: pin
+        run: |
+          git remote set-branches origin main
+          git fetch origin main
+          git checkout --detach origin/main
+          OUT=$(python scripts/prepare_release.py manual "$REQUESTED_VERSION")
+          echo "$OUT"
+          echo "tag=$(echo "$OUT" | python -c "import json,sys; print(json.load(sys.stdin)['tag'])")" >> "$GITHUB_OUTPUT"
+          echo "version=$(echo "$OUT" | python -c "import json,sys; print(json.load(sys.stdin)['version'])")" >> "$GITHUB_OUTPUT"
+          echo "sha=$(echo "$OUT" | python -c "import json,sys; print(json.load(sys.stdin)['sha'])")" >> "$GITHUB_OUTPUT"
+      - name: Create tag at the pinned main commit
+        env:
+          RELEASE_TAG: ${{ steps.pin.outputs.tag }}
+          PINNED_SHA: ${{ steps.pin.outputs.sha }}
+        run: |
+          git tag "${RELEASE_TAG}" "${PINNED_SHA}"
+          git push origin "refs/tags/${RELEASE_TAG}"
+      - name: Generate release notes since the previous fork release
+        env:
+          RELEASE_TAG: ${{ steps.pin.outputs.tag }}
+        run: python scripts/prepare_release.py notes --tag "${RELEASE_TAG}" > notes-body.md
+      - name: Create the release with the fork marker
+        env:
+          RELEASE_TAG: ${{ steps.pin.outputs.tag }}
+          RELEASE_VERSION: ${{ steps.pin.outputs.version }}
+        run: |
+          # The marker line identifies this as a fork release for weekly
+          # selection; eligibility additionally requires fork-base ancestry.
+          printf 'utec-client-fork-release: true\n\n' > release-body.md
+          cat notes-body.md >> release-body.md
+          gh release create "${RELEASE_TAG}" \
+            --verify-tag \
+            --target "${{ steps.pin.outputs.sha }}" \
+            --title "utec-client ${RELEASE_VERSION}" \
+            --notes-file release-body.md
+      - name: Dispatch the common validated publishing path
+        env:
+          RELEASE_TAG: ${{ steps.pin.outputs.tag }}
+          RELEASE_VERSION: ${{ steps.pin.outputs.version }}
+        run: |
+          gh workflow run publish.yml \
+            --ref main \
+            -f tag="${RELEASE_TAG}" \
+            -f version="${RELEASE_VERSION}"

utec_client-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,263 @@
+name: Publish to PyPI
+
+# The single common validated publishing path for human-created, manual, and
+# weekly releases. Flow:
+#
+# 1. validate-source (trusted main checkout, before any target-tag use):
+#    strict stable tag/version pair, single remote tag ref, tag commit an
+#    ancestor of origin/main, release carries the fork marker, tag commit a
+#    strict descendant of the fork base. Inputs only ever reach scripts via
+#    env vars.
+# 2. build: if a prior run of this trusted workflow already built the exact
+#    source commit (its BUILD job succeeded even if the run later failed at
+#    publish time; located via the GitHub API, scripts/find_validated_build.py),
+#    its immutable GitHub Actions artifact release-dists-<source sha> is
+#    reused — retries never rebuild. Otherwise, when PyPI has NO release
+#    files yet, the selected source is built and fully validated (lint,
+#    tests, build, clean-environment artifact checks); when PyPI already has
+#    files, a missing/unusable validated artifact fails closed instead of
+#    rebuilding originals. The artifact carries PROVENANCE.json (tag,
+#    version, source commit, building run) + SHA256SUMS. Release assets are
+#    intentionally NOT uploaded: trust rests on the immutable workflow
+#    artifact plus its provenance binding.
+# 3. pypi-publish (OIDC): re-downloads the same-run immutable artifact,
+#    re-verifies provenance + manifest + producer run + version, classifies
+#    against PyPI (read-only), uploads only missing distribution files, then
+#    performs a post-upload readback verification.
+
+on:
+  workflow_call:
+    inputs:
+      tag:
+        required: true
+        type: string
+      version:
+        required: true
+        type: string
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to publish (must already exist)"
+        required: true
+        type: string
+      version:
+        description: "Stable version matching the tag, e.g. 1.2.3"
+        required: true
+        type: string
+  release:
+    types: [published]
+
+concurrency:
+  group: utec-client-release
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  validate-source:
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.set.outputs.tag }}
+      version: ${{ steps.set.outputs.version }}
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - id: set
+        run: |
+          if [ -n "$DISPATCH_TAG" ]; then
+            echo "tag=$DISPATCH_TAG" >> "$GITHUB_OUTPUT"
+            echo "version=$DISPATCH_VERSION" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
+            echo "version=${RELEASE_TAG#v}" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          DISPATCH_TAG: ${{ inputs.tag }}
+          DISPATCH_VERSION: ${{ inputs.version }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+      - name: Validate source eligibility before any target-tag use
+        env:
+          PUBLISH_TAG: ${{ steps.set.outputs.tag }}
+          PUBLISH_VERSION: ${{ steps.set.outputs.version }}
+        run: |
+          git remote set-branches origin main
+          git fetch origin main
+          python scripts/prepare_release.py prepublish --tag "$PUBLISH_TAG" --version "$PUBLISH_VERSION"
+
+  build:
+    runs-on: ubuntu-latest
+    needs: validate-source
+    permissions:
+      contents: read
+      actions: read # locate/download the prior validated build artifact
+    env:
+      GH_TOKEN: ${{ github.token }}
+      RELEASE_TAG: ${{ needs.validate-source.outputs.tag }}
+      RELEASE_VERSION: ${{ needs.validate-source.outputs.version }}
+    outputs:
+      source_sha: ${{ steps.prepub.outputs.sha }}
+      built_by_run: ${{ steps.decide.outputs.built_by_run }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - run: pip install -e .[dev]
+      - name: Resolve and re-verify source eligibility
+        id: prepub
+        run: |
+          git remote set-branches origin main
+          git fetch origin main
+          OUT=$(python scripts/prepare_release.py prepublish --tag "$RELEASE_TAG" --version "$RELEASE_VERSION")
+          echo "$OUT"
+          SHA=$(echo "$OUT" | python -c "import json,sys; print(json.load(sys.stdin)['sha'])")
+          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
+      - name: Look for a prior validated build of this exact source
+        id: decide
+        env:
+          SOURCE_SHA: ${{ steps.prepub.outputs.sha }}
+          CURRENT_RUN: ${{ github.run_id }}
+        run: |
+          set +e
+          OUT=$(python scripts/find_validated_build.py --sha "$SOURCE_SHA" --tag "$RELEASE_TAG" --exclude-run "$CURRENT_RUN")
+          code=$?
+          set -e
+          if [ "$code" = 2 ]; then
+            # Trusted run found but artifact missing/expired: fail closed here
+            # too (before any rebuild decision) with the actionable guidance
+            # the finder already printed.
+            exit 1
+          fi
+          if [ "$code" = 0 ]; then
+            REUSED_RUN=$(echo "$OUT" | awk '{print $1}')
+            ARTIFACT=$(echo "$OUT" | awk '{print $2}')
+            echo "reused=true" >> "$GITHUB_OUTPUT"
+            echo "reused_run_id=$REUSED_RUN" >> "$GITHUB_OUTPUT"
+            echo "artifact_name=$ARTIFACT" >> "$GITHUB_OUTPUT"
+            echo "built_by_run=$REUSED_RUN" >> "$GITHUB_OUTPUT"
+          else
+            echo "reused=false" >> "$GITHUB_OUTPUT"
+            echo "built_by_run=$CURRENT_RUN" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Reuse prior validated build artifact
+        if: steps.decide.outputs.reused == 'true'
+        env:
+          REUSED_RUN: ${{ steps.decide.outputs.reused_run_id }}
+          ARTIFACT_NAME: ${{ steps.decide.outputs.artifact_name }}
+          SOURCE_SHA: ${{ steps.prepub.outputs.sha }}
+        run: |
+          mkdir -p dist
+          if ! gh run download "$REUSED_RUN" -n "$ARTIFACT_NAME" -D dist; then
+            echo "::error::failed to download validated artifact $ARTIFACT_NAME from run $REUSED_RUN."
+            echo "::error::Recovery: re-run the failed jobs of run $REUSED_RUN (its build job rebuilds from the same source commit), then re-dispatch this publish run. Do NOT rebuild from a different source after files may be on PyPI."
+            exit 1
+          fi
+          python scripts/verify_validated_build.py --dir dist --tag "$RELEASE_TAG" \
+            --version "$RELEASE_VERSION" --sha "$SOURCE_SHA" --built-by-run "$REUSED_RUN"
+      - name: Rebuilding this version is only allowed while it has no PyPI files
+        if: steps.decide.outputs.reused != 'true'
+        env:
+          RELEASE_VERSION: ${{ needs.validate-source.outputs.version }}
+        run: |
+          set +e
+          # N6: version-scoped gate — older published versions never block a
+          # new release; exit 4 (unknown PyPI state) also fails closed.
+          python scripts/pypi_preflight.py --check-files-exist --version "${RELEASE_VERSION}"
+          code=$?
+          set -e
+          if [ "$code" = 0 ]; then
+            echo "::error::PyPI already has files for version ${RELEASE_VERSION} but no validated artifact for source ${{ steps.prepub.outputs.sha }} was found; refusing to rebuild."
+            echo "::error::Recovery: re-run the failed PUBLISH job of the original run (its retained artifact is reused), or re-dispatch publish with the same tag/version to reuse a validated artifact from another trusted run. If the original artifact is irretrievably lost, manual owner intervention is required — never delete or reuse published filenames."
+            exit 1
+          fi
+          if [ "$code" != 1 ]; then
+            echo "::error::could not determine PyPI state for ${RELEASE_VERSION} (exit $code); refusing to rebuild on unknown state."
+            exit 1
+          fi
+      - name: Build and fully validate the selected source
+        if: steps.decide.outputs.reused != 'true'
+        env:
+          SOURCE_SHA: ${{ steps.prepub.outputs.sha }}
+          CURRENT_RUN: ${{ github.run_id }}
+        run: |
+          git fetch --force origin "refs/tags/${RELEASE_TAG}:refs/tags/${RELEASE_TAG}"
+          git checkout --detach "refs/tags/${RELEASE_TAG}"
+          pip install -e .[dev]
+          ruff check . && ruff format --check .
+          pytest
+          python -m build
+          V=$(ls dist | grep '\.whl$'); V=${V#utec_client-}; V=${V%-py3-none-any.whl}
+          if [ "$V" != "${RELEASE_VERSION}" ]; then
+            echo "::error::built version $V != release version ${RELEASE_VERSION}"
+            exit 1
+          fi
+          python -c "import json, os; json.dump({'tag': os.environ['RELEASE_TAG'], 'version': os.environ['RELEASE_VERSION'], 'source_sha': os.environ['SOURCE_SHA'], 'built_by_run': int(os.environ['CURRENT_RUN'])}, open('dist/PROVENANCE.json', 'w'))"
+          sha256sum dist/*.whl dist/*.tar.gz > dist/SHA256SUMS
+          python scripts/check_artifact.py --dist-dir dist --version "${RELEASE_VERSION}"
+      - name: Check actual bytes against the selected version (all publish attempts)
+        run: python scripts/check_artifact.py --dist-dir dist --version "${RELEASE_VERSION}"
+      - name: Upload immutable validated artifact (this run)
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-dists-${{ steps.prepub.outputs.sha }}
+          path: dist/
+          if-no-files-found: error
+          retention-days: 90 # the supported maximum; retain offline originals for longer needs
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      id-token: write # the only job with publishing authority (OIDC)
+      contents: read
+    environment:
+      name: pypi-publish
+      url: https://pypi.org/p/utec-client/
+    env:
+      GH_TOKEN: ${{ github.token }}
+      PUBLISH_TAG: ${{ needs.validate-source.outputs.tag }}
+      PUBLISH_VERSION: ${{ needs.validate-source.outputs.version }}
+      SOURCE_SHA: ${{ needs.build.outputs.source_sha }}
+      BUILT_BY_RUN: ${{ needs.build.outputs.built_by_run }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-dists-${{ needs.build.outputs.source_sha }}
+          path: dist/
+      - name: Re-verify provenance, producer run, and manifest of the exact bytes
+        run: |
+          python scripts/verify_validated_build.py --dir dist --tag "$PUBLISH_TAG" \
+            --version "$PUBLISH_VERSION" --sha "$SOURCE_SHA" --built-by-run "$BUILT_BY_RUN"
+      - name: Read-only PyPI preflight (new / identical / conflict) and staging of new files
+        id: preflight
+        run: |
+          set +e
+          python scripts/pypi_preflight.py --dist-dir dist --staging-dir staging
+          code=$?
+          if [ "$code" = 0 ]; then echo "proceed=true" >> "$GITHUB_OUTPUT"
+          elif [ "$code" = 3 ]; then echo "proceed=false" >> "$GITHUB_OUTPUT"
+          else exit 1; fi
+      - name: Publish missing files to PyPI
+        if: steps.preflight.outputs.proceed == 'true'
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: staging/
+      - name: Post-upload readback verification
+        run: python scripts/pypi_preflight.py --dist-dir dist --verify-published

utec_client-0.5.0/.github/workflows/test.yml

@@ -0,0 +1,57 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# PR checks are read-only and run no publishing credentials.
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - run: pip install -e .[dev]
+      - run: ruff check .
+      - run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0 # setuptools-scm derives the version from tags
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .[dev]
+      # Coverage floor (90%) and flags are centralized in pyproject.toml.
+      - run: pytest
+
+  package:
+    # Verify wheel/sdist metadata and installed-package behavior outside the
+    # source checkout, including a wheel rebuilt from the sdist.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - run: pip install -e .[dev]
+      - run: python -m build
+      - name: Verify artifacts from a clean environment
+        run: |
+          V=$(basename dist/*.whl .whl); V=${V#utec_client-}; V=${V%-py3-none-any}
+          python scripts/check_artifact.py --dist-dir dist --version "$V"

utec_client-0.5.0/.github/workflows/weekly-release.yml

@@ -0,0 +1,107 @@
+name: Weekly release
+
+# Mondays 13:00 UTC. Selects the highest eligible fork release, verifies its
+# tag is an ancestor of main, and — only when main has newer commits — cuts
+# the next patch release at the pinned main commit, then dispatches the
+# common validated publishing path (publish.yml), which builds and checks
+# the exact tagged source. Skips with a notice when no fork baseline release
+# exists yet or main is unchanged; never bootstraps from inherited upstream
+# releases/tags.
+
+on:
+  schedule:
+    - cron: "0 13 * * 1"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: utec-client-release
+  cancel-in-progress: false
+
+jobs:
+  decide:
+    runs-on: ubuntu-latest
+    outputs:
+      action: ${{ steps.decide.outputs.action }}
+      tag: ${{ steps.decide.outputs.tag }}
+      version: ${{ steps.decide.outputs.version }}
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - id: decide
+        run: |
+          git remote set-branches origin main
+          git fetch origin main
+          DECISION=$(python scripts/prepare_release.py weekly)
+          echo "$DECISION"
+          ACTION=$(echo "$DECISION" | python -c "import json,sys; print(json.load(sys.stdin)['action'])")
+          echo "action=$ACTION" >> "$GITHUB_OUTPUT"
+          if [ "$ACTION" = release ]; then
+            echo "tag=$(echo "$DECISION" | python -c "import json,sys; print(json.load(sys.stdin)['tag'])")" >> "$GITHUB_OUTPUT"
+            echo "version=$(echo "$DECISION" | python -c "import json,sys; print(json.load(sys.stdin)['version'])")" >> "$GITHUB_OUTPUT"
+          fi
+
+  release:
+    if: needs.decide.outputs.action == 'release'
+    needs: decide
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the tag and release
+      actions: write # explicitly dispatch the publish workflow
+    env:
+      GH_TOKEN: ${{ github.token }}
+      RELEASE_TAG: ${{ needs.decide.outputs.tag }}
+      RELEASE_VERSION: ${{ needs.decide.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Re-validate version at the pinned main tip
+        id: pin
+        run: |
+          git remote set-branches origin main
+          git fetch origin main
+          git checkout --detach origin/main
+          OUT=$(python scripts/prepare_release.py manual "$RELEASE_VERSION")
+          echo "$OUT"
+          echo "sha=$(echo "$OUT" | python -c "import json,sys; print(json.load(sys.stdin)['sha'])")" >> "$GITHUB_OUTPUT"
+      - name: Check tag does not already exist
+        run: |
+          if git rev-parse -q --verify "refs/tags/${RELEASE_TAG}" >/dev/null; then
+            echo "::error::tag ${RELEASE_TAG} already exists; tags are never moved"
+            exit 1
+          fi
+      - name: Create tag at the pinned main commit
+        run: |
+          git tag "${RELEASE_TAG}" "${{ steps.pin.outputs.sha }}"
+          git push origin "refs/tags/${RELEASE_TAG}"
+      - name: Generate release notes since the previous fork release
+        run: python scripts/prepare_release.py notes --tag "${RELEASE_TAG}" > notes-body.md
+      - name: Create the release with the fork marker
+        run: |
+          # The marker line identifies this as a fork release for weekly
+          # selection; eligibility additionally requires fork-base ancestry.
+          printf 'utec-client-fork-release: true\n\n' > release-body.md
+          cat notes-body.md >> release-body.md
+          gh release create "${RELEASE_TAG}" \
+            --verify-tag \
+            --title "utec-client ${RELEASE_VERSION}" \
+            --notes-file release-body.md
+      - name: Dispatch the common validated publishing path
+        run: |
+          gh workflow run publish.yml \
+            --ref main \
+            -f tag="${RELEASE_TAG}" \
+            -f version="${RELEASE_VERSION}"