mirrorwall 0.2.0__tar.gz

mirrorwall-0.2.0/.editorconfig

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

mirrorwall-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,136 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install ruff
+      - run: ruff format --check .
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install ruff
+      - run: ruff check .
+
+  types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: mypy src tests
+
+  boundaries:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: lint-imports
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python-version }}" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m "not live and not performance" --cov --cov-report=xml
+
+  tests-314-early-warning:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.14" }
+      # Deliberately unpinned: ci.lock is resolved on 3.13, and pinning a version that has no
+      # 3.14 wheels would defeat the purpose of an early warning.
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not live and not performance"
+
+  coverage:
+    needs: [tests]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m "not live and not performance" --cov --cov-report=term-missing --cov-fail-under=85
+
+  contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m contract
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        # gitleaks scans *history*, and `actions/checkout` fetches a single commit by default.
+        # For a push it is handed `<first-pushed>^..<last-pushed>`, so the parent of the first
+        # pushed commit has to be in the object store; in a depth-1 clone it is not, and git
+        # answers "unknown revision", which the action reports as exit code 1. It fails the same
+        # way whether or not a secret exists, so a green run would not have meant anything either.
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install pip-audit
+      # Audit the locked sets, not the job's own environment: a bare `pip-audit` here would
+      # inspect an environment containing only pip-audit itself (Security Standards §11).
+      - run: pip-audit --require-hashes -r requirements/ci.lock
+      - run: pip-audit --require-hashes -r requirements/release.lock
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+
+  install-check:
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - run: pip install dist/*.whl
+      - run: python -c "import mirrorwall"

mirrorwall-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+  workflow_dispatch:   # manual TestPyPI dry run; see publish-testpypi below
+
+permissions:
+  id-token: write   # required for PyPI Trusted Publishing
+  contents: write   # required to create the GitHub release
+
+jobs:
+  release:
+    # Tag pushes only. Without this, clicking "Run workflow" for the TestPyPI dry run below would
+    # also fire this job and publish to real PyPI — the exact opposite of a dry run.
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment: pypi   # must match the Environment name set on the PyPI trusted publisher
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      # Byte-for-byte the dry run's build chain below. A real release that resolved `build` and
+      # `hatchling` fresh from PyPI would not be the artifact the dry run proved.
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - run: pip install "dist/$(ls dist | grep .whl)[dev]"
+      - run: pytest -m "not live and not performance"
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+  publish-testpypi:
+    # Manual only, via Actions -> Release -> Run workflow. Packaging and Release Standards §6
+    # requires a successful TestPyPI publish ahead of a package's first real release; 0.2.0 is
+    # this package's first published version, so run this once before tagging v0.2.0. Later
+    # releases may skip it, or use it again as a dry run.
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - run: pip install "dist/$(ls dist | grep .whl)[dev]"
+      - run: pytest -m "not live and not performance"
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

mirrorwall-0.2.0/.gitignore

@@ -0,0 +1,100 @@
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# ---- Packaging / build backends ----
+pip-wheel-metadata/
+share/python-wheels/
+
+# ---- Testing / coverage ----
+.pytest_cache/
+.cache
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+*.py,cover
+htmlcov/
+nosetests.xml
+.hypothesis/
+
+# ---- Type checking / linting ----
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.pytype/
+
+# ---- Virtual environments ----
+.venv/
+venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+.python-version
+
+# ---- Distribution / dependency locking ----
+# requirements/*.lock is deliberately NOT ignored. The lock files are committed
+# inputs: CI and release jobs install from them with --require-hashes (Packaging
+# and Release Standards §4, Security Standards §11), so an ignored lock file
+# means a checkout that cannot build.
+
+# ---- Editors / OS ----
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ---- Suite runtime state (this component's local data) ----
+# The application writes to XDG paths at runtime (~/.config, ~/.local/share,
+# ~/.local/state per Master Architecture §1.2), never inside the repository.
+# These entries only guard against a developer pointing XDG_* at the repo
+# during local testing.
+.local/
+.config/
+*.sqlite3
+*.sqlite3-journal
+*.sqlite3-wal
+*.sqlite3-shm
+/data/
+/logs/
+/backups/
+/artifacts/
+/exports/
+
+# ---- Secrets ----
+# Per Security Standards §8: secrets are never committed. Config files may
+# only name where a secret comes from (*_env / *_file), never the value.
+.env
+.env.*
+*.key
+*.pem
+secrets.toml
+
+# ---- Node-free JS assets (MirrorWall consumers may still use a local tool) ----
+node_modules/
+
+# ---- Build artifacts from docs generation ----
+docs/api/openapi-v1.json.tmp

mirrorwall-0.2.0/.importlinter

@@ -0,0 +1,21 @@
+[importlinter]
+root_package = mirrorwall
+include_external_packages = True
+
+[importlinter:contract:no-application-imports]
+name = MirrorWall must not import applications
+type = forbidden
+source_modules = mirrorwall
+forbidden_modules =
+    freeweight
+    loadcoach
+    ideapress
+
+[importlinter:contract:no-sibling-packages]
+name = MirrorWall must not import sibling capability packages
+type = forbidden
+source_modules = mirrorwall
+forbidden_modules =
+    modelrack
+    sweatmeter
+    weightsdb

mirrorwall-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.4
+    hooks:
+      - id: gitleaks

mirrorwall-0.2.0/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to `mirrorwall` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
+[Semantic Versioning](https://semver.org/), pre-1.0 per
+packaging and release standards §3.
+
+## [Unreleased]
+
+## [0.2.0] — 2026-08-29
+
+### Changed
+- **`starlette>=1.3.1,<2`**, widened from `>=0.37,<1`. Two reasons, either sufficient. The 0.x line
+  carries PYSEC-2026-161, -248, -249, -2280 and -2281, none of which has a fix below 1.3.1, so
+  `pip-audit` fails the security gate against any lock the old cap allows. And the cap was wrong on
+  its own terms: FreeWeight and LoadCoach — the two applications this package exists to serve —
+  already run starlette 1.6 under fastapi 0.141, so `<1` made `mirrorwall` un-coinstallable with
+  its own consumers. The full suite passes unchanged on 1.6.0; no source change was needed.
+- CI installs from committed, hash-verified lockfiles (`requirements/ci.lock`,
+  `requirements/release.lock`) rather than an editable checkout, per Packaging Standards §4;
+  `pip-audit` audits those locks instead of an empty environment; `release.yml` gains the `pypi`
+  deployment environment, the manual TestPyPI dry run required before a first release, and a build
+  chain pinned byte-for-byte to the one the dry run proves. `[tool.coverage.run] source` now names
+  the importable package rather than `src/mirrorwall`, because a non-editable install reports 0 %
+  against a path-based source.
+
+  The `dev` extra moves to `pytest>=9.0.3,<10`, matching BaseAiCore, SetSpec, ModelRack and
+  SweatMeter: PYSEC-2026-1845 affects pytest through 9.0.2 and failed the security job.
+
+  `ci.lock` could not be compiled at all until `setspec 0.4.0` was published: this package requires
+  `setspec>=0.4,<0.5`, PyPI carried 0.3.0, and every CI job that installed from an index failed at
+  the `pip install` step for that reason. Those jobs had never been green.
+
+### Added
+- `tests/contract/test_public_api.py`: the published surface asserted in both directions, every
+  name resolved, `py.typed` shipped, and the templates, stylesheets, icon sprite and
+  `PACKAGE_TEMPLATE_DIR`/`PACKAGE_STATIC_DIR` roots asserted against the *installed* package. A
+  wheel that drops package data imports perfectly and then fails at a consumer's first render, so
+  the check has to run against the install rather than the checkout. The `contracts` CI job
+  collected nothing before this and failed with pytest's exit code 5.
+
+### Added
+- Phase 1: design tokens, the layout shell and the core components, extracted from FreeWeight's
+  shipped UI and generalized until nothing in the package knows what an application is.
+  - `static/css/{tokens,reset,layout,components,tables,charts}.css` plus `tokens.json`. The
+    palette is byte-identical to the one FreeWeight proved in production; `--mw-accent` and its
+    three relatives are the per-application override point, and nothing else needs to change.
+  - `templates/mirrorwall/{base,components,telemetry_bar}.html`: a shell of slots — header,
+    navigation, telemetry bar, content, footer, theme bootstrap — and macros for button, input,
+    select, checkbox, switch, card, table, badge, tabs, drawer, dialog, toast, tooltip, progress,
+    empty state, pagination, filter bar, key-value list, JSON viewer and chart container.
+  - `static/js/{theme,table,drawer,dialog,toast}.js`: progressive enhancement only. Every page is
+    complete before any of them loads (ADR-0020).
+  - `static/icons/sprite.svg`: sixteen original glyphs, stroked with `currentColor` so they
+    re-theme with the page.
+  - `templating.py`: `create_template_environment` — autoescaping on, `StrictUndefined`, the
+    package's macros on the search path behind the application's own.
+  - `filters.py`: `bytes_human`, `duration_human`, `timestamp`, `measurement`, `truncate_middle`,
+    `json_pretty`, `asset_url`, and the `supported` test. `measurement` renders an em dash with
+    the producer's own reason for an absent reading — never a zero (ADR-0016), and it is the only
+    sanctioned way a template touches a `Measurement`, because `UNSUPPORTED` refuses `__bool__`.
+  - `THIRD_PARTY_NOTICES.md` and `static/ASSETS.sha256`: the vendoring discipline, with every
+    shipped asset's digest recomputed and checked by the test suite.
+  - Tests: contrast computed from the tokens (4.5:1 text, 3:1 UI, both themes, 21 pairs each);
+    a term scan over names and markup in every shipped file; component snapshots asserting the
+    ARIA each pattern requires; escaping; `StrictUndefined`; package data present in a wheel that
+    the test actually builds.
+
+- Phase 2: the backend helpers — envelopes, request IDs, SSE, static mounting, health.
+  - `sse.py`: `Event`, `Subscription`, `EventBroker`, the `EventSource` protocol and
+    `sse_response`. The stream **subscribes before it replays** and drops from the live queue
+    anything the replay already emitted, which is what makes a reconnect gap-free and
+    duplicate-free at once. Every call into the synchronous, database-backed source — opening the
+    subscription, each bounded replay batch, closing it — goes through `anyio.to_thread.run_sync`
+    (ADR-0003 §6-8); the steady-state stream is served from the in-memory fan-out and takes no
+    threadpool slot at all, which is what makes 200 concurrent subscribers affordable against a
+    40-thread pool. Subscriber queues are bounded and drop the oldest, counting what they dropped.
+    Every frame carries the SetSpec event envelope except `event: token`, which is bare — the one
+    documented exception (ADR-0025 §3).
+  - `middleware.py`: `RequestIdMiddleware` (validate or generate, bind to the logging context,
+    echo `X-Request-ID`, add `X-Response-Time-Ms`), `HostValidationMiddleware` and
+    `CsrfMiddleware` (ADR-0026 §1-2), both running before routing and before authentication.
+  - `responses.py`: `json_response`, `error_response`, `paginated_response`, `clamp_limit`.
+  - `static.py`: `mount_static` and a content-hashing `asset_url` that replaces the Phase 1
+    filter at the same template seam, with immutable cache headers, traversal **and** symlink
+    containment.
+  - `health.py`: `ComponentStatus`, `ComponentHealth`, `health_payload`, `worst_status`.
+    `NOT_CONFIGURED` never worsens a roll-up: a component nobody asked for is not a fault.
+  - `static/js/{sse,telemetry}.js`: the client half. Events are applied idempotently by sequence,
+    so a reconnect's redelivered boundary event does not duplicate a row; an absent telemetry
+    reading renders an em dash with its reason, never `0`.
+  - `sse_response(..., terminal_events=...)`: a finite stream — a generation, a benchmark run —
+    closes after its own last event instead of holding a connection open for a producer that has
+    nothing left to say. Empty by default, because an open-ended stream has no such event.
+  - Every SSE property is proved by mutation: replay-before-subscribe, a missing dedupe, a
+    blocking `replay`, an unbounded queue and a missing cleanup were each applied to the module
+    and each confirmed to fail the corresponding test before it was considered finished.
+
+### Changed
+- `.importlinter` used the plural `root_packages` with a bare string, which import-linter 2.x
+  iterates character by character; and it lacked `include_external_packages`, required whenever a
+  `forbidden` contract names modules outside the root package. Both fixed. `[tool.mypy]` gained
+  `mypy_path`/`explicit_package_bases`, and the coverage floor moved from 85% to the 95% shared
+  packages carry. (The same four defects were found and fixed in two other scaffolds this
+  milestone; a scaffold from the same generator should be checked for them before its first gate.)
+- Declared `anyio>=4,<5` directly. Phase 2's `sse_response` dispatches every call into the
+  synchronous `EventSource` with `anyio.to_thread.run_sync` (ADR-0003 §6-8); Starlette pulls anyio
+  in transitively, but a module this package imports directly is declared directly.
+- Repository scaffold generated from the suite's development plan (no functional code yet).

mirrorwall-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to MirrorWall
+
+This repository is one component of the Local AI Suite. Before changing anything, read
+`docs/packages/mirrorwall/spec.md` and the current
+phase in `development-plan.md` — both are in this repository's `docs/` folder, copied from the suite's
+central documentation set so this repository can be worked on independently.
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+```
+
+## Required reading, in order
+
+1. This component's spec — purpose, scope, non-goals, contracts.
+2. `development-plan.md` in the same folder — the phase you are implementing, its acceptance criteria and its tests.
+
+## Rules that apply to every change here
+
+* Follow the architecture's dependency direction.
+  This repository's `.importlinter` enforces it in CI; do not weaken that file to make an import work.
+* No business logic in a route handler or CLI command body — both call one service method and render
+.
+* An unavailable measurement is `Unsupported`, never zero, never `None` used as a substitute
+.
+* Prompts are versioned JSON records, not Python string literals.
+* Every phase's acceptance criteria in `development-plan.md` must be demonstrable, not merely
+  test-covered — the plan states what to run and what a person should see.
+
+## Before opening a pull request
+
+```bash
+ruff format --check .
+ruff check .
+mypy src tests
+lint-imports
+pytest -m "not live and not performance"
+```
+
+All of the above run in CI (`.github/workflows/ci.yml`); a red CI run blocks merge.
+
+## Commit style
+
+Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `perf:`, `build:`,
+`ci:`), with `!` or a `BREAKING CHANGE:` footer for breaking changes. Update `CHANGELOG.md` under
+`## [Unreleased]` for any user-visible change.