groundskeeping 0.1.0__tar.gz

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

@@ -0,0 +1,66 @@
+name: "🐞 Bug Report"
+description: Report a reproducible bug.
+type: "Bug"
+body:
+  - type: checkboxes
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One or two sentences describing the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Steps and/or a minimal code example that reproduces the issue. Wrap code in triple backticks.
+      placeholder: |
+        1. Import X and call Y with Z
+        2. Observe error
+
+        ```python
+        # minimal example
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error output
+      description: Full traceback if applicable. Formatted automatically.
+      render: python-traceback
+
+  - type: textarea
+    id: system
+    attributes:
+      label: System info
+      description: |
+        Run this in your environment and paste the output:
+
+        ```shell
+        python <(curl -s https://raw.githubusercontent.com/AustralianCancerDataNetwork/cava-devops/main/scripts/cava_system_info.py)
+        ```
+      render: shell

groundskeeping-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discussions
+    url: https://github.com/orgs/AustralianCancerDataNetwork/discussions
+    about: Questions and general discussion about the CAVA stack.

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

@@ -0,0 +1,32 @@
+name: "🚀 Feature Request"
+description: Propose a new feature or enhancement.
+type: "Feature"
+body:
+  - type: checkboxes
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues and this has not been requested before.
+          required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: What are you trying to do that you currently cannot?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would you like this to work?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you considered and why you ruled them out.

groundskeeping-0.1.0/.github/ISSUE_TEMPLATE/not_working.yml

@@ -0,0 +1,65 @@
+name: "❗ Something is not working"
+description: Something behaves unexpectedly but you are not sure if it is a bug.
+body:
+  - type: checkboxes
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues for this problem.
+          required: true
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Problem summary
+      description: 1-2 sentences describing what is not working.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Steps and/or a minimal code example. Wrap code in triple backticks.
+      placeholder: |
+        1. Import X and call Y with Z
+        2. Observe unexpected behaviour
+
+        ```python
+        # minimal example
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual outcome
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected outcome
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error messages
+      description: Full traceback if applicable. Formatted automatically.
+      render: python-traceback
+
+  - type: textarea
+    id: system
+    attributes:
+      label: System info
+      description: |
+        Run this in your environment and paste the output:
+
+        ```shell
+        python <(curl -s https://raw.githubusercontent.com/AustralianCancerDataNetwork/cava-devops/main/scripts/cava_system_info.py)
+        ```
+      render: shell

groundskeeping-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## Summary
+
+<!-- What does this PR do? This text becomes the changelog entry — write it for a reader who will see it months from now, not for the reviewer reading the diff. Leave blank for chore PRs. -->
+
+## Checklist
+
+- [ ] Applied exactly one label (`breaking`, `feature`, `fix`, `dependencies`, or `chore`)
+- [ ] Tests pass locally (`uv run pytest -q`)
+- [ ] Lint passes (`uv run ruff check .`)

groundskeeping-0.1.0/.github/release-drafter.yml

@@ -0,0 +1,31 @@
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+commitish: main
+
+categories:
+  - title: Breaking Changes
+    labels: ['breaking']
+  - title: Features
+    labels: ['feature']
+  - title: Fixes
+    labels: ['fix']
+  - title: Dependencies
+    labels: ['dependencies']
+
+template: |
+  $CHANGES
+
+change-template: '- **$TITLE** (#$NUMBER) @$AUTHOR'
+
+version-resolver:
+  major:
+    labels: ['breaking']
+  minor:
+    labels: ['feature']
+  patch:
+    labels: ['fix', 'dependencies']
+  default: patch
+
+exclude-labels: ['chore']
+
+autolabeler: []

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

@@ -0,0 +1,10 @@
+name: CI
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+jobs:
+  label-gate:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/label-gate.yml@main
+  build-test:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/build-test.yml@main

groundskeeping-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,10 @@
+name: Deploy Docs
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  deploy:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/deploy-docs.yml@main

groundskeeping-0.1.0/.github/workflows/merge.yml

@@ -0,0 +1,13 @@
+name: Release Update
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+permissions:
+  contents: write
+  pull-requests: read
+jobs:
+  draft:
+    if: github.event.pull_request.merged == true
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/release-drafter.yml@main
+    secrets: inherit

groundskeeping-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish
+on:
+  push:
+    tags: ['v*']
+jobs:
+  build:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/publish.yml@main
+  publish:
+    # Inline: PyPI OIDC checks job_workflow_ref, which must point to this file.
+    # Moving pypa/gh-action-pypi-publish into cava-devops would break the trusted publisher.
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/groundskeeping
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: pypa/gh-action-pypi-publish@release/v1

groundskeeping-0.1.0/.gitignore

@@ -0,0 +1,228 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+.vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+*.ipynb
+_temp/

groundskeeping-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+## Development setup
+
+```bash
+uv sync --all-extras --dev
+uv run pytest -q
+uv run ruff check .
+```
+
+## Opening a pull request
+
+1. Apply **exactly one** label before merging:
+
+   | Label | When to use |
+   |---|---|
+   | `breaking` | Public API change, backward-incompatible |
+   | `feature` | New functionality, backward-compatible |
+   | `fix` | Bug fix |
+   | `dependencies` | Dependency version update |
+   | `chore` | CI changes, refactoring, test additions, docs — anything that does not affect the public-facing package. Bypasses the label gate; excluded from the changelog and does not bump the version. |
+
+2. When merging (squash), write a clear extended description in the merge dialog. That text — not the PR's opening description — becomes the changelog entry for this change. Leave it blank for `chore` PRs.
+
+## Versioning and releases
+
+Versions are derived from git tags; there is no version string in any source file. Releases are triggered by a maintainer publishing the standing draft release on the repository's Releases page. There is no automated commit-back to `main`.

groundskeeping-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: groundskeeping
+Version: 0.1.0
+Summary: Reusable Textual operator shell, workbench, configuration browser, and telemetry primitives.
+Author: UNSW CAVA platform tooling
+Requires-Python: >=3.12
+Requires-Dist: oa-configurator<0.3,>=0.1.2
+Requires-Dist: textual<9,>=8.2
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.7.1; extra == 'dev'
+Requires-Dist: mkdocs>=1.6.1; extra == 'dev'
+Requires-Dist: mkdocstrings-python>=2.0.1; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: ty>=0.0.59; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# groundskeeping
+
+`groundskeeping` is a reusable Textual shell for operator tools that help people care for a working environment: setup checks, configuration, queues, telemetry, tuning, and long-running operations.
+
+The package provides the shared operating frame. A consumer application provides the domain. Keep that distinction close and most design decisions become simpler.
+
+## The Shape Of An App
+
+A `groundskeeping` app starts with one `OperatorAppSpec`.
+
+The spec names the app, orders the pages, registers the actions, and supplies the policies that decide whether work may run. It is the composition root: everything application-specific should arrive there from the consumer, not through global lookup inside the shared package.
+
+Pages are owned by the consumer and are ordinary Textual widgets. The shell mounts them once, activates and deactivates them as the operator moves between tabs, and preserves page-local state. A page receives a narrow `PageContext`; it does not receive the whole app.
+
+The default page surface is the workbench:
+
+- catalogue on the left;
+- rows or tree content on the upper right; and
+- selected detail on the lower right.
+
+Pages render package-owned view models such as `CatalogueItem`, `TableView`, `TreeView`, `EmptyView`, `TextView`, and `KeyValueView`. Domain objects should be translated before they reach the workbench. That keeps the shared shell reusable and keeps consumer language in the consumer.
+
+## Setup Pages
+
+A setup page should answer a concrete operator question: "can this environment do the work I am about to ask of it?"
+
+The page should normally live in the consumer package and use consumer services to inspect the environment. `groundskeeping` supplies the rendering and action contracts; it should not know what "ready" means for Groundworkers, CAVA, or any future application.
+
+A good setup page usually has:
+
+- a catalogue of setup areas, such as config, database, runtime, model server, paths, or credentials;
+- a landing `TreeView` summarising overall readiness;
+- a `TableView` for repeated checks where scanning matters;
+- `KeyValueView` detail for the selected check;
+- one or two safe verification actions; and
+- an operation policy that describes effects in the consumer's own vocabulary.
+
+Start read-only. Verification actions are a good first step because they exercise the shell, action contracts, progress reporting, and failure presentation without taking ownership of durable setup changes too early.
+
+## Actions And Jobs
+
+Actions are declarations plus runners.
+
+An `ActionSpec` describes the operator-facing command: label, summary, fields, resources, effects, cancellation mode, and runner. `FieldSpec` parses and redacts input before it reaches the runner. The runner receives an `ActionContext` with progress and cancellation, so long-running work can report what it is doing without importing widgets.
+
+A shell job is work launched by this TUI process. It is not a durable processing queue. Use `JobManager` and `JobPolicy` to gate in-process work and show progress; keep queue state, retries, leases, and durable records inside the consumer.
+
+## Configuration
+
+`groundskeeping.configurator` understands the public shape of `oa-configurator` stack configuration well enough to inspect and present it safely. It can build snapshots, section views, drafts, redacted diffs, and apply intents.
+
+It does not write TOML. Persistence belongs to the public `oa-configurator` mutation API and to the consumer's operation policy. That separation protects comments, secrets, external edits, and tenant-specific safety rules.
+
+Consumer applications can add `ConfigResourceAdapter` implementations for resource types that need better labels, choices, validation, verification, or post-apply effects.
+
+## Telemetry
+
+Telemetry has a headless core and Textual widgets layered above it.
+
+`groundskeeping.telemetry` contains source protocols, availability, normalized metrics, snapshots, and sampling runtime. It must remain free of Textual imports so collectors can be tested and reused outside a running app.
+
+`groundskeeping.widgets.telemetry` renders snapshots. Widgets should bind to metric keys and capabilities, not concrete provider classes. A GPU card, for example, should care about accelerator utilisation and memory metrics; it should not need to know whether the source is NVIDIA, Apple Silicon, or something added later.
+
+Consumers own domain telemetry: queue depth, pipeline progress, database state, workload throughput, and tuning interpretation.
+
+## Ownership Boundary
+
+`groundskeeping` owns:
+
+- route validation and page activation;
+- mounted-page state preservation;
+- the shared workbench surface;
+- generic view models;
+- action, field, progress, cancellation, and job contracts;
+- in-process job gating;
+- read-only configuration inspection and draft/diff models;
+- Textual-free infrastructure telemetry contracts; and
+- reusable widgets that render normalized models.
+
+Consumers own:
+
+- every production page;
+- domain presenters, controllers, and services;
+- queue semantics and durable records;
+- YAML or other consumer configuration formats;
+- resource-specific `oa-configurator` adapters;
+- model calls, database access, and runtime execution;
+- domain telemetry and tuning algorithms;
+- operation safety policy; and
+- application branding and help text.
+
+## Commenting Style
+
+Write comments for the next person adapting the tool.
+
+Good comments explain why a boundary exists, what operator-facing behaviour depends on it, and where domain logic should stay. They are especially useful around Textual lifecycle methods, event routing, worker handoffs, cancellation, secret redaction, and extension points.
+
+Prefer comments that preserve intent over comments that narrate syntax. Explain why row events return to the active page through the workbench surface. Do not explain that a loop iterates over rows.
+
+If a future maintainer is likely to wonder "why is this shaped this way?", leave them a small signpost.
+
+## Running The Demo
+
+```bash
+uv run groundskeeping
+```
+
+The demo composes overview, configuration, and telemetry pages. It also registers a small action so the app spec and action registry can be exercised without a consumer application.
+
+## Running Tests
+
+```bash
+uv run --extra dev pytest -q
+```
+
+The tests cover route validation, app startup, action and job contracts, configurator redaction, telemetry import boundaries, and consumer dependency boundaries.