mirrordash-sdk 0.2.0__tar.gz

mirrordash_sdk-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish to PyPI
+
+# Publishes mirrordash-sdk to PyPI when a tag vX.Y.Z is pushed (git tag v0.2.0 && git push origin v0.2.0).
+# PyPI trusts the publish job in the pypi environment (trusted publishing), so no token is stored.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  build:
+    name: Build package
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+
+      # PyPI publishes whatever pyproject.toml says, so a mismatched tag would ship the wrong version under it
+      - name: Check the tag matches pyproject.toml
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          VERSION=$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          if [ "$TAG" != "v$VERSION" ]; then
+            echo "::error::Tag $TAG does not match pyproject.toml version $VERSION (expected v$VERSION)"
+            exit 1
+          fi
+
+      - name: Build package distribution
+        run: uv build
+
+      - name: Save package
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  # Only this job can publish (id-token), and it runs no build code: it uploads what the build job made
+  publish:
+    name: Publish to PyPI
+    needs: [test, build]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mirrordash-sdk
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download package
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

mirrordash_sdk-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: Tests
+
+# Runs the tests on every push to master, and before every PyPI publish (publish.yml calls it).
+# The tests also generate each module template and run that module's own tests.
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+# A newer push replaces a running test of an older one; runs called by publish are never cancelled
+concurrency:
+  group: test-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'push' }}
+
+jobs:
+  test:
+    name: Tests
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Run tests
+        run: uv run pytest -q

mirrordash_sdk-0.2.0/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# IntelliJ IDEA
+.idea/
+*.iml
+

mirrordash_sdk-0.2.0/LICENSE.md

@@ -0,0 +1,137 @@
+# MirrorDash License
+
+Required Notice: Copyright (C) 2026 Jonas Öhlander (https://github.com/Menturan/MirrorDash)
+
+---
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

mirrordash_sdk-0.2.0/MODULE_AGENTS.md

@@ -0,0 +1,112 @@
+# MODULE_AGENTS.md — MirrorDash Module AI Agent Guide
+
+This file provides AI coding agents with instructions for creating, modifying, and testing custom modules for MirrorDash. Read this before developing any module.
+
+---
+
+## 1. Developer Environment & Scaffolding
+
+### Always Use the CLI Scaffolder
+Never build module packages by hand. Create a module from a template; pick `api` when it fetches data from a web API, `basic` otherwise:
+```bash
+uvx mirrordash-sdk create-module mirrordash-<name> --template api --description "<description>"
+```
+This gives the right Hatchling layout, entry point, settings form, translations and tests (`uv run pytest`).
+
+### A Local Mirror
+Inside the module directory, set up a local mirror with the module on it and start it (`http://localhost:8000/`, admin password `mirrordash`):
+```bash
+uvx mirrordash-sdk dev-setup -e
+uvx mirrordash-sdk start
+```
+`uvx mirrordash-sdk quickstart mirrordash-<name>` does all of the above in one go and opens the browser.
+
+---
+
+## 2. Coding Rules for Modules
+
+### Async & Non-Blocking Loops
+0. **Fetch with `self.fetch_json`**: never write your own HTTP code for JSON APIs. `data, error = await self.fetch_json(url, headers=..., params=...)` has a timeout, doesn't block, and on a failure returns the last good answer with `error` set (`rejected`, `offline`, `http <code>`, `invalid`). Put API keys in `headers`, never in the URL. Show `data` when there is any and a `.module-message` when `error` is set. In tests: `module.fetch_json = AsyncMock(return_value=(data, None))`.
+1. **Never block the event loop**: The module's `run_loop` is an async task. Do not use blocking operations (like `requests`, `urllib.request.urlopen`, or `time.sleep()`).
+2. **Wrap Synchronous I/O**: Use `await asyncio.to_thread(sync_func, ...)` to offload synchronous network or disk reads.
+3. **Use Async Sleeps**: Sleep only with `await asyncio.sleep(self.interval)`.
+4. **Handle Shutdown Cleanly**: Always catch and re-raise `asyncio.CancelledError` to allow graceful stops:
+   ```python
+   except asyncio.CancelledError:
+       # perform cleanup...
+       raise
+   ```
+
+### State & Persistence (OverlayFS Compliance)
+The system runs on a read-only root filesystem in production.
+- **Do not write to package directories**: Never open files relative to `__file__` for writing.
+- **Use Injected Paths**:
+  - `self.data_dir`: Write SQLite databases, configurations, and user state here (backed up).
+  - `self.cache_dir`: Write temporary data, HTTP response caches, and asset downloads here (excluded from backups).
+
+---
+
+## 3. Localization & Globals
+
+### Respect Global Configurations
+Never hardcode locales, metric units, or time zones. Fall back to settings defined under the global configuration:
+
+```python
+def __init__(self, config):
+    global_cfg = config.get("globals", {})
+    self.language = global_cfg.get("language", "en")
+    self.timezone = global_cfg.get("timezone", "Europe/Stockholm")
+    self.time_format = global_cfg.get("time_format", "24h")
+    self.temp_unit = global_cfg.get("temperature_unit", "C")
+```
+
+### Localization Mappings
+1. Place translation dictionaries in a `translations/` directory (e.g. `en.json`, `sv.json`) inside your package folder.
+2. The core automatically resolves and merges `translations` onto the Jinja2 render context as `translations` and attaches them to `self.translations`.
+3. Use the injected helper `self.translate("key", "default_val")` inside Python files.
+
+---
+
+## 4. UI Design & Styling Rules
+
+All module designs must adhere to the MirrorDash **Ethereal Design System** to preserve visual unity on a dark ambient mirror display:
+
+- **Transparent Backgrounds**: Widgets float on a pure black background. Never define a custom background color on the module wrapper.
+- **Building blocks first**: lay out with the classes every module gets (no CSS needed): `.module-header`, `.display-xl`/`.display-lg` for big numbers, `.flex-row`, `.flex-row-between` (label–value rows), `.flex-column`, `.text-primary`/`.text-secondary`, `.module-message` for errors and empty states. See `http://localhost:8000/design`.
+- **HUD Contrast**: For your own CSS, use the design tokens:
+  - Primary text/numbers: `var(--color-high-contrast)` (#ffffff)
+  - Secondary metadata/labels: `var(--color-standard-gray)` (#999999)
+  - Dimmed borders/dividers: `var(--color-dimmed-charcoal)` (#666666)
+- **Vector Icons**: Use Lucide outline icons via standard HTML attributes. Do not use emoji icons:
+  ```html
+  <i data-lucide="cloud-rain"></i>
+  ```
+- **Translation-Safe Responsive Fluidity**:
+  - **No fixed widths**: Do not use hardcoded pixel widths (`width: 150px`) for lists, columns, or layout elements. Swedish, German, or French text strings can be twice as long as English.
+  - Use Flexbox or CSS Grid with flexible sizing (`flex: 1`, `min-width: 0`, `max-content`).
+  - Use text-overflow ellipsis utilities to handle long strings gracefully.
+- **Shadow DOM Encapsulation**: Remember that modules render inside Shadow DOM. CSS beyond the building blocks goes in a template `<style>` block; other page styles do not cascade in, and global scripts (`document.querySelector`) cannot select your module's elements. Every template `<script>` gets `root` (the module's shadow root): query from it and keep timers on it (`clearInterval(root._timer); root._timer = setInterval(...)`). Never use `document.currentScript` (null in a shadow root) or globals (two instances would share them).
+
+---
+
+## 5. Configuration UI (Admin Dashboard Integration)
+
+Provide a `config_schema` dictionary or a `config_schema.json` to allow the user to modify settings from the Admin panel UI.
+
+- Use basic JSON schema types (`boolean`, `string`, `integer`).
+- Define title, description, and sensible default values.
+- If providing a set of selections, use `enum` to render a dropdown.
+- API keys, tokens and passwords get `"format": "password"`, so the admin page hides what is typed (`mirrordash-sdk validate` warns otherwise).
+- Don't declare `enabled`, `position`, `carousel_group`, `carousel_interval`, `max_width`, `max_height`, `z_index` or `opacity`: the core adds them to every module.
+- `self.render_template` / `self.translate` don't exist yet inside `__init__`; use them from `run_loop`.
+
+---
+
+## 6. Checklist for Module Commits
+Before submitting a pull request or code change:
+1. Ensure the package naming matches Hatchling requirements (folder uses hyphens, package/source uses underscores).
+2. Ensure you have provided a `README.md` at the module root containing:
+   - Clear description.
+   - Step-by-step setup instructions for API keys/tokens (if any).
+   - A `screenshot.png` at the package root, referenced in the markdown.
+3. Run the test suite: `uv run pytest`, and `uvx mirrordash-sdk validate .`.