ops: wire frontend into shared task infrastructure (#269)

.github/workflows/pytest.yml

@@ -0,0 +1,37 @@
+name: Python Tests
+env:
+  PYTHON: "3.11"
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "ofd/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+  pull_request:
+    paths:
+      - "ofd/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: go-task/setup-task@v2
+        with:
+          version: 3.x
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ env.PYTHON }}
+
+      - name: Run tests
+        run: task test

.gitignore

@@ -8,3 +8,6 @@ dist/
 .cache/
 .env
 .task/
+htmlcov/
+.coverage
+local/

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing (Developer Setup)
+
+This guide is for developers working on the OFD codebase. For adding filament data, see the [main README](README.md).
+
+## Prerequisites
+
+- **uv** — `curl -LsSf https://astral.sh/uv/install.sh | sh` or see [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/)
+- **Node.js 22+**
+- **Task** — `brew install go-task` or see [taskfile.dev/installation](https://taskfile.dev/installation/)
+
+## Bootstrap
+
+```sh
+task setup   # installs Python deps (uv) + WebUI deps (npm)
+```
+
+## Common tasks
+
+```sh
+task test        # pytest
+task test-all    # pytest + Playwright E2E
+task lint        # ruff + svelte-check
+task serve       # start OFD API server
+```
+
+Run `task --list` for the full list.
+
+## Making a PR
+
+Run `task check` before opening a pull request — it covers lint, data validation, and all tests in one go.
+
+Keep each PR focused on a single logical change. Smaller, focused PRs are easier to review and less likely to conflict with concurrent work.
+
+## Frontend development
+
+No need to install Task just to work on the frontend — npm scripts work directly:
+
+```sh
+cd webui
+npm run dev        # dev server
+npm test           # Playwright E2E tests
+npm run check      # svelte-check type checking
+npm run build      # production build
+```
+
+> **Note:** The frontend currently uses npm directly. If we ever switch to a different package manager (bun, pnpm, etc.), adding a `Taskfile.yml` inside `webui/` would let all tooling and CI use `task` commands, making the package manager an implementation detail that only Taskfile needs to know about.

README.md

@@ -35,6 +35,8 @@ Click the **Fork** button in the top right of this page, a guide is [available h
 ### 3. Install our requirements
 If you don't have Git installed, [follow this guide](docs/installing-software.md#git). The OFD wrapper script will help you install Python and Node.js automatically (see step 5).
 
+Developers working on the codebase itself should also read [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ### 4. Download the database
 Download the database using either [this guide](docs/cloning.md) or by just using the command below, with `YOUR_USERNAME` replaced ofc!
 ```bash

Taskfile.yml

@@ -1,24 +1,52 @@
 version: "3"
 
+includes:
+  local:
+    taskfile: local/Taskfile.yml
+    optional: true # not checked in; create local/Taskfile.yml for personal tasks
+
+vars:
+  WEBUI_DIR: webui
+
+# NOTE: taskfile can be easily written to support different operating systems, but for simplicity we'll assume
+# mostly *nix-like operating systems are used, esp. MacOS and Linux, meaning most rules would work without
+# need for OS-specific variants
+
 tasks:
   # ── Setup ────────────────────────────────────────────────────────────────
 
   setup:
-    desc: Install Python dependencies
+    desc: Install all dependencies (Python + WebUI)
     # keep this task idempotent and without rules, it should instead depend on other smaller tasks to
     # make things ready for development. Ideally `task test` should just work after running this
-    deps: [.setup-python]
+    deps: [.setup-python, .install-playwright]
 
   .setup-python:
-    internal: true
     cmds:
-      - uv sync --frozen --extra dev
+      - uv sync --frozen
     sources:
       - pyproject.toml
       - uv.lock
     generates:
       - .venv/pyvenv.cfg
 
+  .setup-webui:
+    cmds:
+      - npm --prefix {{.WEBUI_DIR}} ci
+      - touch {{.WEBUI_DIR}}/node_modules/.webui-installed
+    sources:
+      - "{{.WEBUI_DIR}}/package.json"
+      - "{{.WEBUI_DIR}}/package-lock.json"
+    generates:
+      - "{{.WEBUI_DIR}}/node_modules/.webui-installed"
+
+  .install-playwright:
+    deps: [.setup-webui]
+    dir: "{{.WEBUI_DIR}}"
+    status:
+      - test -f node_modules/.playwright-installed
+    cmd: npm run test:install && touch node_modules/.playwright-installed
+
   # ── Python CLI ───────────────────────────────────────────────────────────
 
   validate:
@@ -51,13 +79,31 @@ tasks:
     cmds:
       - uv run -m ofd script {{.CLI_ARGS}}
 
+  # ── WebUI ────────────────────────────────────────────────────────────────
+
+  webui:
+    desc: Start the WebUI dev server (http://localhost:5173)
+    deps: [.setup-webui]
+    dir: "{{.WEBUI_DIR}}"
+    cmds:
+      - npm run dev
+
+  webui-build:
+    desc: Build the WebUI for production
+    deps: [.setup-webui]
+    dir: "{{.WEBUI_DIR}}"
+    cmds:
+      - npm run build
+
   # ── Code quality ─────────────────────────────────────────────────────────
 
   lint:
-    desc: Lint Python code with ruff
-    deps: [.setup-python]
+    desc: Lint all code (Python + WebUI)
+    deps: [.setup-python, .setup-webui]
     cmds:
       - uv run ruff check .
+      - uv run ruff format --check .
+      - npm --prefix {{.WEBUI_DIR}} run check
 
   lint-fix:
     desc: Lint and auto-fix Python code with ruff
@@ -67,28 +113,47 @@ tasks:
 
   format:
     desc: Format Python code with ruff
+    aliases: ["fmt"]
     deps: [.setup-python]
     cmds:
       - uv run ruff format .
 
   test:
-    desc: Run Python test suite with pytest
+    desc: Run Python tests (pytest)
     deps: [.setup-python]
     cmds:
       - uv run pytest --durations 3 --ff {{.CLI_ARGS}}
 
+  test-cov:
+    desc: Run Python tests with coverage (terminal + HTML report in htmlcov/)
+    deps: [.setup-python]
+    cmds:
+      - uv run pytest --cov=ofd --cov-report= --cov-report=html {{.CLI_ARGS}}
+      - uv run coverage report --skip-covered --show-missing --sort=cover
+
+  test-all:
+    desc: Run all tests (Python + WebUI)
+    deps: [test, .install-playwright]
+    cmds:
+      - npm --prefix {{.WEBUI_DIR}} run test
+
   requirements:
     desc: Regenerate requirements.txt from uv.lock (for pip users)
     deps: [.setup-python]
     cmds:
       - uv export --no-hashes -o requirements.txt
 
+  # ── Maintenance ──────────────────────────────────────────────────────────
+
+  clean:
+    desc: Remove Python cache files and build artefacts
+    cmds: # note: trailing plus makes command not to fail if there are no matches
+      - find ofd -type d -name __pycache__ -exec rm -rf {} +
+      - find ofd -type f -name "*.py[cod]" -delete
+      - find . -type d -name "*.egg-info" -exec rm -rf {} +
+
   # ── Compound ─────────────────────────────────────────────────────────────
 
   check:
-    desc: Lint, format-check, and test (CI equivalent)
-    deps: [.setup-python]
-    cmds:
-      - uv run ruff check .
-      - uv run ruff format --check .
-      - uv run pytest
+    desc: Lint, format-check, validate, and test — Python + WebUI (CI equivalent)
+    deps: [lint, validate, test-all]

pyproject.toml

@@ -3,46 +3,37 @@ name = "ofd"
 version = "1.0.0"
 description = "Open Filament Database CLI - Unified tooling for the OFD project"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.10" # NOTE: several other places assume 3.11 => require at least 3.11?
 license = { text = "MIT" }
-authors = [
-    { name = "Open Filament Collective" }
-]
+authors = [{ name = "Open Filament Collective" }]
 keywords = ["filament", "3d-printing", "database", "cli"]
 classifiers = [
-    "Development Status :: 4 - Beta",
-    "Environment :: Console",
-    "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Programming Language :: Python :: 3.14",
-    "Topic :: Database",
-    "Topic :: Utilities",
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Database",
+  "Topic :: Utilities",
 ]
 
 dependencies = [
-    "argcomplete>=3.1.0",
-    "jsonschema>=4.23.0",
-    "markdown>=3.0",
-    "ofd-validator>=0.5.1",
-    "iniconfig>=2.0.0",
-    "referencing>=0.30.0",
-    "PyYAML>=6.0",
-    "requests>=2.28.0",
+  "argcomplete>=3.1.0",
+  "jsonschema>=4.23.0",
+  "markdown>=3.0",
+  "ofd-validator>=0.5.1",
+  "iniconfig>=2.0.0",
+  "referencing>=0.30.0",
+  "PyYAML>=6.0",
+  "requests>=2.28.0",
 ]
 
-[project.optional-dependencies]
-dev = [
-    "pytest>=7.0.0",
-    "pytest-cov>=4.0.0",
-    "mypy>=1.0.0",
-    "ruff>=0.1.0",
-]
 
 [project.scripts]
 ofd = "ofd.__main__:main"
@@ -66,7 +57,7 @@ line-length = 100
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "UP", "B", "C4"]
-ignore = ["E501"]  # Line too long - handled by formatter
+ignore = ["E501"]                              # Line too long - handled by formatter
 
 [tool.mypy]
 python_version = "3.10"
@@ -78,3 +69,8 @@ ignore_missing_imports = true
 testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_functions = ["test_*"]
+
+# PEP 735 dependency groups — preferred over [project.optional-dependencies] for dev tooling.
+# uv includes these by default (no --extra flag needed).
+[dependency-groups]
+dev = ["mypy>=1.0.0", "pytest>=7.0.0", "pytest-cov>=4.0.0", "ruff>=0.1.0"]