3d-review 0.1.0__tar.gz

3d_review-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konstantinos Georgiou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

3d_review-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: 3d-review
+Version: 0.1.0
+Summary: Review a 3D design with an assistant: a web bench where a person marks what is wrong on the model, a ledger of which build step moved what, a requirement board whose rows are proven able to fail, and a Penpot bridge
+Author: Konstantinos Georgiou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/drkostas/3d-review
+Keywords: 3d,design review,3d-printing,trimesh,penpot,assistant
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: 3d-base>=0.2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: trimesh>=4.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: penpot
+Requires-Dist: shapely>=2.0; extra == "penpot"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# 3d-review
+
+3d-review is what I used to review a 3D design together with an AI assistant, while designing a 3D-printed toy. The person shows what is wrong on the model itself, the assistant answers with pictures, and the assistant has to prove that what the person asked for is still true after every rebuild.
+
+![The review bench with three parts loaded](docs/bench.png)
+
+It has four parts, and each one can be used alone.
+
+- **The bench** is a web page that shows the model's stages. The person picks a part, moves or turns a ghost of it, marks a spot, writes what is wrong and submits. Each submission keeps the before and after pictures, the exact transform and the words, and becomes a thread the assistant answers. Replies are drawn from the person's own camera. "Publish all" notifies the assistant once for everything new.
+- **The ledger** records which step of a build pipeline moved or rebuilt a part the person cares about, including code that runs between two steps. A placement the person locked stays locked, or the ledger says which line moved it.
+- **The board** has one row per thing the person asked for, each with a measurement and a bar. A planted fault proves each row can go red, so a green board is not a green check over a hole.
+- **The Penpot bridge** pushes 2D outlines in millimetres into a self-hosted Penpot file and reads the person's edits back.
+
+## Install
+
+```bash
+pip install 3d-review
+pip install "3d-review[penpot]"    # adds shapely, for cutting outlines in the Penpot bridge
+```
+
+In Python it is imported as `review3d`. It uses [3d-base](https://github.com/drkostas/3d-base) for pictures.
+
+## The bench
+
+```bash
+3d-review stages body.stl arm.stl wheel.stl -o model     # writes model/stages.json and model/stages/parts.glb
+cp "$(python -c 'import review3d,os;print(os.path.dirname(review3d.__file__))')/bench/bench.example.toml" model/bench.toml
+3d-review bench --config model/bench.toml --port 8766
+```
+
+Then open `http://localhost:8766/twist.html`. `threads.html` lists every thread. From Python, `review3d.stages.write_stages` writes any number of stages (for example "parts", "assembled" and "printed") from `{stage: {part: trimesh.Trimesh}}`, and `review3d.bench.server.Bench` takes your own notifier, rebuild hook and freshness check. The default notifier appends a line to a file, so the assistant can watch that file.
+
+The bench never changes the model. A submission is a request, and applying it is a separate step.
+
+## The ledger
+
+```python
+from review3d import ledger
+import mybuild
+
+ledger.install(mybuild, watch={"arm", "wheel"}, pipeline="build")
+mybuild.build()
+print(ledger.missing(mybuild, "build"))   # steps the pipeline calls that the ledger does not wrap
+ledger.write("ledger.json")
+```
+
+The steps are read from the pipeline's own source, so a step added later is never invisible to it. Moves are measured exactly (the rigid transform between the vertices before and after), and a part whose vertex count changed is reported as rebuilt.
+
+## The board
+
+```python
+import types
+import trimesh
+from review3d.board import Board, Row, at_most, mirror_asymmetry
+
+design = types.SimpleNamespace(body=trimesh.load("part.stl"))   # any object your rows can read
+
+board = Board([Row("symmetric", "the two sides match", lambda d: mirror_asymmetry(d.body, normal=(1, 0, 0)), at_most(0.2), "mm")])
+
+@board.fault("symmetric")
+def bump(design):
+    lump = trimesh.creation.box(extents=(2, 2, 2))
+    lump.apply_translation([6, 0, 0])
+    design.body = trimesh.util.concatenate([design.body, lump])
+
+board.report(design)
+print(board.proof_table(board.prove(design)))
+```
+
+A row whose measurement fails or has no input reads unknown, never green. A row with no fault reads unproven. The measurements include mirror symmetry, sphericity, surface roughness, gap and penetration between parts, tipping, first-layer area, overhang share, length along an axis, axis angle, bow, out of round, tunnels, and the brightness of a rendered view.
+
+## The Penpot bridge
+
+```python
+from review3d.penpot import PenpotClient, PenpotSettings
+
+client = PenpotClient(PenpotSettings.load("penpot.toml"))   # or PENPOT_* environment variables
+result = client.push({"plate": [(0, 0), (60, 0), (60, 20), (0, 20)]})
+edited = client.pull(file_id=result.file_id)
+```
+
+One Penpot unit is one millimetre. Keep credentials in the settings file or the environment, never in code.
+
+## Claude Code skill
+
+```bash
+3d-review skill            # copies it to ~/.claude/skills/3d-review
+```
+
+The skill is the review loop as we ran it. It covers writing the person's requirements as rows before building, proving each row, answering threads with pictures, keeping locks through rebuilds, asking questions with pictures on the bench instead of in words, and the failures that taught each rule.
+
+## Limits
+
+- The bench is meant for one person and one assistant on a trusted network. It has no login, so keep it on `127.0.0.1` or behind a private network.
+- The board's measurements are general. The rows that matter for your design are yours to write.
+- The bench includes three.js r169 (MIT, licence in `bench/static/vendor`).
+- Reading through Penpot's exporter depends on the exporter service working. The default `pull` reads the stored geometry and does not need it.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test,penpot]'
+.venv/bin/pytest
+```
+
+The Penpot tests use a fake server. Set `PENPOT_URL` and a token to run the live round trip too.
+
+## License
+
+MIT

3d_review-0.1.0/README.md

@@ -0,0 +1,110 @@
+# 3d-review
+
+3d-review is what I used to review a 3D design together with an AI assistant, while designing a 3D-printed toy. The person shows what is wrong on the model itself, the assistant answers with pictures, and the assistant has to prove that what the person asked for is still true after every rebuild.
+
+![The review bench with three parts loaded](docs/bench.png)
+
+It has four parts, and each one can be used alone.
+
+- **The bench** is a web page that shows the model's stages. The person picks a part, moves or turns a ghost of it, marks a spot, writes what is wrong and submits. Each submission keeps the before and after pictures, the exact transform and the words, and becomes a thread the assistant answers. Replies are drawn from the person's own camera. "Publish all" notifies the assistant once for everything new.
+- **The ledger** records which step of a build pipeline moved or rebuilt a part the person cares about, including code that runs between two steps. A placement the person locked stays locked, or the ledger says which line moved it.
+- **The board** has one row per thing the person asked for, each with a measurement and a bar. A planted fault proves each row can go red, so a green board is not a green check over a hole.
+- **The Penpot bridge** pushes 2D outlines in millimetres into a self-hosted Penpot file and reads the person's edits back.
+
+## Install
+
+```bash
+pip install 3d-review
+pip install "3d-review[penpot]"    # adds shapely, for cutting outlines in the Penpot bridge
+```
+
+In Python it is imported as `review3d`. It uses [3d-base](https://github.com/drkostas/3d-base) for pictures.
+
+## The bench
+
+```bash
+3d-review stages body.stl arm.stl wheel.stl -o model     # writes model/stages.json and model/stages/parts.glb
+cp "$(python -c 'import review3d,os;print(os.path.dirname(review3d.__file__))')/bench/bench.example.toml" model/bench.toml
+3d-review bench --config model/bench.toml --port 8766
+```
+
+Then open `http://localhost:8766/twist.html`. `threads.html` lists every thread. From Python, `review3d.stages.write_stages` writes any number of stages (for example "parts", "assembled" and "printed") from `{stage: {part: trimesh.Trimesh}}`, and `review3d.bench.server.Bench` takes your own notifier, rebuild hook and freshness check. The default notifier appends a line to a file, so the assistant can watch that file.
+
+The bench never changes the model. A submission is a request, and applying it is a separate step.
+
+## The ledger
+
+```python
+from review3d import ledger
+import mybuild
+
+ledger.install(mybuild, watch={"arm", "wheel"}, pipeline="build")
+mybuild.build()
+print(ledger.missing(mybuild, "build"))   # steps the pipeline calls that the ledger does not wrap
+ledger.write("ledger.json")
+```
+
+The steps are read from the pipeline's own source, so a step added later is never invisible to it. Moves are measured exactly (the rigid transform between the vertices before and after), and a part whose vertex count changed is reported as rebuilt.
+
+## The board
+
+```python
+import types
+import trimesh
+from review3d.board import Board, Row, at_most, mirror_asymmetry
+
+design = types.SimpleNamespace(body=trimesh.load("part.stl"))   # any object your rows can read
+
+board = Board([Row("symmetric", "the two sides match", lambda d: mirror_asymmetry(d.body, normal=(1, 0, 0)), at_most(0.2), "mm")])
+
+@board.fault("symmetric")
+def bump(design):
+    lump = trimesh.creation.box(extents=(2, 2, 2))
+    lump.apply_translation([6, 0, 0])
+    design.body = trimesh.util.concatenate([design.body, lump])
+
+board.report(design)
+print(board.proof_table(board.prove(design)))
+```
+
+A row whose measurement fails or has no input reads unknown, never green. A row with no fault reads unproven. The measurements include mirror symmetry, sphericity, surface roughness, gap and penetration between parts, tipping, first-layer area, overhang share, length along an axis, axis angle, bow, out of round, tunnels, and the brightness of a rendered view.
+
+## The Penpot bridge
+
+```python
+from review3d.penpot import PenpotClient, PenpotSettings
+
+client = PenpotClient(PenpotSettings.load("penpot.toml"))   # or PENPOT_* environment variables
+result = client.push({"plate": [(0, 0), (60, 0), (60, 20), (0, 20)]})
+edited = client.pull(file_id=result.file_id)
+```
+
+One Penpot unit is one millimetre. Keep credentials in the settings file or the environment, never in code.
+
+## Claude Code skill
+
+```bash
+3d-review skill            # copies it to ~/.claude/skills/3d-review
+```
+
+The skill is the review loop as we ran it. It covers writing the person's requirements as rows before building, proving each row, answering threads with pictures, keeping locks through rebuilds, asking questions with pictures on the bench instead of in words, and the failures that taught each rule.
+
+## Limits
+
+- The bench is meant for one person and one assistant on a trusted network. It has no login, so keep it on `127.0.0.1` or behind a private network.
+- The board's measurements are general. The rows that matter for your design are yours to write.
+- The bench includes three.js r169 (MIT, licence in `bench/static/vendor`).
+- Reading through Penpot's exporter depends on the exporter service working. The default `pull` reads the stored geometry and does not need it.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test,penpot]'
+.venv/bin/pytest
+```
+
+The Penpot tests use a fake server. Set `PENPOT_URL` and a token to run the live round trip too.
+
+## License
+
+MIT

3d_review-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "3d-review"
+version = "0.1.0"
+description = "Review a 3D design with an assistant: a web bench where a person marks what is wrong on the model, a ledger of which build step moved what, a requirement board whose rows are proven able to fail, and a Penpot bridge"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Konstantinos Georgiou" }]
+dependencies = ["3d-base>=0.2.0", "numpy>=1.24", "trimesh>=4.0", "scipy>=1.10", "tomli>=2; python_version < '3.11'"]
+keywords = ["3d", "design review", "3d-printing", "trimesh", "penpot", "assistant"]
+classifiers = ["Programming Language :: Python :: 3", "Topic :: Multimedia :: Graphics :: 3D Modeling"]
+
+[project.urls]
+Homepage = "https://github.com/drkostas/3d-review"
+
+[project.scripts]
+3d-review = "review3d.cli:main"
+
+[project.optional-dependencies]
+penpot = ["shapely>=2.0"]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+review3d = ["skill/SKILL.md", "bench/static/*.html", "bench/static/vendor/**/*", "bench/bench.example.toml"]

3d_review-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

3d_review-0.1.0/src/3d_review.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: 3d-review
+Version: 0.1.0
+Summary: Review a 3D design with an assistant: a web bench where a person marks what is wrong on the model, a ledger of which build step moved what, a requirement board whose rows are proven able to fail, and a Penpot bridge
+Author: Konstantinos Georgiou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/drkostas/3d-review
+Keywords: 3d,design review,3d-printing,trimesh,penpot,assistant
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: 3d-base>=0.2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: trimesh>=4.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: penpot
+Requires-Dist: shapely>=2.0; extra == "penpot"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# 3d-review
+
+3d-review is what I used to review a 3D design together with an AI assistant, while designing a 3D-printed toy. The person shows what is wrong on the model itself, the assistant answers with pictures, and the assistant has to prove that what the person asked for is still true after every rebuild.
+
+![The review bench with three parts loaded](docs/bench.png)
+
+It has four parts, and each one can be used alone.
+
+- **The bench** is a web page that shows the model's stages. The person picks a part, moves or turns a ghost of it, marks a spot, writes what is wrong and submits. Each submission keeps the before and after pictures, the exact transform and the words, and becomes a thread the assistant answers. Replies are drawn from the person's own camera. "Publish all" notifies the assistant once for everything new.
+- **The ledger** records which step of a build pipeline moved or rebuilt a part the person cares about, including code that runs between two steps. A placement the person locked stays locked, or the ledger says which line moved it.
+- **The board** has one row per thing the person asked for, each with a measurement and a bar. A planted fault proves each row can go red, so a green board is not a green check over a hole.
+- **The Penpot bridge** pushes 2D outlines in millimetres into a self-hosted Penpot file and reads the person's edits back.
+
+## Install
+
+```bash
+pip install 3d-review
+pip install "3d-review[penpot]"    # adds shapely, for cutting outlines in the Penpot bridge
+```
+
+In Python it is imported as `review3d`. It uses [3d-base](https://github.com/drkostas/3d-base) for pictures.
+
+## The bench
+
+```bash
+3d-review stages body.stl arm.stl wheel.stl -o model     # writes model/stages.json and model/stages/parts.glb
+cp "$(python -c 'import review3d,os;print(os.path.dirname(review3d.__file__))')/bench/bench.example.toml" model/bench.toml
+3d-review bench --config model/bench.toml --port 8766
+```
+
+Then open `http://localhost:8766/twist.html`. `threads.html` lists every thread. From Python, `review3d.stages.write_stages` writes any number of stages (for example "parts", "assembled" and "printed") from `{stage: {part: trimesh.Trimesh}}`, and `review3d.bench.server.Bench` takes your own notifier, rebuild hook and freshness check. The default notifier appends a line to a file, so the assistant can watch that file.
+
+The bench never changes the model. A submission is a request, and applying it is a separate step.
+
+## The ledger
+
+```python
+from review3d import ledger
+import mybuild
+
+ledger.install(mybuild, watch={"arm", "wheel"}, pipeline="build")
+mybuild.build()
+print(ledger.missing(mybuild, "build"))   # steps the pipeline calls that the ledger does not wrap
+ledger.write("ledger.json")
+```
+
+The steps are read from the pipeline's own source, so a step added later is never invisible to it. Moves are measured exactly (the rigid transform between the vertices before and after), and a part whose vertex count changed is reported as rebuilt.
+
+## The board
+
+```python
+import types
+import trimesh
+from review3d.board import Board, Row, at_most, mirror_asymmetry
+
+design = types.SimpleNamespace(body=trimesh.load("part.stl"))   # any object your rows can read
+
+board = Board([Row("symmetric", "the two sides match", lambda d: mirror_asymmetry(d.body, normal=(1, 0, 0)), at_most(0.2), "mm")])
+
+@board.fault("symmetric")
+def bump(design):
+    lump = trimesh.creation.box(extents=(2, 2, 2))
+    lump.apply_translation([6, 0, 0])
+    design.body = trimesh.util.concatenate([design.body, lump])
+
+board.report(design)
+print(board.proof_table(board.prove(design)))
+```
+
+A row whose measurement fails or has no input reads unknown, never green. A row with no fault reads unproven. The measurements include mirror symmetry, sphericity, surface roughness, gap and penetration between parts, tipping, first-layer area, overhang share, length along an axis, axis angle, bow, out of round, tunnels, and the brightness of a rendered view.
+
+## The Penpot bridge
+
+```python
+from review3d.penpot import PenpotClient, PenpotSettings
+
+client = PenpotClient(PenpotSettings.load("penpot.toml"))   # or PENPOT_* environment variables
+result = client.push({"plate": [(0, 0), (60, 0), (60, 20), (0, 20)]})
+edited = client.pull(file_id=result.file_id)
+```
+
+One Penpot unit is one millimetre. Keep credentials in the settings file or the environment, never in code.
+
+## Claude Code skill
+
+```bash
+3d-review skill            # copies it to ~/.claude/skills/3d-review
+```
+
+The skill is the review loop as we ran it. It covers writing the person's requirements as rows before building, proving each row, answering threads with pictures, keeping locks through rebuilds, asking questions with pictures on the bench instead of in words, and the failures that taught each rule.
+
+## Limits
+
+- The bench is meant for one person and one assistant on a trusted network. It has no login, so keep it on `127.0.0.1` or behind a private network.
+- The board's measurements are general. The rows that matter for your design are yours to write.
+- The bench includes three.js r169 (MIT, licence in `bench/static/vendor`).
+- Reading through Penpot's exporter depends on the exporter service working. The default `pull` reads the stored geometry and does not need it.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test,penpot]'
+.venv/bin/pytest
+```
+
+The Penpot tests use a fake server. Set `PENPOT_URL` and a token to run the live round trip too.
+
+## License
+
+MIT

3d_review-0.1.0/src/3d_review.egg-info/SOURCES.txt

@@ -0,0 +1,35 @@
+LICENSE
+README.md
+pyproject.toml
+src/3d_review.egg-info/PKG-INFO
+src/3d_review.egg-info/SOURCES.txt
+src/3d_review.egg-info/dependency_links.txt
+src/3d_review.egg-info/entry_points.txt
+src/3d_review.egg-info/requires.txt
+src/3d_review.egg-info/top_level.txt
+src/review3d/__init__.py
+src/review3d/board.py
+src/review3d/cli.py
+src/review3d/ledger.py
+src/review3d/penpot.py
+src/review3d/stages.py
+src/review3d/bench/__init__.py
+src/review3d/bench/bench.example.toml
+src/review3d/bench/notify.py
+src/review3d/bench/server.py
+src/review3d/bench/settings.py
+src/review3d/bench/thread.py
+src/review3d/bench/static/threads.html
+src/review3d/bench/static/twist.html
+src/review3d/bench/static/vendor/LICENSE-three.js.txt
+src/review3d/bench/static/vendor/three.module.js
+src/review3d/bench/static/vendor/jsm/controls/OrbitControls.js
+src/review3d/bench/static/vendor/jsm/controls/TransformControls.js
+src/review3d/bench/static/vendor/jsm/loaders/GLTFLoader.js
+src/review3d/bench/static/vendor/jsm/utils/BufferGeometryUtils.js
+src/review3d/skill/SKILL.md
+tests/test_bench.py
+tests/test_board.py
+tests/test_cli.py
+tests/test_ledger.py
+tests/test_penpot.py

3d_review-0.1.0/src/3d_review.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

3d_review-0.1.0/src/3d_review.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+3d-review = review3d.cli:main

3d_review-0.1.0/src/3d_review.egg-info/requires.txt

@@ -0,0 +1,13 @@
+3d-base>=0.2.0
+numpy>=1.24
+trimesh>=4.0
+scipy>=1.10
+
+[:python_version < "3.11"]
+tomli>=2
+
+[penpot]
+shapely>=2.0
+
+[test]
+pytest>=8

3d_review-0.1.0/src/3d_review.egg-info/top_level.txt

@@ -0,0 +1 @@
+review3d

3d_review-0.1.0/src/review3d/__init__.py

@@ -0,0 +1,2 @@
+"""Review a 3D design with an assistant."""
+__version__ = "0.1.0"

3d_review-0.1.0/src/review3d/bench/__init__.py

@@ -0,0 +1,10 @@
+"""The review bench, a web page for reviewing a 3D model.
+
+A reviewer opens the page, picks a stage of the model, circles a spot or moves a ghost copy of a
+part, writes what is wrong, and submits. Each submission is stored as a comment thread that the
+assistant answers. Replies can carry a picture rendered from the reviewer's own camera.
+
+`server.Bench` holds the plug-in points. They are the folders that hold the stage files, the
+folder that holds the threads, the notifier used when the reviewer presses "Publish all", and the
+optional rebuild and freshness hooks.
+"""

3d_review-0.1.0/src/review3d/bench/bench.example.toml

@@ -0,0 +1,6 @@
+# Copy this file into your project as bench.toml.
+port = 8766
+host = "127.0.0.1"
+model_dirs = ["."]
+subs_dir = "submissions"
+stages_dir = "stages"

3d_review-0.1.0/src/review3d/bench/notify.py

@@ -0,0 +1,22 @@
+"""Notifiers, which tell the assistant that the reviewer pressed "Publish all".
+
+A notifier is any object with a method `notify(text)` that returns `(ok, detail)`. The default
+appends a line to a log file, which works on every machine and needs nothing installed. A project
+with a better channel (a chat it can write into, a message queue) passes its own notifier.
+"""
+import datetime as _dt
+import pathlib
+
+
+class FileNotifier:
+    """Append each notification to a log file, one line per notification, with a timestamp."""
+
+    def __init__(self, path):
+        self.path = pathlib.Path(path)
+
+    def notify(self, text):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        stamp = _dt.datetime.now().astimezone().isoformat(timespec="seconds")
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(f"{stamp}  {text}\n")
+        return True, f"written to {self.path}"