python-yarbo 0.1.0__tar.gz

python_yarbo-0.1.0/.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{py,toml,yaml,yml,json,md}]
+indent_style = space
+indent_size = 4
+
+[*.{yaml,yml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

python_yarbo-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# CODEOWNERS — code review assignment
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+* @markus-lassfolk

python_yarbo-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,110 @@
+name: Bug Report
+description: Report a bug or unexpected behaviour in python-yarbo.
+title: "[Bug]: "
+labels: ["bug", "triage"]
+assignees:
+  - markus-lassfolk
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill in as much detail as possible.
+        **Do not include credentials, IP addresses, or serial numbers in this report.**
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is.
+      placeholder: Tell us what happened...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Steps to reproduce the behaviour.
+      placeholder: |
+        1. Import the library
+        2. Run `async with YarboClient(...) as client:`
+        3. Call `await client.lights_on()`
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+      description: What actually happened? Include full tracebacks (redact any sensitive data).
+    validations:
+      required: true
+
+  - type: input
+    id: lib-version
+    attributes:
+      label: python-yarbo version
+      placeholder: "e.g. 0.1.0 — run `pip show python-yarbo`"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.12.3 — run `python --version`"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Ubuntu 24.04
+        - Ubuntu 22.04
+        - Debian 12
+        - macOS 14 (Sonoma)
+        - macOS 13 (Ventura)
+        - Windows 11
+        - Windows 10
+        - Raspberry Pi OS
+        - Other (specify in additional context)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Transport used
+      options:
+        - Local MQTT (YarboLocalClient / same WiFi as robot)
+        - Cloud API (YarboCloudClient)
+        - Hybrid (YarboClient)
+        - Discovery (discover_yarbo)
+    validations:
+      required: true
+
+  - type: input
+    id: yarbo-model
+    attributes:
+      label: Yarbo model
+      placeholder: "e.g. Yarbo G1, Yarbo S1 (snow blower)"
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: |
+        Anything else that might help — logs (redact credentials/IPs/SNs),
+        MQTT captures, code snippets, etc.

python_yarbo-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,61 @@
+name: Feature Request
+description: Suggest a new feature or enhancement for python-yarbo.
+title: "[Feature]: "
+labels: ["enhancement"]
+assignees:
+  - markus-lassfolk
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Got an idea to make python-yarbo better? Great — describe it below!
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: Is your feature request related to a problem? Describe it.
+      placeholder: "I find it frustrating when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: A clear description of what you want to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Have you considered any alternative solutions or workarounds?
+
+  - type: textarea
+    id: api-sketch
+    attributes:
+      label: API sketch (optional)
+      description: If you have an idea of what the Python API would look like, sketch it here.
+      render: python
+      placeholder: |
+        # Example:
+        async with YarboClient(broker="192.168.1.24", sn="...") as client:
+            await client.start_plan("morning-route")
+            async for event in client.watch_plan_events():
+                print(event.status)
+
+  - type: checkboxes
+    id: willing-to-pr
+    attributes:
+      label: Would you like to implement this?
+      options:
+        - label: Yes, I'd like to submit a PR for this feature.
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Any other context, links to protocol docs, or related issues.

python_yarbo-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,48 @@
+## Summary
+
+<!-- Describe your changes in a few sentences. Link the related issue(s). -->
+
+Closes #<!-- issue number -->
+
+## Type of change
+
+- [ ] 🐛 Bug fix (non-breaking change that fixes an issue)
+- [ ] ✨ New feature (non-breaking change that adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] 🧹 Refactor / code cleanup (no behaviour change)
+- [ ] 📝 Documentation update
+- [ ] ⚙️ CI/CD / tooling change
+
+## Changes made
+
+<!-- Bullet-point summary of what changed and why. -->
+
+-
+-
+
+## Testing
+
+<!-- Describe how you tested this. Include commands you ran. -->
+
+- [ ] Added / updated pytest tests
+- [ ] All tests pass locally (`pytest tests/`)
+- [ ] Tested manually against Yarbo hardware (if applicable — describe setup below)
+
+## Quality checklist
+
+- [ ] **ruff lint**: Zero errors (`ruff check src/ tests/`)
+- [ ] **ruff format**: No formatting issues (`ruff format --check src/ tests/`)
+- [ ] **mypy**: Zero new type errors (`mypy src/yarbo/`)
+- [ ] **Tests pass**: `pytest tests/` — all green
+- [ ] **CHANGELOG.md** updated under `[Unreleased]`
+- [ ] **Docs updated** (docstrings, README if API changed)
+- [ ] **No secrets, credentials, IP addresses, or serial numbers** in code, comments, or commits
+- [ ] **Follows coding standards** in [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+## Screenshots / output (optional)
+
+<!-- Paste relevant terminal output, before/after if helpful. Redact any credentials/IPs. -->
+
+---
+
+> **Reviewer note**: Branch must be up-to-date with `develop` and all CI checks must pass before merge.

python_yarbo-0.1.0/.github/SECURITY.md

@@ -0,0 +1,76 @@
+# Security Policy
+
+## Supported Versions
+
+python-yarbo is under active development. Security fixes are applied to the **latest release** only.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x     | ✅ Latest release  |
+| < 0.1   | ❌ Not supported   |
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+If you discover a security vulnerability in python-yarbo, please report it privately:
+
+1. **GitHub Private Advisory** *(preferred)*: Go to
+   [Security → Advisories](https://github.com/markus-lassfolk/python-yarbo/security/advisories/new)
+   and click "Report a vulnerability".
+
+2. **Email**: If you cannot use GitHub Advisories, contact the maintainer directly.
+   Include "[python-yarbo Security]" in the subject line.
+
+### What to include
+
+- A description of the vulnerability and its potential impact
+- Steps to reproduce or a proof-of-concept (if safe to share)
+- Affected versions
+- Any suggested mitigations
+
+### Response timeline
+
+| Milestone                      | Target SLA           |
+| ------------------------------ | -------------------- |
+| Acknowledgement of report      | 48 hours             |
+| Initial assessment             | 5 days               |
+| Fix / patch (if confirmed)     | 30 days              |
+| Public disclosure              | After fix is released |
+
+## Security Considerations
+
+python-yarbo communicates with Yarbo robot mowers over **local MQTT (plaintext)**.
+Keep the following in mind:
+
+- **Credentials**: Never hard-code passwords, API keys, or serial numbers in code.
+  Use environment variables or a secrets manager. The RSA public key extracted from
+  the APK is not sensitive and can be committed; private keys and passwords must not be.
+
+- **Network exposure**: The Yarbo EMQX broker listens on port 1883 (plaintext) on
+  the local network. Do **not** expose this port to the internet. Restrict access
+  with your router's firewall.
+
+- **MQTT authentication**: The local EMQX broker appears to accept anonymous connections.
+  Treat the local network as a trust boundary — ensure only authorised devices have WiFi access.
+
+- **Serial numbers**: Your Yarbo serial number (SN) is used as an MQTT topic component.
+  It is not a secret, but avoid sharing it publicly to reduce exposure.
+
+- **Cloud API**: The cloud REST API is migrating to AWS SigV4 auth. JWT tokens
+  (30-day lifetime) should be treated as sensitive credentials.
+
+## Scope
+
+The following are **in scope** for security reports:
+
+- Credential exposure or insecure credential handling in library code
+- Unsafe use of `eval`, `exec`, or similar constructs
+- Insecure defaults that could expose user credentials or device access
+
+The following are **out of scope**:
+
+- Vulnerabilities in the Yarbo firmware or cloud service (report to Yarbo directly)
+- MQTT broker configuration issues (report to your broker vendor)
+- Issues only reproducible on Python versions below 3.11 (unsupported)
+- Issues in third-party dependencies (report upstream; we will update dependencies)

python_yarbo-0.1.0/.github/copilot.yml

@@ -0,0 +1,4 @@
+review:
+  auto_review: true
+  auto_fix: true
+  auto_merge: false

python_yarbo-0.1.0/.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+
+updates:
+  # Python dependencies
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "08:00"
+      timezone: Europe/Stockholm
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+
+  # GitHub Actions
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "08:00"
+      timezone: Europe/Stockholm
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci/cd"
+    commit-message:
+      prefix: "chore(actions)"

python_yarbo-0.1.0/.github/workflows/auto-create-pr.yml

@@ -0,0 +1,93 @@
+name: Auto-create PRs for Bot Branches
+
+on:
+  push:
+    branches:
+      - 'bugfix/**'
+      - 'fix/**'
+      - 'hotfix/**'
+      - 'copilot-fix/**'
+      - 'cursor-agent/**'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  create-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create PR if missing
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const branch = context.ref.replace('refs/heads/', '');
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const actor = context.actor;
+
+            console.log(`Pushed branch: ${branch} by ${actor}`);
+
+            // Only act if the author is a known bot/agent
+            const BOT_AUTHORS = new Set([
+              'copilot',
+              'cursor',
+              'cursor-agent',
+              'github-actions'
+            ]);
+
+            // context.actor for apps is often the app name without the [bot] suffix
+            const isBotAuthor = BOT_AUTHORS.has(actor) || actor.endsWith('[bot]');
+            
+            if (!isBotAuthor) {
+              console.log('Author is not a bot. Skipping auto-PR creation.');
+              return;
+            }
+
+            // Check if a PR already exists for this branch
+            const { data: pulls } = await github.rest.pulls.list({
+              owner,
+              repo,
+              head: `${owner}:${branch}`,
+              state: 'open'
+            });
+
+            if (pulls.length > 0) {
+              console.log(`PR already exists for branch ${branch}: #${pulls[0].number}`);
+              return;
+            }
+
+            // Get default branch to target
+            const { data: repoInfo } = await github.rest.repos.get({ owner, repo });
+            const defaultBranch = repoInfo.default_branch;
+            
+            // Format title from branch name (e.g. bugfix/autofix-test -> Bugfix/autofix test)
+            let title = branch.split('/').pop().replace(/-/g, ' ');
+            title = title.charAt(0).toUpperCase() + title.slice(1);
+            
+            if (branch.startsWith('bugfix/') || branch.startsWith('fix/')) {
+              title = `Fix: ${title}`;
+            }
+
+            console.log(`Creating PR for branch ${branch} targeting develop`);
+            
+            try {
+              const { data: newPr } = await github.rest.pulls.create({
+                owner,
+                repo,
+                title: title,
+                head: branch,
+                base: "develop",
+                body: `🤖 **Auto-created PR**\n\nThis branch (\`${branch}\`) was pushed by an AI agent/bot (\`${actor}\`), but no PR was opened. This PR was automatically created so CI can run and the \`copilot-automerge\` workflow can process it.`
+              });
+              
+              console.log(`✅ Created PR #${newPr.number}`);
+            } catch (error) {
+              console.error(`❌ Failed to create PR: ${error.message}`);
+              if (error.status === 422) {
+                 console.log("This usually means there are no commits between the base branch and the head branch.");
+              } else {
+                 throw error;
+              }
+            }

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

@@ -0,0 +1,103 @@
+name: CI
+
+# Run on every push to main/develop and every pull request (any target branch).
+# workflow_dispatch allows manual run from the Actions tab if triggers don't fire.
+on:
+  push:
+    branches: [main, develop]
+  pull_request: {}
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  checks: write
+
+jobs:
+  lint:
+    name: Lint (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+      - name: mypy type-check
+        run: mypy src/yarbo/
+
+  test:
+    name: test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run pytest with coverage
+        run: |
+          pytest --cov=yarbo --cov-report=xml --cov-report=term-missing \
+            --tb=short -q tests/
+
+      - name: Upload coverage artifact
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v6
+        with:
+          name: coverage-report
+          path: coverage.xml
+
+      # Uncomment when Codecov token is configured:
+      # - name: Upload to Codecov
+      #   if: matrix.python-version == '3.12'
+      #   uses: codecov/codecov-action@v4
+      #   with:
+      #     token: ${{ secrets.CODECOV_TOKEN }}
+      #     files: coverage.xml
+      #     fail_ci_if_error: false
+
+  # Gate jobs with stable names for branch protection (required status checks).
+  # Configure branch protection to require "Lint" and "Test" if you use 2 checks.
+  lint-gate:
+    name: Lint
+    runs-on: ubuntu-latest
+    needs: lint
+    if: always() && (needs.lint.result == 'success' || needs.lint.result == 'failure')
+    steps:
+      - run: test '${{ needs.lint.result }}' = success
+
+  test-gate:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: test
+    if: always() && (needs.test.result == 'success' || needs.test.result == 'failure')
+    steps:
+      - run: test '${{ needs.test.result }}' = success

python_yarbo-0.1.0/.github/workflows/copilot-automerge.yml

@@ -0,0 +1,112 @@
+name: Auto-merge Copilot Fixes
+
+on:
+  check_suite:
+    types: [completed]
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: write
+  checks: read
+  pull-requests: write
+
+jobs:
+  automerge:
+    runs-on: ubuntu-latest
+    if: >
+      github.event_name == 'check_suite' &&
+      github.event.check_suite.conclusion == 'success' ||
+      github.event_name == 'pull_request'
+    steps:
+      - name: Auto-merge eligible bot fix PRs
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+
+            // Bot authors that are allowed to auto-merge
+            const BOT_AUTHORS = new Set([
+              'copilot[bot]',
+              'cursor[bot]',
+              'cursor-agent',
+              'github-actions[bot]',
+            ]);
+
+            // Branch prefixes eligible for auto-merge (only when authored by bots)
+            const FIX_PREFIXES = [
+              'copilot-fix/', 'cursor-agent/',
+              'bugfix/', 'fix/', 'hotfix/',
+            ];
+
+            const { data: pulls } = await github.rest.pulls.list({
+              owner, repo, state: 'open', per_page: 50
+            });
+
+            const eligible = pulls.filter(pr => {
+              const branch = pr.head.ref;
+              const author = pr.user.login;
+              const isBotAuthor = BOT_AUTHORS.has(author);
+              const isFixBranch = FIX_PREFIXES.some(p => branch.startsWith(p));
+              return isBotAuthor && isFixBranch;
+            });
+
+            if (eligible.length === 0) {
+              console.log('No eligible bot fix PRs found');
+              return;
+            }
+
+            for (const pr of eligible) {
+              console.log(`Checking PR #${pr.number}: ${pr.title} (${pr.head.ref}) by ${pr.user.login}`);
+
+              const { data: checks } = await github.rest.checks.listForRef({
+                owner, repo, ref: pr.head.sha
+              });
+
+              const allChecks = checks.check_runs.filter(
+                c => c.name !== 'automerge' && c.name !== 'Auto-merge Copilot Fixes'
+              );
+
+              if (allChecks.length === 0) {
+                console.log(`  No checks found yet, skipping`);
+                continue;
+              }
+
+              const pending = allChecks.filter(c => c.status !== 'completed');
+              const failed = allChecks.filter(
+                c => c.status === 'completed' &&
+                     c.conclusion !== 'success' &&
+                     c.conclusion !== 'neutral' &&
+                     c.conclusion !== 'skipped'
+              );
+
+              if (pending.length > 0) {
+                console.log(`  ${pending.length} checks still pending, skipping`);
+                continue;
+              }
+
+              if (failed.length > 0) {
+                console.log(`  ${failed.length} checks failed: ${failed.map(c => c.name).join(', ')}`);
+                await github.rest.issues.createComment({
+                  owner, repo, issue_number: pr.number,
+                  body: `⚠️ Auto-merge skipped — ${failed.length} check(s) failed: ${failed.map(c => '`' + c.name + '`').join(', ')}.\n\nPlease fix manually or close this PR.`
+                });
+                continue;
+              }
+
+              console.log(`  All ${allChecks.length} checks passed, squash-merging...`);
+              try {
+                await github.rest.pulls.merge({
+                  owner, repo, pull_number: pr.number,
+                  merge_method: 'squash',
+                  commit_title: `${pr.title} (#${pr.number})`,
+                  commit_message: `Auto-merged bot fix PR.\n\nCo-authored-by: ${pr.user.login}`
+                });
+                console.log(`  ✅ Merged PR #${pr.number}`);
+              } catch (e) {
+                console.log(`  ❌ Merge failed: ${e.message}`);
+              }
+            }
+  issues: write