pyplusportal 0.1.0__tar.gz

pyplusportal-0.1.0/.claude/hooks/format-python.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Formats and auto-fixes a Python file right after it is written, so the
+# `ruff format --check` gate never fails for something a tool can fix.
+set -uo pipefail
+
+payload=$(cat)
+file=$(printf '%s' "$payload" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("file_path",""))' 2>/dev/null)
+
+case "$file" in (*.py) ;; (*) exit 0 ;; esac
+[ -f "$file" ] || exit 0
+
+cd "$(git rev-parse --show-toplevel)" 2>/dev/null || exit 0
+uv run ruff check --fix -q "$file" >/dev/null 2>&1
+uv run ruff format -q "$file" >/dev/null 2>&1
+exit 0

pyplusportal-0.1.0/.claude/hooks/gates-before-push.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Refuses `git push` when the gates CI runs are not green.
+#
+# The git pre-push hook already does this for pushes from a shell. This one
+# covers pushes an agent makes, and gives it the failure output directly so it
+# can fix the cause instead of retrying.
+set -uo pipefail
+
+payload=$(cat)
+command=$(printf '%s' "$payload" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("command",""))' 2>/dev/null)
+
+case "$command" in
+  (*"git push"*) ;;
+  (*) exit 0 ;;
+esac
+# The pre-push git hook handles the shell path; skip when it is being bypassed
+# deliberately, so --no-verify keeps meaning what it says.
+case "$command" in (*--no-verify*) exit 0 ;; esac
+
+cd "$(git rev-parse --show-toplevel)" 2>/dev/null || exit 0
+
+if ! output=$(./.claude/hooks/gates.sh 2>&1); then
+  {
+    echo "Blocked: main must stay green, and the gates are not."
+    echo
+    echo "$output"
+    echo
+    echo "Fix these before pushing. Do not bypass with --no-verify unless the"
+    echo "user has asked for a deliberately red push."
+  } >&2
+  exit 2
+fi
+exit 0

pyplusportal-0.1.0/.claude/hooks/gates.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Runs every gate CI runs. Used by the pre-push hook and the `verify` skill, so
+# a red pipeline is discovered here rather than on GitHub.
+set -uo pipefail
+cd "$(git rev-parse --show-toplevel)" || exit 1
+
+fail=0
+run() {
+  local label="$1"; shift
+  if out=$("$@" 2>&1); then
+    printf '  ok    %s\n' "$label"
+  else
+    printf '  FAIL  %s\n' "$label"
+    printf '%s\n' "$out" | tail -15 | sed 's/^/        /'
+    fail=1
+  fi
+}
+
+echo "gates:"
+run "ruff check"    uv run ruff check src tests tests_ha custom_components
+run "ruff format"   uv run ruff format --check src tests tests_ha custom_components
+run "mypy"          uv run --group ha mypy
+run "library tests" uv run pytest -q
+run "ha tests"      uv run --group ha pytest -c pytest-ha.ini -q
+exit $fail

pyplusportal-0.1.0/.claude/hooks/no-account-data.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Blocks commits that would put real account data into the repository.
+#
+# This exists because it already happened: a meter number, a customer number
+# and a portal user id reached tracked files, including — of all places — the
+# test that proves the redaction helper works. They were caught by hand, one
+# step before the repository went public. This hook is the part that does not
+# depend on someone remembering.
+#
+# Reads a Claude Code PreToolUse payload on stdin. Exit 2 blocks the tool call
+# and returns stderr to the model.
+set -uo pipefail
+
+payload=$(cat)
+command=$(printf '%s' "$payload" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("command",""))' 2>/dev/null)
+
+# Only interested in commits. Everything else passes straight through.
+case "$command" in
+  *"git commit"*) ;;
+  *) exit 0 ;;
+esac
+
+cd "$(git rev-parse --show-toplevel)" 2>/dev/null || exit 0
+staged=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null)
+[ -z "$staged" ] && exit 0
+
+# Patterns for values that identify a real account or connection point.
+# Deliberately shaped, not a list of known values: a new meter number must trip
+# this too.
+findings=$(printf '%s\n' "$staged" | while IFS= read -r file; do
+  # Patterns are wrapped in balanced parens: inside $( ), an unbalanced ')'
+  # from a case pattern terminates the substitution and breaks the parser.
+  case "$file" in
+    (uv.lock|*.png|*.lock) continue ;;                # hashes collide with digit runs
+    (.claude/hooks/no-account-data.sh) continue ;;    # this file describes the patterns
+    (docs/specs/safety.md) continue ;;                # so does the spec
+  esac
+  [ -f "$file" ] || continue
+
+  git diff --cached -U0 -- "$file" | grep '^+' | grep -v '^+++' | \
+    grep -nEi \
+      -e '[0-9][A-Z]{3}[0-9]{10}' \
+      -e '\b1[0-9]{9}\b' \
+      -e '\b0003[0-9]{2}\b' \
+      -e 'plusportal\.de' \
+      -e 'PLUSPORTAL_PASSWORD=.+' \
+    | grep -viE '123456|1ABC0000000000|1XYZ9876543210|1000000000|<tenant>' \
+    | sed "s|^|  $file: |"
+done)
+
+if [ -n "$findings" ]; then
+  cat >&2 <<EOF
+Blocked: the staged changes look like they contain real account data.
+
+$findings
+
+Nothing identifying a real account belongs in this repository — no meter
+numbers, customer numbers, portal user ids, real tenant numbers or portal
+hostnames. Use fictional values (tenant 123456, meter 1ABC0000000000*,
+user 1000000000) and take real ones from the environment; see
+docs/specs/safety.md.
+
+If this is a false positive, say so and the check can be narrowed. Do not
+work around it by unstaging the file and committing it another way.
+EOF
+  exit 2
+fi
+
+exit 0

pyplusportal-0.1.0/.claude/hooks/no-direct-push-to-main.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Refuses a direct push to main. Every change arrives as a pull request.
+#
+# GitHub enforces this too — the ruleset on main requires one — but its refusal
+# comes after the push has been attempted and reads like a permissions error.
+# This says what to do instead, before anything is sent.
+set -uo pipefail
+
+payload=$(cat)
+command=$(printf '%s' "$payload" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("command",""))' 2>/dev/null)
+
+case "$command" in
+  (*"git push"*) ;;
+  (*) exit 0 ;;
+esac
+
+cd "$(git rev-parse --show-toplevel)" 2>/dev/null || exit 0
+branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+
+# Pushing main, either by being on it or by naming it as the refspec.
+targets_main=0
+[ "$branch" = "main" ] && targets_main=1
+case "$command" in (*" main"*|*":main"*|*"HEAD:main"*) targets_main=1 ;; esac
+[ "$targets_main" = "0" ] && exit 0
+
+cat >&2 <<EOF
+Blocked: main takes pull requests only.
+
+Work on a branch and open a pull request instead:
+
+  git switch -c <type>/<short-description>
+  git push -u origin <branch>
+  gh pr create --fill
+
+Branch names follow the change type — feat/, fix/, chore/, docs/, refactor/ —
+because the release notes and the version bump are derived from it. See
+docs/AGENTIC-SDLC.md.
+EOF
+exit 2

pyplusportal-0.1.0/.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/no-account-data.sh"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/no-direct-push-to-main.sh"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/gates-before-push.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-python.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

pyplusportal-0.1.0/.claude/skills/release/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: release
+description: Use when cutting a release of this project — bumping the version, publishing pyplusportal to PyPI and shipping the integration through HACS.
+---
+
+# Release
+
+Two artefacts move together: the library on PyPI and the integration that pins it. Three
+places carry the version and `tests/test_packaging.py` ties them to each other; the release
+workflow adds the git tag to the same chain, so a mismatch fails before anything publishes.
+
+## Bump
+
+All three, in one commit:
+
+- `pyproject.toml` → `[project] version`
+- `custom_components/plusportal/manifest.json` → `version`
+- `custom_components/plusportal/manifest.json` → `requirements` pin
+
+```bash
+uv run pytest tests/test_packaging.py    # proves they agree
+./.claude/hooks/gates.sh                 # everything else
+```
+
+## Tag
+
+```bash
+git commit -am "Release X.Y.Z"
+git tag vX.Y.Z
+git push origin main --tags
+```
+
+The workflow verifies the tag matches the project version, runs both suites, builds,
+publishes to PyPI through Trusted Publishing and creates the GitHub release. No API token
+is stored anywhere; see RELEASING.md for the one-time PyPI setup.
+
+## Before the first public release
+
+- The repository must be public, or HACS validation cannot fetch `hacs.json` and
+  `manifest.json` — it fetches them unauthenticated.
+- Apply the branch ruleset once that is true: `scripts/apply-ruleset.sh`.
+- `pyplusportal` must still be free on PyPI.
+
+## Do not
+
+Publish on the user's behalf without being asked. Tagging is theirs to trigger; a release
+is public and cannot be unpublished from PyPI.

pyplusportal-0.1.0/.claude/skills/verify/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: verify
+description: Use when a change to this repository needs verifying before commit or push — runs every gate CI runs, then exercises the affected layer for real. Also use when CI is red and you need to reproduce it locally.
+---
+
+# Verify
+
+Green gates are necessary, not sufficient. The gates prove the code is consistent;
+exercising it proves it does the right thing.
+
+## 1. Gates — always
+
+```bash
+./.claude/hooks/gates.sh
+```
+
+ruff check, ruff format, mypy strict, both test suites. Exactly what CI runs, so a red
+pipeline shows up here first. All five must pass; the pre-push hook refuses otherwise.
+
+## 2. Exercise the layer you touched
+
+**Client or CLI** — run it against the real portal. The offline suite uses recorded
+fixtures, so it cannot catch a changed API:
+
+```bash
+uv run pytest -m live          # reconciles three figures against the portal
+uv run pyplusportal overview
+uv run pyplusportal readings --from <date> --to <date>
+```
+
+`-m live` skips silently without `.env`. If it skips, you have not verified anything —
+say so rather than reporting success.
+
+**Integration** — the HA suite covers logic, not appearance. For anything a user sees
+(config flow wording, entity names, dashboard behaviour), load it in a real Home Assistant
+and look. If you cannot, say which parts are unverified.
+
+**Statistics** — the failure mode is a plausible-looking wrong graph. Check the numbers,
+not just that rows were written.
+
+## 3. When a test passes the moment you write it
+
+Mutate the implementation and confirm the test fails. This repository has shipped three
+assertions that could not fail: two matched text argparse prints anyway, one asserted a
+value equals itself. Each was caught in review, not by the suite.
+
+```bash
+# stub the function the test targets, run just that test, expect red, restore
+```
+
+Report the mutation you tried and what happened. "Tests pass" is not evidence when the
+test is new.
+
+## 4. Report honestly
+
+State what you ran, what passed, and what you did not verify. A skipped live suite, an
+unexercised UI path and an untested error branch are all worth one sentence each.

pyplusportal-0.1.0/.env.example

@@ -0,0 +1,15 @@
+# Copy to .env and fill in. Never commit .env.
+# Tenant number from your portal URL: https://123456.plusportal.de -> 123456
+PLUSPORTAL_TENANT=123456
+# Alternatively the full base URL (takes precedence over PLUSPORTAL_TENANT):
+# PLUSPORTAL_BASE_URL=https://123456.plusportal.de
+
+# Portal login — either the e-mail address or the customer number.
+PLUSPORTAL_USERNAME=
+PLUSPORTAL_PASSWORD=
+
+# Tariff (all optional, needed only for the `cost` command):
+# PLUSPORTAL_ENERGY_PRICE_CT=32.5        # energy price in ct/kWh; required by 'cost'
+# PLUSPORTAL_BASE_PRICE_EUR=120.00       # annual standing charge in EUR; used by 'cost'
+# PLUSPORTAL_MONTHLY_ADVANCE_EUR=85.00   # monthly advance payment in EUR; used by 'cost'
+# PLUSPORTAL_BILLING_YEAR_START=01-01    # billing year start as MM-DD; default 01-01

pyplusportal-0.1.0/.githooks/pre-push

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Refuses to push when the gates CI runs would fail.
+#
+# GitHub-side enforcement (a required-status-checks ruleset on main) needs a
+# public repository or GitHub Pro, and is blocked while this repo is private.
+# .github/rulesets/main.json holds it ready; scripts/apply-ruleset.sh applies it
+# the moment that changes. Until then this hook is what keeps main green.
+#
+# Bypass with --no-verify only when you intend to push something red, and say so.
+set -euo pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+if ! ./.claude/hooks/gates.sh; then
+  cat >&2 <<'EOF'
+
+Push refused: the gates above are what CI runs, and they are not green.
+Fix them, or push with --no-verify if you deliberately want a red main.
+EOF
+  exit 1
+fi

pyplusportal-0.1.0/.github/rulesets/main.json

@@ -0,0 +1,66 @@
+{
+  "name": "main must stay green",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": [
+        "~DEFAULT_BRANCH"
+      ],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false,
+        "automatic_copilot_code_review_enabled": false,
+        "allowed_merge_methods": [
+          "squash",
+          "merge",
+          "rebase"
+        ]
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": true,
+        "required_status_checks": [
+          {
+            "context": "Lint and types"
+          },
+          {
+            "context": "Library tests (Python 3.12)"
+          },
+          {
+            "context": "Library tests (Python 3.13)"
+          },
+          {
+            "context": "Home Assistant integration tests"
+          },
+          {
+            "context": "Home Assistant manifest"
+          },
+          {
+            "context": "HACS validation"
+          },
+          {
+            "context": "Version bump"
+          }
+        ]
+      }
+    }
+  ]
+}

pyplusportal-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint and types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Pinned exactly: setup-uv publishes floating major tags only up to v7.
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --group ha
+      - name: ruff
+        run: uv run ruff check src tests tests_ha custom_components
+      - name: ruff format
+        run: uv run ruff format --check src tests tests_ha custom_components
+      - name: mypy
+        run: uv run --group ha mypy
+
+  test-library:
+    name: Library tests (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --python ${{ matrix.python }}
+      # The `live` marker is excluded by default, so no credentials are needed
+      # and CI never talks to a real customer portal.
+      - run: uv run pytest -q --cov --cov-report=term --cov-fail-under=90
+
+  test-integration:
+    name: Home Assistant integration tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --group ha
+      - run: uv run --group ha pytest -c pytest-ha.ini -q
+
+  hassfest:
+    name: Home Assistant manifest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: home-assistant/actions/hassfest@master
+
+  version:
+    name: Version bump
+    # Shipped code under an unchanged version means Home Assistant and HACS
+    # keep serving the old one with nothing to indicate why.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v9.0.0
+      - run: uv run python scripts/check_version_bump.py origin/${{ github.base_ref }}
+
+  hacs:
+    name: HACS validation
+    # HACS fetches hacs.json and manifest.json without authentication, which
+    # 404s on a private repository — the check reports them as invalid rather
+    # than unreachable. It runs as soon as the repository is public; skipping
+    # is honest, marking it continue-on-error would hide real failures later.
+    if: ${{ !github.event.repository.private }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: hacs/action@main
+        with:
+          category: integration

pyplusportal-0.1.0/.github/workflows/claude-review.yml

@@ -0,0 +1,67 @@
+name: Claude review
+
+# Reviews every pull request without needing a mention. Advisory: it comments,
+# it does not gate. The gates are the CI checks in ci.yml.
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+concurrency:
+  group: claude-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      # A missing optional credential should not paint the pull request red.
+      # `secrets` is not available in a job-level `if`, so the check happens
+      # here and the review step keys off it.
+      - id: credential
+        env:
+          TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        run: |
+          if [ -z "$TOKEN" ]; then
+            echo "present=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::No CLAUDE_CODE_OAUTH_TOKEN configured; skipping the review."
+          else
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - if: steps.credential.outputs.present == 'true'
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            Review this pull request against the project's own standards, which
+            are in CLAUDE.md and docs/specs/.
+
+            Weight these, in order:
+
+            1. Correctness against the specs. Does a changed behaviour still
+               match the requirement it cites, and was the spec updated when the
+               behaviour changed?
+            2. Tests that cannot fail. This project has shipped three assertions
+               that passed no matter what the implementation did. If a test looks
+               like it might be vacuous, say which mutation would leave it green.
+            3. The three portal traps in CLAUDE.md: interval timestamps mark the
+               END, the fine series is power in kW, only period=month gives local
+               midnight. Each is silent when wrong.
+            4. Account data. Nothing identifying a real meter, customer or tenant
+               may enter the repository.
+            5. Decimal where money or a running sum is involved.
+
+            Be specific and cite file:line. Do not restate the diff. If it is
+            sound, say so briefly rather than inventing findings.
+          claude_args: |
+            --max-turns 20
+            --model claude-opus-5

pyplusportal-0.1.0/.github/workflows/claude.yml

@@ -0,0 +1,65 @@
+name: Claude
+
+# Responds to @claude in issues, pull requests and review comments.
+# Requires the Claude GitHub App on the repository and an ANTHROPIC_API_KEY
+# secret; see docs/AGENTIC-SDLC.md.
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+  issues:
+    types: [opened, assigned]
+
+concurrency:
+  group: claude-${{ github.event.issue.number || github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      # Checked out so CLAUDE.md, .claude/ and docs/specs/ are available —
+      # they are what keep the agent's changes consistent with the project.
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --group ha
+
+      # Without the credential the action fails with a validation error that
+      # says nothing about which repository setting is missing.
+      - id: credential
+        env:
+          TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        run: |
+          if [ -z "$TOKEN" ]; then
+            echo "present=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::No CLAUDE_CODE_OAUTH_TOKEN configured; @claude is inactive."
+          else
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - if: steps.credential.outputs.present == 'true'
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          claude_args: |
+            --max-turns 30
+            --model claude-opus-5