golded 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. golded-1.0.0/.gitignore +12 -0
  2. golded-1.0.0/LICENSE +21 -0
  3. golded-1.0.0/PKG-INFO +95 -0
  4. golded-1.0.0/README.md +70 -0
  5. golded-1.0.0/docs/PLAN.md +240 -0
  6. golded-1.0.0/docs/VERIFICATION.md +69 -0
  7. golded-1.0.0/docs/release.md +57 -0
  8. golded-1.0.0/docs/screens/area-list-dark.svg +141 -0
  9. golded-1.0.0/docs/screens/area-list-light.svg +142 -0
  10. golded-1.0.0/docs/screens/message-list-dark.svg +143 -0
  11. golded-1.0.0/docs/screens/message-list-light.svg +143 -0
  12. golded-1.0.0/docs/screens/message-view-dark.svg +140 -0
  13. golded-1.0.0/docs/screens/message-view-light.svg +141 -0
  14. golded-1.0.0/docs/screens/reply-dark.svg +142 -0
  15. golded-1.0.0/docs/screens/reply-light.svg +143 -0
  16. golded-1.0.0/docs/screens/splash-dark.svg +141 -0
  17. golded-1.0.0/docs/screens/splash-light.svg +139 -0
  18. golded-1.0.0/golded.toml.example +10 -0
  19. golded-1.0.0/pyproject.toml +82 -0
  20. golded-1.0.0/scripts/build_pages.py +745 -0
  21. golded-1.0.0/scripts/build_screenshots.py +113 -0
  22. golded-1.0.0/scripts/check_pages.py +121 -0
  23. golded-1.0.0/scripts/seed_demo.py +182 -0
  24. golded-1.0.0/scripts/verify_distribution.py +122 -0
  25. golded-1.0.0/src/golded/__init__.py +0 -0
  26. golded-1.0.0/src/golded/__main__.py +3 -0
  27. golded-1.0.0/src/golded/cli.py +65 -0
  28. golded-1.0.0/src/golded/data/__init__.py +0 -0
  29. golded-1.0.0/src/golded/data/area.py +8 -0
  30. golded-1.0.0/src/golded/data/sqlite_store.py +99 -0
  31. golded-1.0.0/src/golded/data/store.py +47 -0
  32. golded-1.0.0/src/golded/logic/__init__.py +0 -0
  33. golded-1.0.0/src/golded/logic/display_text.py +15 -0
  34. golded-1.0.0/src/golded/logic/quote.py +124 -0
  35. golded-1.0.0/src/golded/logic/session.py +304 -0
  36. golded-1.0.0/src/golded/logic/subject.py +22 -0
  37. golded-1.0.0/src/golded/logic/tear_origin.py +38 -0
  38. golded-1.0.0/src/golded/logic/thread_tree.py +101 -0
  39. golded-1.0.0/src/golded/logic/user_config.py +80 -0
  40. golded-1.0.0/src/golded/logic/version.py +9 -0
  41. golded-1.0.0/src/golded/py.typed +0 -0
  42. golded-1.0.0/src/golded/ui/__init__.py +0 -0
  43. golded-1.0.0/src/golded/ui/app.py +149 -0
  44. golded-1.0.0/src/golded/ui/area_list.py +265 -0
  45. golded-1.0.0/src/golded/ui/list_screen.py +73 -0
  46. golded-1.0.0/src/golded/ui/logo.py +14 -0
  47. golded-1.0.0/src/golded/ui/message_list.py +334 -0
  48. golded-1.0.0/src/golded/ui/message_view.py +330 -0
  49. golded-1.0.0/src/golded/ui/pagebar.py +90 -0
  50. golded-1.0.0/src/golded/ui/splash.py +143 -0
  51. golded-1.0.0/src/golded/ui/status.py +71 -0
  52. golded-1.0.0/src/golded/ui/theme.py +89 -0
  53. golded-1.0.0/src/golded/ui/title.py +29 -0
  54. golded-1.0.0/src/golded/ui/write_message.py +467 -0
  55. golded-1.0.0/tests/test_app_smoke.py +203 -0
  56. golded-1.0.0/tests/test_cli.py +71 -0
  57. golded-1.0.0/tests/test_data_store.py +54 -0
  58. golded-1.0.0/tests/test_display_text.py +19 -0
  59. golded-1.0.0/tests/test_message_markup.py +37 -0
  60. golded-1.0.0/tests/test_quote.py +83 -0
  61. golded-1.0.0/tests/test_session.py +356 -0
  62. golded-1.0.0/tests/test_subject.py +21 -0
  63. golded-1.0.0/tests/test_tear_origin.py +48 -0
  64. golded-1.0.0/tests/test_thread_tree.py +107 -0
  65. golded-1.0.0/tests/test_user_config.py +74 -0
  66. golded-1.0.0/tests/test_version.py +9 -0
@@ -0,0 +1,12 @@
1
+ __pycache__/
2
+ *.sqlite3
3
+ *.sqlite3-wal
4
+ *.sqlite3-shm
5
+ golded.toml
6
+ .venv/
7
+ dist/
8
+ .pytest_cache/
9
+ .mypy_cache/
10
+ .ruff_cache/
11
+ *.egg-info/
12
+ .agent-compose-backup-*/
golded-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 GoldED.dev contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
golded-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,95 @@
1
+ Metadata-Version: 2.5
2
+ Name: golded
3
+ Version: 1.0.0
4
+ Summary: GoldED message reader for FTN areas in SQLite, in the terminal
5
+ Project-URL: Repository, https://github.com/golded-dev/golded-python
6
+ Project-URL: Issues, https://github.com/golded-dev/golded-python/issues
7
+ Project-URL: Changelog, https://github.com/golded-dev/golded-python/blob/main/CHANGELOG.md
8
+ Author: GoldED.dev contributors
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Classifier: Environment :: Console :: Curses
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Classifier: Topic :: Communications :: BBS
18
+ Classifier: Typing :: Typed
19
+ Requires-Python: >=3.12
20
+ Requires-Dist: golded-ftn-sqlite<2,>=1.1.0
21
+ Requires-Dist: golded-ftn<2,>=1.5.1
22
+ Requires-Dist: rich>=14.2.0
23
+ Requires-Dist: textual<9,>=8.2.8
24
+ Description-Content-Type: text/markdown
25
+
26
+ # golded
27
+
28
+ A terminal message reader for FidoNet echomail and netmail stored in SQLite, modelled on GoldED. Built with Textual. Storage comes from [`golded-ftn`](https://pypi.org/project/golded-ftn/) and [`golded-ftn-sqlite`](https://pypi.org/project/golded-ftn-sqlite/).
29
+
30
+ The manual covers message bases, configuration, every key and each screen: <https://golded-dev.github.io/golded-python/>. Its source is in `site/`, built by `scripts/build_pages.py`.
31
+
32
+ ## Install
33
+
34
+ ```bash
35
+ uv tool install golded
36
+ golded --help
37
+ ```
38
+
39
+ Python 3.12 or newer, on Linux, macOS or Windows. `pipx install golded` works too.
40
+
41
+ ## Run
42
+
43
+ ```bash
44
+ golded --database messages.sqlite3
45
+ ```
46
+
47
+ `golded` opens one golded-ftn-sqlite base. Without options it looks for `messages.sqlite3` and `golded.toml` in the current directory. The manual shows how to create a base with `ftnt` from [`golded-ftn-tools`](https://pypi.org/project/golded-ftn-tools/).
48
+
49
+ `↑` `↓` and `Enter` pick an area and a message, `←` `→` step through messages, `r` replies, `F2` saves, `Esc` goes back and quits from the area list.
50
+
51
+ ## Config
52
+
53
+ `golded.toml` sets who you are when you write:
54
+
55
+ ```toml
56
+ from_name = "Odinn"
57
+ from_address = "2:236/777"
58
+ database = "messages.sqlite3"
59
+ origin = "Where we're going, we don't need roads."
60
+ theme = "dark"
61
+ threaded_list = false
62
+ splash_seconds = 10
63
+ ```
64
+
65
+ `--config`, `--database` and `--theme` override the file. A value golded cannot use stops it at startup with one line and exit status 1. The manual describes each field.
66
+
67
+ ## Development
68
+
69
+ Requires [uv](https://docs.astral.sh/uv/).
70
+
71
+ ```bash
72
+ uv sync
73
+ uv run python scripts/seed_demo.py
74
+ cp golded.toml.example golded.toml
75
+ uv run golded
76
+ ```
77
+
78
+ `scripts/seed_demo.py` writes a demo `messages.sqlite3`. **It deletes that file first if it exists, along with its `-wal` and `-shm` files.**
79
+
80
+ ```
81
+ src/golded/cli.py entry point (`golded`, `python -m golded`)
82
+ src/golded/ui/ draws the screen and handles keys (Textual)
83
+ src/golded/logic/ selected area, current message, navigation, draft
84
+ src/golded/data/ thin edge toward the FTN packages
85
+ scripts/ demo seeder, manual builder and release checks
86
+ tests/ unittest, run with pytest
87
+ ```
88
+
89
+ `cli.py` opens the store and hands it to `ui/app.py`, which wraps it in a `logic` `Session`; the screens work through that session.
90
+
91
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks and [docs/release.md](docs/release.md) for release preparation.
92
+
93
+ ## License
94
+
95
+ MIT. See [LICENSE](LICENSE).
golded-1.0.0/README.md ADDED
@@ -0,0 +1,70 @@
1
+ # golded
2
+
3
+ A terminal message reader for FidoNet echomail and netmail stored in SQLite, modelled on GoldED. Built with Textual. Storage comes from [`golded-ftn`](https://pypi.org/project/golded-ftn/) and [`golded-ftn-sqlite`](https://pypi.org/project/golded-ftn-sqlite/).
4
+
5
+ The manual covers message bases, configuration, every key and each screen: <https://golded-dev.github.io/golded-python/>. Its source is in `site/`, built by `scripts/build_pages.py`.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ uv tool install golded
11
+ golded --help
12
+ ```
13
+
14
+ Python 3.12 or newer, on Linux, macOS or Windows. `pipx install golded` works too.
15
+
16
+ ## Run
17
+
18
+ ```bash
19
+ golded --database messages.sqlite3
20
+ ```
21
+
22
+ `golded` opens one golded-ftn-sqlite base. Without options it looks for `messages.sqlite3` and `golded.toml` in the current directory. The manual shows how to create a base with `ftnt` from [`golded-ftn-tools`](https://pypi.org/project/golded-ftn-tools/).
23
+
24
+ `↑` `↓` and `Enter` pick an area and a message, `←` `→` step through messages, `r` replies, `F2` saves, `Esc` goes back and quits from the area list.
25
+
26
+ ## Config
27
+
28
+ `golded.toml` sets who you are when you write:
29
+
30
+ ```toml
31
+ from_name = "Odinn"
32
+ from_address = "2:236/777"
33
+ database = "messages.sqlite3"
34
+ origin = "Where we're going, we don't need roads."
35
+ theme = "dark"
36
+ threaded_list = false
37
+ splash_seconds = 10
38
+ ```
39
+
40
+ `--config`, `--database` and `--theme` override the file. A value golded cannot use stops it at startup with one line and exit status 1. The manual describes each field.
41
+
42
+ ## Development
43
+
44
+ Requires [uv](https://docs.astral.sh/uv/).
45
+
46
+ ```bash
47
+ uv sync
48
+ uv run python scripts/seed_demo.py
49
+ cp golded.toml.example golded.toml
50
+ uv run golded
51
+ ```
52
+
53
+ `scripts/seed_demo.py` writes a demo `messages.sqlite3`. **It deletes that file first if it exists, along with its `-wal` and `-shm` files.**
54
+
55
+ ```
56
+ src/golded/cli.py entry point (`golded`, `python -m golded`)
57
+ src/golded/ui/ draws the screen and handles keys (Textual)
58
+ src/golded/logic/ selected area, current message, navigation, draft
59
+ src/golded/data/ thin edge toward the FTN packages
60
+ scripts/ demo seeder, manual builder and release checks
61
+ tests/ unittest, run with pytest
62
+ ```
63
+
64
+ `cli.py` opens the store and hands it to `ui/app.py`, which wraps it in a `logic` `Session`; the screens work through that session.
65
+
66
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks and [docs/release.md](docs/release.md) for release preparation.
67
+
68
+ ## License
69
+
70
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,240 @@
1
+ # Release plan: golded 1.0.0 (repo golded-python)
2
+
3
+ Status: draft 2026-11-13. Nothing is committed or published yet.
4
+
5
+ Goal: turn the imported exam project into a release-ready open source package in
6
+ the golded-dev suite. No new features. "Release-ready" means the same bar as the
7
+ `golded-ftn-*-python` packages and `golded-ftn-tools`: installable wheel and sdist,
8
+ CI on Linux/macOS/Windows with Python 3.12–3.14 (Windows added 2026-11-15), strict checks, a reviewed release
9
+ checklist, and a static HTML manual in the shared GoldED design.
10
+
11
+ Template repos: `golded-ftn-tools` (application with an HTML manual, entry point,
12
+ release checklist) and `golded-ftn-sqlite-python` (pyproject, CI, verify script).
13
+
14
+ ## Starting point
15
+
16
+ - 41 files from the exam submission, flat layout: `app.py`, `ui/`, `logic/`,
17
+ `data/`, `seed.py`, `tests/` (unittest, 63 tests passing on Python 3.14).
18
+ - Runtime: Textual 8.2.8, golded-ftn 1.5.1, golded-ftn-sqlite 1.1.0. Faker only in
19
+ `seed.py`. All pinned with `==` in `requirements.txt`.
20
+ - Course-only seed content and personal names are already removed.
21
+ - README was the Danish course version; rewritten in English and its conda instructions
22
+ were replaced with uv on 2026-11-13; see "Anaconda" below.
23
+ - Code style is the course idiom: `keyword = value` spacing, no Ruff, no mypy.
24
+
25
+ ## Anaconda
26
+
27
+ The course required Anaconda; this project does not. The code never depended on
28
+ it: on 2026-11-13 the 63 tests passed on uv-managed CPython 3.14.10
29
+ (`--python-preference only-managed`, `/opt/anaconda3` off `PATH`) with only
30
+ `requirements.txt` installed. The README's conda instructions are replaced with uv.
31
+ Rules that keep it out:
32
+
33
+ - uv is the only documented toolchain (README, manual, CONTRIBUTING, AGENTS.md).
34
+ - CI runs on stock GitHub runners with `astral-sh/setup-uv`; no conda action.
35
+ - Phase 7 adds `grep -riE "conda|anaconda"` over the release tree; the only allowed
36
+ hits are this section and the CHANGELOG line noting the change.
37
+
38
+ ## Decisions before work starts
39
+
40
+ | # | Decision | Recommendation |
41
+ | --- | --- | --- |
42
+ | D1 | Names: distribution, import package, command | **Decided 2026-11-13:** `golded` / `golded` / `golded`, following the suite rule: the repo carries the `-python` suffix, the distribution does not (`golded-ftn-sqlite-python` → `golded-ftn-sqlite`). No clash with the C++ build, whose binaries are `gedlnx`/`gedmac`. `golded` is free on PyPI (checked 2026-11-13: 404). |
43
+ | D2 | What happens to `seed.py` | Move to `scripts/seed_demo.py`; Faker becomes a dev dependency. The manual shows how to create a real base with `ftnt`. Making seeding a CLI subcommand would be a new feature. |
44
+ | D3 | Adopt Ruff format | Yes. It rewrites the `keyword = value` course style once; do it in its own commit so the diff is reviewable as "format only". |
45
+ | D4 | mypy strictness | `strict = true`, as in the siblings. Textual typing may need a few targeted ignores; each one gets a reason. |
46
+ | D5 | Python floor | 3.12, as in the siblings. CI proves it. |
47
+ | D6 | LICENSE copyright holder | **Decided 2026-11-15:** `GoldED.dev contributors` in LICENSE and `authors`, as in the siblings. The splash `AUTHOR` stays Odinn (D7). |
48
+ | D7 | Splash identity: `RELEASE_NAME` "Stille og roligt™ edition", `COPYRIGHT_YEARS` "1990 - 2026", `AUTHOR`, countdown 10 s | **Decided 2026-11-15:** keep the identity. The countdown becomes `splash_seconds` in `golded.toml` (default 10, `0` skips the splash, anything but a whole number of 0 or more is a startup error). This is the one new option in 1.0.0, added at Odinn's request. |
49
+ | D8 | Version | 1.0.0. The config format, CLI options and key bindings become the public surface. |
50
+ | D9 | Manual hosting | `site/` in this repo, published to GitHub Pages by a pinned workflow; linked from the suite docs (`golded-ftn-python-docs`). |
51
+
52
+ ## Phase 1 — Baseline commit
53
+
54
+ 1. Commit the imported tree unchanged apart from the course cleanup already done,
55
+ with a message stating its origin (exam project, Itucation, 30 October 2026).
56
+ 2. Add `docs/PLAN.md` (this file) in the same or the next commit.
57
+
58
+ Done when: `git log` shows one baseline commit and tests still pass.
59
+
60
+ ## Phase 2 — Packaging
61
+
62
+ 1. Move code to `src/golded/` with subpackages `ui`, `logic`, `data`.
63
+ Imports become absolute package imports (`from golded.logic.session import …`).
64
+ 2. `app.py` becomes `golded/cli.py` with `main()`; add `__main__.py` so
65
+ `python -m golded` works. Entry point `golded = "golded.cli:main"`.
66
+ 3. `pyproject.toml` modelled on `golded-ftn-tools`: hatchling, `requires-python >=3.12`,
67
+ MIT, classifiers, project URLs, `py.typed`, sdist include list.
68
+ Dependencies as ranges: `textual>=8.2.8,<9`, `golded-ftn>=1.5.1,<2`,
69
+ `golded-ftn-sqlite>=1.1.0,<2`. Dev group: pytest, ruff, mypy, build, twine,
70
+ hatchling, Faker.
71
+ 4. Single version source: keep `logic/version.py` and add a test that it equals
72
+ the installed distribution version (no behaviour change).
73
+ 5. Delete `requirements.txt`; add `uv.lock`.
74
+ 6. Behaviour stays as it is: `golded.toml` and `messages.sqlite3` are still
75
+ resolved relative to the working directory. Only the error hint changes from
76
+ "python seed.py" to a pointer to the manual.
77
+
78
+ Done when: `uv sync`, `uv run golded --help` and `uv run pytest` work from a clean clone.
79
+
80
+ Status 2026-11-13: done, not committed. From a copy of the tracked and new files
81
+ without `.venv`: `uv sync --locked`, `seed.py`, `uv run golded --help` and 64 tests
82
+ pass (63 old + version test). The tests also pass on uv-managed Python 3.12.16, and
83
+ the wheel installs and runs `golded --help` there. A headless `run_test()` reaches
84
+ splash → area list → message list and quits cleanly. `rich` is a direct
85
+ dependency because `ui/area_list.py` and `logic/display_text.py` import it;
86
+ `authors` in `pyproject.toml` follows D6.
87
+
88
+ ## Phase 3 — Quality gates
89
+
90
+ 1. pytest runs the existing unittest suite unchanged (no rewrite to pytest style).
91
+ 2. Ruff lint (`E, F, I, UP, B`) and Ruff format; fix lint findings without
92
+ changing behaviour.
93
+ 3. mypy strict over `src`, `tests`, `scripts`.
94
+ 4. Headless smoke tests with Textual's `App.run_test()` against a temporary
95
+ seeded base: splash dismiss, open area, open message, next/previous,
96
+ theme toggle, write and save a message, discard confirm. These test existing
97
+ behaviour; they are the only way CI sees the UI at all.
98
+ 5. `scripts/verify_distribution.py` adapted from `golded-ftn-tools`: build, rebuild
99
+ wheel from sdist, inspect metadata and contents, install outside the checkout,
100
+ run `golded --help` and the headless smoke against the installed wheel.
101
+ 6. `.github/workflows/ci.yml`: Ubuntu + macOS + Windows (from 2026-11-15) × 3.12/3.13/3.14, `uv sync --no-sources`,
102
+ ruff, mypy, pytest, build, `twine check`, verify script. Actions pinned to full SHAs.
103
+
104
+ Done when: all gates pass locally on 3.12 and 3.14.
105
+
106
+ Status 2026-11-14: done. Ruff lint and format, strict mypy (42 files), 71 tests
107
+ and `scripts/verify_distribution.py` pass on 3.14 and, in a clean copy, on
108
+ uv-managed 3.12.16. CI is written but has not run on GitHub; `actionlint` is not
109
+ installed here, so the workflow is checked only by running its steps locally.
110
+
111
+ Found on the way, recorded for Phase 4:
112
+
113
+ - `q` does not quit from the area list (filter letter) or the write screen
114
+ (text). The README now says so; behaviour is unchanged.
115
+ - `ListScreen.on_scroll` never ran (Textual has no `Scroll` message) and was
116
+ deleted. Whether the pagebar follows mouse-wheel scrolling in lists needs a
117
+ manual check.
118
+ - Reply drafts passed the sender address as text where `OutgoingMessage`
119
+ expects `FtnAddress`; it now parses it. The stored value is unchanged.
120
+
121
+ ## Phase 4 — Code review pass (no features)
122
+
123
+ 1. Search for course leftovers: Danish strings in UI/comments/docstrings,
124
+ "kursist", "Itucation", "eksamen", teacher or classmate names.
125
+ 2. Review the error paths users will hit outside the course: missing database,
126
+ non-SQLite file, read-only file, schema version mismatch from golded-ftn-sqlite,
127
+ malformed `golded.toml`, invalid `from_address`. Each must give a one-line
128
+ message and exit code 1, not a traceback. Bugs found here are fixed; missing
129
+ features are listed under "Later".
130
+ 3. Manual run in macOS Terminal, iTerm2 and one Linux terminal: key bindings
131
+ (`Cmd+S` only reaches the app in some terminals; `F2`/`Ctrl+S` must always work),
132
+ resize, both themes, 80×25 minimum.
133
+ 4. Record results in `docs/VERIFICATION.md`.
134
+
135
+ Status 2026-11-14: steps 1, 2 and 4 done; step 3 (manual terminals) is open.
136
+ Fixed: unsupported database schema, malformed `golded.toml` and invalid
137
+ `from_address` gave tracebacks and now give one line and exit 1; the list
138
+ pagebar now follows mouse-wheel scrolling. A non-boolean `threaded_list` and an
139
+ unknown `theme` were accepted silently and are now config errors (decided
140
+ 2026-11-14).
141
+
142
+ ## Phase 5 — HTML manual
143
+
144
+ Same construction as the `golded-ftn-tools` manual: plain HTML and CSS, little
145
+ JavaScript, readable without it, local assets only.
146
+
147
+ 1. `DESIGN.md` pointing to the suite `DESIGN.md` in `golded-ftn-python-docs`;
148
+ `site/assets/` with the GoldED logo, `manual.css`, IBM Plex fonts and `OFL.txt`.
149
+ 2. Pages:
150
+ - `index.html` — what it is, install (`uv tool install golded`,
151
+ `pipx`), first run, link to the suite docs.
152
+ - `database.html` — what a message base is here; creating one with `ftnt`
153
+ (golded-ftn-sqlite format), the demo seeder for contributors.
154
+ - `config.html` — `golded.toml` fields and the three CLI options.
155
+ - `keys.html` — every key binding per screen.
156
+ - `screens.html` — screenshots of each screen in both themes, generated as SVG
157
+ by Textual from the deterministic demo base.
158
+ 3. `scripts/build_pages.py` renders the pages from source text in `docs/manual/`;
159
+ `scripts/check_pages.py` checks internal links, asset references, and that
160
+ `keys.html` lists exactly the bindings declared in the code. That last check
161
+ keeps the manual from drifting.
162
+ 4. `.github/workflows/pages.yml` publishes `site/` only, on push to `main`.
163
+ 5. Check a narrow mobile viewport, keyboard navigation and print view.
164
+ 6. In `golded-ftn-python-docs`: link to the manual from the home page. Separate
165
+ repo, separate commit.
166
+
167
+ Status 2026-11-14: steps 1–5 done; step 6 waits for Phase 8.7, since the link
168
+ would point at a page that is not live. Changes from the plan above: the page
169
+ text lives in `scripts/build_pages.py`, as in `golded-ftn-tools`, not in
170
+ `docs/manual/`; the screenshots are rendered by `scripts/build_screenshots.py`
171
+ into `docs/screens/` and inlined; `ftnt` 1.2.0 was tested against golded
172
+ (create, write, read back, reply saved by golded) before the database page
173
+ documents it. Browser check: Chrome desktop and 390 px mobile; Safari, print
174
+ and keyboard-only navigation are not checked yet.
175
+
176
+ ## Phase 6 — Repository documents
177
+
178
+ - `README.md` in English: what, install, run, config summary, link to the manual.
179
+ Short; the manual holds the details.
180
+ - `CHANGELOG.md` with `1.0.0 — <date>`.
181
+ - `CONTRIBUTING.md`, `SECURITY.md` following the siblings.
182
+ - `AGENTS.md` via `agent-compose` (`.agent-fragments/`, `agent-compose.toml`),
183
+ replacing the course rule (kursist idiom) with suite rules: uv, pytest, Ruff,
184
+ mypy, synthetic data only, no private archives in tests.
185
+ - `docs/release.md`: the release checklist below.
186
+ - `.gitignore` extended with `.venv/`, `dist/`, caches, `site/` build output
187
+ only if generated pages are not committed (decide with D9; the siblings commit them).
188
+
189
+ Status 2026-11-15: done. README is short and links the manual; the keys tables
190
+ moved to the manual, with the write-screen notes added to the keys page.
191
+ `site/` stays committed (D9), so `.gitignore` gains only `*.egg-info/` and the
192
+ agent-compose backups. `AGENTS.md` uses the siblings' setup (`project.md` plus the
193
+ Ash persona). While checking SECURITY.md, an area name such as `[/b]` crashed
194
+ golded with `MarkupError`; fixed in its own commit.
195
+
196
+ ## Phase 7 — Release verification
197
+
198
+ 1. All Phase 3 gates on the release commit.
199
+ 2. `uv build --no-sources`; rebuild wheel from sdist; `twine check`.
200
+ 3. Install the wheel in a clean venv outside the checkout; run `golded --help`
201
+ and the headless smoke.
202
+ 4. Recheck that `golded` is still free on PyPI immediately before release.
203
+ 5. Write `RELEASE-SHA256.txt` for wheel and sdist.
204
+
205
+ Status 2026-11-15, on `ad2fa6b`: steps 1–4 pass. Gates on Python 3.12.16 and
206
+ 3.14.10 in fresh envs; two builds give identical archives; `twine check` and
207
+ `verify_distribution.py` pass on both; the installed wheel runs in a real pty
208
+ (splash, area list, `Esc`, exit 0); `golded` is still 404 on PyPI. Step 5 waits:
209
+ the sdist includes `docs/`, so the manual terminal checks and any fix the first
210
+ Windows CI run needs would change it. `RELEASE-SHA256.txt` and the CHANGELOG
211
+ date are written on the frozen release commit, after CI is green on all nine jobs.
212
+
213
+ ## Phase 8 — Publication (each step needs an explicit go)
214
+
215
+ 1. Create `golded-dev/golded-python` on GitHub (public) and push `main`.
216
+ 2. Create the protected `pypi` environment; register the PyPI Trusted Publisher
217
+ (repo, `publish.yml`, environment `pypi`). Add `publish.yml` copied from
218
+ `golded-ftn-tools` (downloads release assets, checks SHA-256, publishes via OIDC).
219
+ 3. Tag `v1.0.0`, create the GitHub release with wheel, sdist and `RELEASE-SHA256.txt`.
220
+ 4. Run the publish workflow.
221
+ 5. Enable GitHub Pages, set the repository variable `PUBLISH_PAGES` to `true`
222
+ (the deploy job in `pages.yml` is off until then), flip `RELEASED` in
223
+ `scripts/build_pages.py` and rebuild; verify the public manual.
224
+ 6. Verify from the public index: `uvx golded --help` without wheelhouse.
225
+ 7. Link from the suite docs (Phase 5.6) once the manual is live.
226
+
227
+ Status 2026-11-15: step 1 done. `golded-dev/golded-python` is public; CI on
228
+ `5966064` is green on all nine jobs (Windows needed `python.exe` in
229
+ `verify_distribution.py`; fail-fast is off). Step 2 partly done: the `pypi`
230
+ environment requires Odinn's review and deploys only from `main`; `publish.yml`
231
+ is copied from `golded-ftn-tools`. The PyPI Trusted Publisher needs Odinn's
232
+ pypi.org login.
233
+
234
+ ## Out of scope (later)
235
+
236
+ Everything that changes what the program can do: other message-base formats
237
+ (JAM, Squish, MSG, Hudson), thread view stretch goals, editing/deleting
238
+ messages, search, user-level config locations (`~/.config`), packaging for
239
+ Homebrew. Windows was moved in on 2026-11-15: CI must pass there, because
240
+ nobody can test it by hand.
@@ -0,0 +1,69 @@
1
+ # Verification: golded 1.0.0
2
+
3
+ Results of the Phase 4 review pass (see `docs/PLAN.md`). Automated checks are
4
+ repeatable; the manual terminal checks are filled in by whoever runs them.
5
+
6
+ ## Course leftovers (2026-11-14)
7
+
8
+ `grep -rniE "kursist|itucation|eksamen|lasse|undervis|aflevering|conda"` over the
9
+ tree without `.venv`, `.git` and `uv.lock`: hits only in `docs/PLAN.md` (history and
10
+ the plan itself) and `classes=` in `ui/write_message.py` (substring of "lasse").
11
+
12
+ `grep -rnE "[æøåÆØÅ]"` over `src`, `seed.py`, `scripts`, `tests`, README and the
13
+ example config: hits only in test fixtures (`test_quote.py`, `test_display_text.py`,
14
+ `test_tear_origin.py`, `test_session.py`), where Danish text is the data under test
15
+ (mojibake repair, tearline handling). A word search for common Danish words in
16
+ `src`, `seed.py` and `scripts` finds only `RELEASE_NAME = "Stille og roligt™
17
+ edition"`, which is decision D7.
18
+
19
+ ## Startup error paths (2026-11-14)
20
+
21
+ Probed with the installed `golded` command, stdin from `/dev/null`, 6 s timeout.
22
+ Covered by `tests/test_cli.py` except where noted.
23
+
24
+ | Case | Before | Now |
25
+ | --- | --- | --- |
26
+ | Database path does not exist | `Database not found` + hint, exit 1 | unchanged |
27
+ | Database path is a directory | `Database not found` + hint, exit 1 | unchanged (not a test) |
28
+ | File is not SQLite | `Cannot open database …: file is not a database`, exit 1 | unchanged |
29
+ | SQLite file with another schema, or a newer/older golded-ftn-sqlite schema | traceback (`ValueError`), exit 1 | `Cannot open database …: not a supported golded-ftn-sqlite database`, exit 1 |
30
+ | Empty file | traceback, exit 1 | same one-line message as above (not a test) |
31
+ | Directory not writable (WAL needs `-shm`) | `Cannot open database …: attempt to write a readonly database`, exit 1 | unchanged (not a test) |
32
+ | Database file read-only (`chmod 444`) | app starts and reads; saving shows `attempt to write a readonly database` in the status bar and keeps the draft | unchanged (probed headless, not a test) |
33
+ | Malformed `golded.toml` | traceback (`TOMLDecodeError`), exit 1 | `Cannot read config …: Illegal character …`, exit 1 |
34
+ | Invalid `from_address` | traceback (`ValueError`), exit 1 | `Cannot read config …: Invalid FTN address [nonsense].`, exit 1 |
35
+ | `--config` names a directory | ignored, defaults used | unchanged |
36
+ | `threaded_list = "no"` | read with `bool()`, so any non-empty string meant `true` | `Cannot read config …: threaded_list must be true or false, not 'no'`, exit 1 |
37
+ | `theme = "neon"` | fell back to `dark` without a message | `Cannot read config …: theme must be one of dark, light, not 'neon'`, exit 1 |
38
+ | `splash_seconds = -1` (option added 2026-11-15) | did not exist; countdown fixed at 10 | `Cannot read config …: splash_seconds must be a whole number of 0 or more, not -1`, exit 1 |
39
+
40
+ The last two were accepted silently before; Odinn decided on 2026-11-14 that they
41
+ are errors. Covered by `tests/test_user_config.py`.
42
+
43
+ ## Pagebar and mouse wheel (2026-11-14)
44
+
45
+ The list screens updated the pagebar only when the cursor moved; the old
46
+ `on_scroll` handler never ran. Probe: 45 messages in a 15-row terminal, 15
47
+ `MouseScrollDown` events on the table moved `scroll_y` from 0 to 30 with the
48
+ cursor on row 0 and produced 0 pagebar updates. The list screens now watch the
49
+ table's `scroll_y`, as the message view already did for its body; the same probe
50
+ gives 15 updates and a pagebar equal to a fresh repaint.
51
+ `test_pagebar_follows_list_scroll` fails without the fix and passes with it.
52
+
53
+ ## Manual terminal checks
54
+
55
+ Odinn tested iTerm2, macOS Terminal and Ubuntu 24.04 in Multipass on
56
+ 2026-11-21 with synthetic databases.
57
+ He reported that the guided checks worked in all three terminals.
58
+
59
+ | Check | macOS Terminal | iTerm2 | Linux terminal |
60
+ | --- | --- | --- | --- |
61
+ | `F2` saves | Pass (reported) | Pass (reported) | Pass (reported) |
62
+ | `Ctrl+S` saves | Pass (reported) | Pass (reported) | Pass (reported) |
63
+ | `Cmd+S` saves (may not reach the app) | Pass (reported) | Pass (reported) | Not part of the Linux test |
64
+ | `F9` toggles theme; both themes readable | Pass (reported) | Pass (reported) | Pass (reported) |
65
+ | `Shift+→` / `Shift+←` in the message view | Pass (reported) | Pass (reported) | Pass (reported) |
66
+ | `Shift+Space` pages up | Pass (reported) | Pass (reported) | Pass (reported) |
67
+ | Mouse wheel moves the pagebar in the lists and the message view | Pass (reported) | Pass (reported) | Pass (reported) |
68
+ | Resize while in each screen | Pass (reported) | Pass (reported) | Pass (reported) |
69
+ | 80×25 shows every screen without clipping | Pass (reported) | Pass (reported) | Pass (reported) |
@@ -0,0 +1,57 @@
1
+ # Release preparation
2
+
3
+ Version 1.0.0 targets Linux, macOS and Windows, Python 3.12–3.14. CI must pass on
4
+ all three. Windows is tested headless only; nobody has run it in a Windows
5
+ terminal, so say so if a Windows bug report comes in.
6
+
7
+ ## Verification
8
+
9
+ 1. On the release commit, run every check in [CONTRIBUTING.md](../CONTRIBUTING.md)
10
+ with `uv sync --locked --no-sources` on Python 3.12 and 3.14. CI runs the same
11
+ checks on Linux, macOS and Windows with 3.12, 3.13 and 3.14.
12
+ 2. Build wheel and sdist with `uv build --no-sources`. Rebuild the wheel from the
13
+ sdist; `scripts/verify_distribution.py` does this and checks metadata, LICENSE,
14
+ `py.typed`, the contents and two clean installs outside the checkout. Do not
15
+ use editable installs or local source overrides.
16
+ 3. Install the wheel in a clean venv outside the checkout and run `golded --help`
17
+ and `golded --database DEMO` against a base from `scripts/seed_demo.py`.
18
+ 4. Run the manual terminal checks in `docs/VERIFICATION.md` and fill in the table.
19
+ 5. Recheck that the version is free at `https://pypi.org/pypi/golded/json`
20
+ immediately before release. A released version must never be overwritten.
21
+ 6. Set the date in `CHANGELOG.md`, then write `RELEASE-SHA256.txt` for the wheel and
22
+ sdist. Changes after verification require rebuilding and checking the changed
23
+ artifact.
24
+
25
+ ## CI and Trusted Publishing
26
+
27
+ CI resolves public dependencies with `uv sync --locked --no-sources`. Do not point
28
+ CI at a private workspace or an unpinned sibling branch.
29
+
30
+ A maintainer must create and protect the GitHub `pypi` environment with required
31
+ reviewers, register the exact repository owner/name, workflow `publish.yml` and
32
+ environment `pypi` as the PyPI Trusted Publisher, and enable the repository's
33
+ Actions workflows. The `pypi` environment exists, requires the maintainer's
34
+ review and allows deployments from `main` only. `publish.yml` runs by hand with a
35
+ release tag: it downloads the reviewed GitHub release assets, verifies
36
+ `RELEASE-SHA256.txt`, then requests an OIDC identity. No API token is required or
37
+ included. This document does not create that configuration or prove it exists.
38
+
39
+ ## Manual
40
+
41
+ `pages.yml` checks `site/` on every push and deploys it to GitHub Pages only from
42
+ `main` when the repository variable `PUBLISH_PAGES` is `true`. After the PyPI
43
+ upload:
44
+
45
+ 1. Enable GitHub Pages with GitHub Actions as the source and set `PUBLISH_PAGES`.
46
+ 2. Set `RELEASED = True` in `scripts/build_pages.py`, run it and
47
+ `scripts/check_pages.py`, and commit `site/`.
48
+ 3. Check the public manual in a browser, and link it from the suite docs
49
+ (`golded-ftn-python-docs`).
50
+
51
+ ## Publication
52
+
53
+ Each step is separately authorized: push the repository, configure the `pypi`
54
+ environment and Trusted Publisher, tag `v1.0.0` and create the GitHub release with
55
+ wheel, sdist and `RELEASE-SHA256.txt`, run the publish workflow, publish the
56
+ manual. After upload, run `uvx golded --help` from the public index without a
57
+ wheelhouse. Local success does not prove public installation.