plexdo 1.1.26__tar.gz → 1.1.29__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 (124) hide show
  1. plexdo-1.1.29/.github/workflows/wiki.yml +129 -0
  2. {plexdo-1.1.26 → plexdo-1.1.29}/AI.prompt.md +256 -17
  3. {plexdo-1.1.26 → plexdo-1.1.29}/CHANGELOG.md +94 -0
  4. {plexdo-1.1.26 → plexdo-1.1.29}/CONTRIBUTING.md +20 -0
  5. {plexdo-1.1.26 → plexdo-1.1.29}/MANIFEST.in +2 -1
  6. {plexdo-1.1.26 → plexdo-1.1.29}/Makefile +11 -3
  7. {plexdo-1.1.26/src/plexdo.egg-info → plexdo-1.1.29}/PKG-INFO +121 -3
  8. {plexdo-1.1.26 → plexdo-1.1.29}/README.md +120 -2
  9. {plexdo-1.1.26/src/plexdo/data → plexdo-1.1.29/completions}/_plexdo +19 -1
  10. {plexdo-1.1.26 → plexdo-1.1.29}/completions/plexdo.bash +32 -5
  11. {plexdo-1.1.26/src/plexdo/data → plexdo-1.1.29/completions}/plexdo.fish +14 -4
  12. {plexdo-1.1.26 → plexdo-1.1.29}/completions/plexdo.ps1 +7 -1
  13. plexdo-1.1.29/man/plexdo-append-playlist.1.scd +115 -0
  14. plexdo-1.1.29/man/plexdo-build-chronological.1.scd +174 -0
  15. plexdo-1.1.29/man/plexdo-build-concatenated.1.scd +178 -0
  16. plexdo-1.1.29/man/plexdo-build-interleaved.1.scd +169 -0
  17. plexdo-1.1.29/man/plexdo-build-randomize.1.scd +161 -0
  18. plexdo-1.1.29/man/plexdo-clean-playlist.1.scd +133 -0
  19. plexdo-1.1.29/man/plexdo-conventions.7.scd +252 -0
  20. plexdo-1.1.29/man/plexdo-copy-playlist-all-users.1.scd +148 -0
  21. plexdo-1.1.29/man/plexdo-copy-playlist-to-user.1.scd +142 -0
  22. plexdo-1.1.29/man/plexdo-copy-watched.1.scd +170 -0
  23. plexdo-1.1.29/man/plexdo-export-playlist.1.scd +116 -0
  24. plexdo-1.1.29/man/plexdo-export-titles.1.scd +171 -0
  25. plexdo-1.1.29/man/plexdo-find-missing.1.scd +175 -0
  26. plexdo-1.1.29/man/plexdo-list-libraries.1.scd +105 -0
  27. plexdo-1.1.29/man/plexdo-list-playlist.1.scd +124 -0
  28. plexdo-1.1.29/man/plexdo-list-playlists.1.scd +103 -0
  29. plexdo-1.1.29/man/plexdo-list-show.1.scd +123 -0
  30. plexdo-1.1.29/man/plexdo-list-titles.1.scd +170 -0
  31. plexdo-1.1.29/man/plexdo-list-users.1.scd +109 -0
  32. plexdo-1.1.29/man/plexdo-login.1.scd +146 -0
  33. plexdo-1.1.29/man/plexdo-logout.1.scd +144 -0
  34. plexdo-1.1.29/man/plexdo-player-remote-play.1.scd +352 -0
  35. plexdo-1.1.29/man/plexdo-read.1.scd +122 -0
  36. plexdo-1.1.29/man/plexdo-remove-playlist.1.scd +95 -0
  37. plexdo-1.1.29/man/plexdo-rescan.1.scd +133 -0
  38. plexdo-1.1.29/man/plexdo-search.1.scd +128 -0
  39. plexdo-1.1.29/man/plexdo-show-metadata.1.scd +140 -0
  40. plexdo-1.1.29/man/plexdo-status.1.scd +152 -0
  41. plexdo-1.1.29/man/plexdo-wait.1.scd +302 -0
  42. plexdo-1.1.29/man/plexdo-write-config-example.1.scd +136 -0
  43. {plexdo-1.1.26/src/plexdo/data → plexdo-1.1.29/man}/plexdo.1 +70 -6
  44. {plexdo-1.1.26 → plexdo-1.1.29}/pyproject.toml +1 -1
  45. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/__init__.py +1 -1
  46. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/accounts.py +81 -13
  47. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/airdates.py +38 -6
  48. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/__init__.py +4 -3
  49. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/auth.py +142 -9
  50. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/build.py +3 -3
  51. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/copy.py +6 -2
  52. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/missing.py +8 -3
  53. plexdo-1.1.29/src/plexdo/commands/remote.py +569 -0
  54. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/constants.py +8 -1
  55. {plexdo-1.1.26/completions → plexdo-1.1.29/src/plexdo/data}/_plexdo +19 -1
  56. {plexdo-1.1.26/man → plexdo-1.1.29/src/plexdo/data}/plexdo.1 +70 -6
  57. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/data/plexdo.bash +32 -5
  58. {plexdo-1.1.26/completions → plexdo-1.1.29/src/plexdo/data}/plexdo.fish +14 -4
  59. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/data/plexdo.ps1 +7 -1
  60. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/logs.py +3 -0
  61. plexdo-1.1.29/src/plexdo/playback.py +231 -0
  62. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/playlists.py +7 -4
  63. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/titles.py +2 -2
  64. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/tokens.py +19 -1
  65. {plexdo-1.1.26 → plexdo-1.1.29/src/plexdo.egg-info}/PKG-INFO +121 -3
  66. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo.egg-info/SOURCES.txt +40 -1
  67. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_cli_and_config.py +3 -2
  68. plexdo-1.1.29/tests/test_fixes.py +208 -0
  69. plexdo-1.1.29/tests/test_logout.py +134 -0
  70. plexdo-1.1.29/tests/test_logs.py +34 -0
  71. plexdo-1.1.29/tests/test_playback.py +180 -0
  72. plexdo-1.1.29/tests/test_remote_play.py +655 -0
  73. plexdo-1.1.29/tools/wiki-pages.sh +81 -0
  74. {plexdo-1.1.26 → plexdo-1.1.29}/.github/workflows/ci.yml +0 -0
  75. {plexdo-1.1.26 → plexdo-1.1.29}/.github/workflows/publish.yml +0 -0
  76. {plexdo-1.1.26 → plexdo-1.1.29}/LICENSE +0 -0
  77. {plexdo-1.1.26 → plexdo-1.1.29}/SECURITY.md +0 -0
  78. {plexdo-1.1.26 → plexdo-1.1.29}/requirements.txt +0 -0
  79. {plexdo-1.1.26 → plexdo-1.1.29}/setup.cfg +0 -0
  80. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/__main__.py +0 -0
  81. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/cache.py +0 -0
  82. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/cli.py +0 -0
  83. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/libraries.py +0 -0
  84. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/metadata.py +0 -0
  85. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/playlists.py +0 -0
  86. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/rescan.py +0 -0
  87. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/search.py +0 -0
  88. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/status.py +0 -0
  89. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/stream.py +0 -0
  90. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/users.py +0 -0
  91. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/wait.py +0 -0
  92. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/commands/watched.py +0 -0
  93. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/config.py +0 -0
  94. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/console.py +0 -0
  95. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/convert.py +0 -0
  96. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/fanout.py +0 -0
  97. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/formats.py +0 -0
  98. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/gallery.py +0 -0
  99. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/identify.py +0 -0
  100. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/m3u.py +0 -0
  101. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/paths.py +0 -0
  102. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/photos.py +0 -0
  103. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/py.typed +0 -0
  104. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/records.py +0 -0
  105. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/sections.py +0 -0
  106. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/security.py +0 -0
  107. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/sorting.py +0 -0
  108. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo/throttle.py +0 -0
  109. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo.egg-info/dependency_links.txt +0 -0
  110. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo.egg-info/entry_points.txt +0 -0
  111. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo.egg-info/requires.txt +0 -0
  112. {plexdo-1.1.26 → plexdo-1.1.29}/src/plexdo.egg-info/top_level.txt +0 -0
  113. {plexdo-1.1.26 → plexdo-1.1.29}/tests/conftest.py +0 -0
  114. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_airdates_misc.py +0 -0
  115. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_console.py +0 -0
  116. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_fanout.py +0 -0
  117. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_formats.py +0 -0
  118. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_identify.py +0 -0
  119. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_paths_tokens.py +0 -0
  120. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_playlists.py +0 -0
  121. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_records_missing.py +0 -0
  122. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_throttle.py +0 -0
  123. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_wait.py +0 -0
  124. {plexdo-1.1.26 → plexdo-1.1.29}/tests/test_watched.py +0 -0
@@ -0,0 +1,129 @@
1
+ name: Wiki
2
+
3
+ # Publishes one GitHub wiki page per man/*.scd page: tools/wiki-pages.sh
4
+ # converts each one scdoc -> roff -> pandoc -> GitHub-flavoured Markdown, and
5
+ # man/plexdo-wait.1.scd becomes the wiki page plexdo-wait.
6
+ #
7
+ # One-time setup: enable the wiki under Settings > Features > Wikis, then
8
+ # create its first page by hand. GitHub only creates the wiki's repository
9
+ # at that point, and until it exists there is nothing to push to.
10
+ #
11
+ # Generated pages begin with a hidden "Generated from" comment. A page that
12
+ # carries it and whose source has been removed is deleted; a page written by
13
+ # hand never carries it and is never deleted. Editing a generated page on the
14
+ # wiki is pointless: the next run overwrites it from its source.
15
+
16
+ on:
17
+ push:
18
+ branches: [main]
19
+ paths:
20
+ - "man/*.scd"
21
+ - "tools/wiki-pages.sh"
22
+ - ".github/workflows/wiki.yml"
23
+ # Pull requests convert the pages without publishing them, so a page that
24
+ # does not compile, or refers to one that does not exist, fails review.
25
+ pull_request:
26
+ paths:
27
+ - "man/*.scd"
28
+ - "tools/wiki-pages.sh"
29
+ - ".github/workflows/wiki.yml"
30
+ # A full resync, for after the wiki has been edited by hand.
31
+ workflow_dispatch:
32
+
33
+ # Converting the pages needs nothing more than reading the repository; only
34
+ # the publish job raises its own permission, to push to the wiki.
35
+ permissions:
36
+ contents: read
37
+
38
+ # Two runs pushing to the wiki at once would race, the later failing on a
39
+ # stale checkout; queue them instead of cancelling, so no update is lost.
40
+ concurrency:
41
+ group: wiki
42
+ cancel-in-progress: false
43
+
44
+ jobs:
45
+ build:
46
+ name: Build pages
47
+ runs-on: ubuntu-latest
48
+ steps:
49
+ - uses: actions/checkout@v7
50
+
51
+ - name: Install scdoc and pandoc
52
+ run: sudo apt-get update && sudo apt-get install -y scdoc pandoc
53
+
54
+ # Fails on a page scdoc rejects, and on a reference to a page that
55
+ # does not exist, rather than publishing a broken link.
56
+ - name: Convert
57
+ run: make wiki
58
+
59
+ - name: Upload pages
60
+ uses: actions/upload-artifact@v7
61
+ with:
62
+ name: wiki
63
+ path: build/wiki/
64
+ if-no-files-found: error
65
+
66
+ publish:
67
+ name: Publish to the wiki
68
+ needs: build
69
+ # Only what has reached main is published: a pull request, or a manual
70
+ # run from another branch, builds the pages and stops there.
71
+ if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
72
+ runs-on: ubuntu-latest
73
+ permissions:
74
+ contents: write # GITHUB_TOKEN pushes to the wiki under this
75
+ steps:
76
+ # Without this, a missing wiki surfaces as checkout's bare "repository
77
+ # not found", which does not say what to do about it.
78
+ - name: Wiki exists
79
+ env:
80
+ GH_TOKEN: ${{ github.token }}
81
+ run: |
82
+ wiki="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.wiki.git"
83
+ if ! git ls-remote "$wiki" > /dev/null 2>&1; then
84
+ echo "::error::The wiki has no repository yet. Enable it under" \
85
+ "Settings > Features > Wikis, create its first page by hand," \
86
+ "and run this workflow again."
87
+ exit 1
88
+ fi
89
+
90
+ - name: Check out the wiki
91
+ uses: actions/checkout@v7
92
+ with:
93
+ repository: ${{ github.repository }}.wiki
94
+ path: wiki
95
+
96
+ - name: Download pages
97
+ uses: actions/download-artifact@v8
98
+ with:
99
+ name: wiki
100
+ path: pages/
101
+
102
+ - name: Sync pages
103
+ working-directory: wiki
104
+ run: |
105
+ # A generated page whose source is gone goes too. Only pages
106
+ # carrying the mark are candidates: hand-written ones never are.
107
+ for page in *.md; do
108
+ [ -e "$page" ] || continue
109
+ if head -n 1 "$page" | grep -q '^<!-- Generated from ' &&
110
+ [ ! -e "../pages/$page" ]; then
111
+ git rm --quiet "$page"
112
+ echo "removed $page"
113
+ fi
114
+ done
115
+
116
+ cp ../pages/*.md .
117
+ git add --all
118
+ if git diff --cached --quiet; then
119
+ echo "The wiki is already up to date."
120
+ exit 0
121
+ fi
122
+ git diff --cached --stat
123
+
124
+ git config user.name "github-actions[bot]"
125
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
126
+ git commit --quiet \
127
+ -m "Update manual pages from ${GITHUB_SHA::7}" \
128
+ -m "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/commit/${GITHUB_SHA}"
129
+ git push
@@ -84,8 +84,8 @@ characters where they reproduce program output or draw a `tree`-style listing.
84
84
  ```
85
85
  pyproject.toml Makefile README.md LICENSE MANIFEST.in requirements.txt
86
86
  CHANGELOG.md CONTRIBUTING.md SECURITY.md AI.prompt.md .gitignore
87
- .gitattributes .github/workflows/ci.yml
88
- man/plexdo.1
87
+ .gitattributes .github/workflows/{ci,publish,wiki}.yml tools/wiki-pages.sh
88
+ man/plexdo.1 man/plexdo-conventions.7.scd man/plexdo-COMMAND.1.scd
89
89
  completions/{plexdo.bash,_plexdo,plexdo.fish,plexdo.ps1}
90
90
  tests/conftest.py + test_*.py
91
91
  src/plexdo/
@@ -98,7 +98,8 @@ src/plexdo/
98
98
  config.py load_config, cached_config, connect_plex, read_token,
99
99
  token_store_path, config_optional, section_optional,
100
100
  check_file_permissions
101
- tokens.py load_store, save_store, lookup, store_token, admin_token
101
+ tokens.py load_store, save_store, lookup, store_token, admin_token,
102
+ forget_tokens
102
103
  cache.py cache_dir, write_cache
103
104
  convert.py parse_date, format_duration
104
105
  console.py output, output_format, clean_text, table_limit,
@@ -109,7 +110,9 @@ src/plexdo/
109
110
  cache_row, season_records
110
111
  identify.py resolve_identifier
111
112
  accounts.py server_for_user, account_type, resolve_user_arguments,
112
- user_roster, UserAccessError
113
+ user_roster, UserAccessError, connect_with_token,
114
+ configured_sections, configured_account,
115
+ configured_accounts
113
116
  sections.py resolve_section, resolve_sections,
114
117
  resolve_library_arguments
115
118
  titles.py display_title, find_item, fetch_item, fetch_show,
@@ -127,6 +130,8 @@ src/plexdo/
127
130
  paths.py mapper_for, library_roots, add_prefix_argument
128
131
  airdates.py resolve_episode_date and its helpers
129
132
  throttle.py paced, throttle_delay
133
+ playback.py fetch_address, parse_ip, url_host, url_of, play_fields,
134
+ add_play_arguments, Candidate, IPAddress
130
135
  security.py scrub_password_argument
131
136
  data/ the four completions and the man page, as package data
132
137
  commands/ one module per group (see COMMANDS)
@@ -141,7 +146,7 @@ Every module in `commands/` exposes exactly three names:
141
146
  - `COMMANDS` maps command name to handler.
142
147
  - `REQUIRES_PLEX` is the subset needing a server; `auth` has an empty
143
148
  frozenset because `login` and `write-config-example` run before a token
144
- exists.
149
+ exists, and `logout` must work once the server no longer accepts one.
145
150
 
146
151
  `commands/__init__.py` holds a `MODULES` tuple whose order sets the order of
147
152
  subcommands in `--help`, plus `register_all(sub, parents)` and
@@ -224,7 +229,11 @@ it has shared nothing with:
224
229
  token is then **saved** so the login happens once
225
230
 
226
231
  Each stage returns None rather than raising, so the next is tried and a stale
227
- stored token falls through to a fresh login. When all three fail, raise
232
+ stored token falls through to a fresh login. Stage 3's sign-in is
233
+ `_login_section`, shared with `configured_accounts()`, which yields each
234
+ `[<user_id>]` account signed in - by its stored token while plex.tv accepts it,
235
+ else by its password, saving the token - one at a time, so a caller that finds
236
+ its account early signs in no more. When all three fail, raise
228
237
  `UserAccessError` explaining that admin rights do not override per-user
229
238
  scoping and that a `[<user_id>]` section would fix it. It must be an ordinary
230
239
  `Exception`, **not** a `sys.exit`: `copy-playlist-all-users` catches per-user
@@ -390,7 +399,10 @@ content.
390
399
 
391
400
  Every argument naming an **existing** playlist accepts a title or a ratingKey
392
401
  through `resolve_playlist`; no command may call `plex.playlist(name)`
393
- directly.
402
+ directly. A numeric value that is no item at all is a clean `sys.exit`, not
403
+ plexapi's `NotFound` escaping as a traceback: look it up with
404
+ `titles.find_item`, which returns None, and `fetch_item` wraps that for every
405
+ other fatal lookup, `fetch_show` included. Nothing calls `fetchItem` bare.
394
406
 
395
407
  Every build command constructs the list fully in memory, validates it is
396
408
  non-empty, prints a numbered preview, and makes exactly one `createPlaylist`
@@ -425,7 +437,7 @@ touched.
425
437
  - `list-libraries` - columns `id`, `type`, `title`; writes the libraries cache.
426
438
  - `list-titles LIBRARY [--album A]` - registered with
427
439
  `aliases=["list-library"]`. argparse reports whichever spelling was typed,
428
- so `COMMANDS` needs an entry for both, giving 28 registry entries for 27
440
+ so `COMMANDS` needs an entry for both, giving 30 registry entries for 29
429
441
  commands; the smoke test floor must allow for it. Table columns are
430
442
  `ratingKey`, `title`, `releaseDate`, `rating`, `studio`; a machine-readable
431
443
  format carries every listed field and, for a show library, nests each show's
@@ -450,7 +462,9 @@ touched.
450
462
  present. A season that simply **stops early is not a gap**: an unaired
451
463
  episode cannot be told from a missing one. Season 0 is skipped by default
452
464
  because specials are numbered irregularly, but `-s 0` overrides that, since
453
- asking for season 0 can only mean the specials.
465
+ asking for season 0 can only mean the specials. With nothing missing a
466
+ table prints `No gaps found.`, but a machine-readable format prints an
467
+ empty list: prose on stdout breaks whatever parses it.
454
468
 
455
469
  ### Building and copying
456
470
 
@@ -460,7 +474,12 @@ touched.
460
474
  side, require at least 3 known dates (so at least 2 intervals), take the
461
475
  median interval, estimate from latest-previous `+median` and earliest-next
462
476
  `-median`, averaging when both exist, and prompt only when that is
463
- impossible.
477
+ impossible. A film with no date has no neighbours, so it is prompted for
478
+ directly. `prompt_for_date` takes **any** item: name an episode by show,
479
+ season, and episode, with `??` for a number Plex lacks rather than `00`,
480
+ which would read as a real episode 0, and anything else by title and year.
481
+ It once read episode-only attributes and crashed on every undated film.
482
+ Running out of input is a `sys.exit` naming the item, not an `EOFError`.
464
483
  - `build-randomize USER SOURCE DEST` - Fisher-Yates via `secrets.randbelow`.
465
484
  - `build-concatenated USER NAME PLAYLIST... [--unique]` - joins the sources
466
485
  end to end, keeping the order within each and the order they were named in.
@@ -478,7 +497,10 @@ touched.
478
497
  as it completes. Because the caller surfaces the skip reason, the message
479
498
  inside `copy_playlist_to` is `LOG.info`, not a warning that would duplicate
480
499
  every skip on stderr.
481
- - `copy-playlist-to-user USER PLAYLIST USER DEST`.
500
+ - `copy-playlist-to-user USER PLAYLIST USER DEST` - a table shows the item
501
+ list then the outcome line; a machine-readable format shows the outcome
502
+ record **alone**, as `copy-playlist-all-users` does, because two documents
503
+ on one stream parse as neither.
482
504
  - `append-playlist USER PLAYLIST RATINGKEY...`, `remove-playlist USER PLAYLIST`.
483
505
  - `clean-playlist USER PLAYLIST [--include-partial]` - removes the watched
484
506
  entries and leaves the rest in their existing order. Preview first, then one
@@ -655,6 +677,124 @@ string and returns nothing for an empty one, so the library appears empty.
655
677
  let `&&` run. Ctrl-C exits 130 for the same reason.
656
678
  - Time, sleep and jitter come in as one `Clock`, so the loop is tested
657
679
  without waiting.
680
+ - `player-remote-play HOST RATINGKEY [--port P] [--player-user USER]
681
+ [--server-url URL]` -
682
+ connects to the player itself with plexapi's `PlexClient` and calls
683
+ `playMedia`, not proxied through the server, so the server need not know
684
+ the player.
685
+ - **IP only on the wire.** Some players refuse a Host header carrying a
686
+ name, as a DNS rebinding defence, so resolve a name here with
687
+ `getaddrinfo` and build every URL from the address; bracket IPv6. Try
688
+ each address in the resolver's order until a player answers at
689
+ `/resources`. Something answering without a `machineIdentifier`, or
690
+ with a reply plexapi cannot parse, is not a player and the next
691
+ address or port is tried; none answering is a `sys.exit` naming each
692
+ URL, and suggesting `--port` when it was not given.
693
+ - **The player's port.** Plex apps differ: 32500 Android/Fire TV, 8324
694
+ Roku, 32433 Plex HTPC/Plex Media Player, 3005 Plex Home Theater,
695
+ Plexamp anywhere. `--port` has no default and, given, is used as is.
696
+ Without it, send a unicast GDM `M-SEARCH * HTTP/1.0` to UDP 32412 at
697
+ each IPv4 address (2 s); a `200 OK` reply from that address whose
698
+ `Content-Type` (if any) names a player gives the port to use. Silence,
699
+ an IPv6 address, or an unusable reply falls back to `_KNOWN_PORTS` in
700
+ the order above, each first checked with a 2 s TCP connect so dropped
701
+ guesses do not each cost the 10 s probe timeout. Tests stub GDM and
702
+ the connect check by default, and exercise both for real on loopback.
703
+ - **Probe without a token**: what answers may not be the player, and a
704
+ token is a credential. Only a 401 earns a retry with plexdo's token.
705
+ - **Whom to send as.** A player trusts the account signed in to it. Send
706
+ as plexdo's own account when it is the server's admin
707
+ (`plex.myPlexUsername`, an email, matching its email or username,
708
+ ignoring case) or when the player's machine identifier is among its
709
+ plex.tv `devices()`; otherwise as the first `configured_accounts()`
710
+ entry whose devices include the player; otherwise as plexdo's own
711
+ anyway, with a warning naming the `[<user id>]` fix. plex.tv being
712
+ unreachable for any of this is a warning and plexdo's own token, never
713
+ the end of the command.
714
+ - **The sending account also fetches the item.** `playMedia` builds the
715
+ play queue and mints the delegation token on `media._server`, and the
716
+ player switches its user to whoever that is, so an item fetched as
717
+ plexdo makes a Roku signed in as a managed user switch to plexdo's
718
+ user. `_server_as` tries `connect_with_token` with the account's own
719
+ token, then, since a server refuses a managed user's plex.tv token,
720
+ `connect_as_shared_user` with the matching `current.users()` entry
721
+ (the admin-minted server token every per-user command uses). Neither
722
+ working is a `sys.exit` for `--player-user` (strict) and a warning
723
+ saying the player will switch, then plexdo's server, for the
724
+ automatic choice.
725
+ - **`--player-user`** names the account instead - a plex.tv id, username,
726
+ or email, ignoring case - and overrides every rule above, the admin
727
+ shortcut included. plexdo's own account when it matches, or when the
728
+ value is `0` and plexdo is the admin, since `0` means the admin
729
+ everywhere else. Then a Plex Home member (`home` true in
730
+ `current.users()`, managed users included) matching by id, username,
731
+ or email, or by title when it has no username, as a managed user has
732
+ none: `switchHomeUser(user, pin=)` gives its plex.tv account without a
733
+ password, `pin` coming from its `[<user_id>]` section; the switched
734
+ token is not stored, as switching is cheap and needs no secret. A
735
+ refused switch falls through to the sections, and with none is a
736
+ `sys.exit` naming the PIN and the section. Otherwise a
737
+ `configured_sections()` entry whose id or
738
+ username is the value is taken at its word without a sign-in to check;
739
+ failing that, sign the rest in one at a time through
740
+ `configured_account` and compare id, username, and email, because a
741
+ section may file the account under the email when given the username.
742
+ Nothing to act as, or plex.tv unreachable, is a `sys.exit`: never send as
743
+ some other account than the one asked for. Deliberately not in
744
+ `USER_ID_ARGUMENTS`: the value is matched against accounts, not the
745
+ roster, whose titles are display names rather than usernames.
746
+ - **The fetch address** is `playback.fetch_address`, below.
747
+ - A 401 from the player is a `sys.exit` explaining the account rule. A
748
+ `ParseError` is success: plexapi parses only after checking the status,
749
+ and some players answer a command with a bare `OK`.
750
+ - `--dry-run` resolves, probes, chooses the account and the address, and
751
+ sends nothing; choosing may still sign in a configured account. Output
752
+ carries `player`, `machineIdentifier`, `product`, `host`,
753
+ `playerAddress` (the URL used), `account`, `ratingKey`, `title`,
754
+ `fetchFrom`, `status`.
755
+ - Every library item plexapi returns carries a `listType`, or a playlist a
756
+ `playlistType`, so `playMedia` accepts all of them; no type check is
757
+ needed, and one would be dead code.
758
+
759
+ #### The address a player fetches from
760
+
761
+ `playMedia` tells the player to fetch from the media's server URL, plexdo's
762
+ configured one, which suits plexdo's network and not necessarily the
763
+ player's: plexdo often runs on another routed segment, or another IPv6 site.
764
+ `playback.fetch_address` chooses instead, and the command passes protocol,
765
+ address, and port to `playMedia`, whose `**params` override its own:
766
+
767
+ - Candidates: the configured URL, listed first, and every connection plex.tv
768
+ lists for the server except relays, which are throttled below what video
769
+ needs. Drop any whose address is loopback, link-local, unspecified, or
770
+ multicast - for a plex.tv connection, test its bare `address`, not just
771
+ its URI's host, which is a plex.direct name that says nothing.
772
+ - Name a plex.tv candidate by its URI's host, normally a plex.direct name
773
+ over https, and rank it by its bare address: https to a bare IP fails the
774
+ certificate.
775
+ - Rank against the player's IP, an IPv6-mapped IPv4 address read as IPv4:
776
+ same family; then same scope by `ipaddress.is_global`, so RFC 1918, ULA,
777
+ and carrier-grade NAT are private alike; then the longest shared prefix. A
778
+ host name, family unknown, ranks between a family match and a mismatch.
779
+ Scope outranks prefix: bits shared across the private/global line mean
780
+ nothing. A tie keeps the first, the configured URL.
781
+ - Bracket an IPv6 literal sent as the address: the player joins address and
782
+ port into a URL.
783
+ - Do not probe the chosen address. A probe runs from plexdo's network, which
784
+ is the very network that may differ from the player's.
785
+ - `--server-url` bypasses all of it, loopback included, for a player on the
786
+ server's own machine or networks joined by NAT; it must be an http or
787
+ https URL with a host, port defaulting to 32400.
788
+ - With no candidate left, `sys.exit` asking for `--server-url` or a
789
+ reachable `[plex] url`. Show the address chosen in the output
790
+ (`fetchFrom`).
791
+ - Tests must use genuinely global addresses for anything about scope: the
792
+ documentation ranges, 2001:db8::/32 and 192.0.2.0/24 among them, are not
793
+ global to `ipaddress`, and would leave the rule unexercised.
794
+
795
+ The ratingKey argument, `--server-url`, and the record's closing fields come
796
+ from `playback.add_play_arguments` and `play_fields`, so a second playback
797
+ command would not repeat them and trip `duplicate-code`.
658
798
 
659
799
  ### Setup
660
800
 
@@ -668,18 +808,40 @@ string and returns nothing for an empty one, so the library appears empty.
668
808
  from `sys.argv`, with a warning that is blunt about what cannot be fixed:
669
809
  the value is already in shell history and was visible during interpreter
670
810
  startup. On Windows the rewrite has no equivalent.
671
- - `write-config-example` - writes `CONFIG_EXAMPLE`, mode 0600. Its `--help`
811
+ - `logout [-u USERNAME]` - signs each stored token out at plex.tv
812
+ (`MyPlexAccount(token=...).signout()`) and removes it from the store via
813
+ `tokens.forget_tokens`. `-u` names a store key, exactly then ignoring
814
+ case; one the store lacks is a `sys.exit` listing those it has, since
815
+ signing out nobody would read as success. A token plex.tv already refuses
816
+ (`Unauthorized` on loading the account) is `already signed out` and
817
+ removed; any other failure leaves the token valid, so it is **kept** for a
818
+ retry and the run exits 1 after removing the rest. Sign a token filed
819
+ under two names out once. A store left empty is deleted rather than kept
820
+ as `{}`: no secrets file outlives its last secret, and the next command's
821
+ "run `plexdo login`" is then the right advice. `--dry-run` contacts
822
+ nothing. Needs no server, so it works when the server is down.
823
+ - `write-config-example [-o]` - writes `CONFIG_EXAMPLE`, mode 0600. An
824
+ existing config is refused without `-o/--overwrite`, and that check comes
825
+ before `--dry-run`, so a rehearsal fails where the real run would; a
826
+ dry run then writes nothing and says where it would write. Its `--help`
672
827
  prints the exact template, which needs `RawDescriptionHelpFormatter` for the
673
828
  epilog's newlines; that same formatter stops argparse wrapping the
674
829
  description, so pre-wrap it with `textwrap.fill(..., width=78)`.
830
+ `CONFIG_EXAMPLE` is one implicitly concatenated string: a line written
831
+ without its opening quote becomes a Python comment and silently drops
832
+ out of the template, as the per-user heading once did.
675
833
 
676
834
  ## ERROR HANDLING
677
835
 
678
836
  `sys.exit` with a clear message for: missing config or token, unknown
679
837
  ratingKey, wrong media type, playlist or user or library not found,
680
838
  unsupported library type, album not found, a refused name collision, a smart
681
- playlist asked to give up an entry, an unknown sessionKey. An interrupted
682
- `wait` exits 130. No bare
839
+ playlist asked to give up an entry, an unknown sessionKey, an existing config
840
+ file without `--overwrite`, an air date with no input to answer for it, a
841
+ `logout -u` name not in the token store, a player host that does not resolve
842
+ or where no player answers. A
843
+ command line argparse cannot parse exits 2, its own convention. An
844
+ interrupted `wait` exits 130. No bare
683
845
  `except`; the broad ones are in `_cancel_all_scans`, the per-user copy loop,
684
846
  and per-section collection, each with a `# pylint: disable=broad-except`.
685
847
 
@@ -766,11 +928,21 @@ sleeps through that window, that it ends on a stop or on autoplay moving on,
766
928
  that a failed poll is retried; that `--paused` ends a play on its deadline and
767
929
  a resume restarts the count; and that `--all` waits for a play started during
768
930
  its confirming poll, takes that second look even when nothing played, and
769
- judges an unfetchable video by its session; path rewriting
931
+ judges an unfetchable video by its session; that `logout` keeps a token it
932
+ could not sign out and removes one plex.tv already refuses; that
933
+ `player-remote-play` sends only IPs, probes without a token, and picks its
934
+ account by the rules above; that the fetch address follows family, then
935
+ scope, then prefix; path rewriting
770
936
  picking the longest matching root; the token store reading a legacy bare-token
771
937
  file; that `loaded_fields` and `file_paths` never trigger a reload; and that
772
938
  global flags survive being given before the subcommand.
773
939
 
940
+ Each bug that shipped gets a regression test in `tests/test_fixes.py` that
941
+ **fails against the code before the fix**; check that it does, or it proves
942
+ nothing. Build real plexapi `Movie` and `Episode` objects from XML for these
943
+ where the bug was about their attributes - they construct offline - rather
944
+ than stand-ins that would have hidden it.
945
+
774
946
  Two behaviours easy to get backwards: two fully played states need no sync, so
775
947
  a "latest wins" test must use states that actually differ; and
776
948
  `format_duration(None)` is empty while `format_duration(0)` is `"0:00"`,
@@ -827,16 +999,83 @@ The release job must confirm the tag matches the packaged version. PyPI
827
999
  uploads are immutable, so publishing `v1.2.3` from a tree carrying some other
828
1000
  version cannot be undone. Strip a leading `v` before comparing.
829
1001
 
1002
+ ## COMMAND PAGES
1003
+
1004
+ Beside the roff overview, every command has a detailed page in scdoc source
1005
+ format: `man/plexdo-COMMAND.1.scd`, one per command, with `list-library`
1006
+ documented in the `list-titles` page as the alias it is, and
1007
+ `man/plexdo-conventions.7.scd` for what every command shares - the global
1008
+ options, how users, libraries, playlists, items, and sessions are named,
1009
+ output formats, path rewriting, pacing, exit status, files, and
1010
+ environment. Nothing installs them; `MANIFEST.in` ships them in the sdist,
1011
+ and they sit under `man/`, so `check-assets` holds them to plain ASCII.
1012
+
1013
+ They are also the project wiki, one page each. `tools/wiki-pages.sh`
1014
+ converts them scdoc -> roff -> `pandoc --from man --to gfm`, and `make wiki`
1015
+ runs it into `build/wiki/`. mandoc cannot do this step: its Markdown output
1016
+ takes mdoc(7) only, and scdoc writes man(7). The script:
1017
+ - names the page for the file less its section, so `plexdo-wait.1.scd` is
1018
+ the page `plexdo-wait`, and fails if two sources would share a name;
1019
+ - writes each stage to a file of its own rather than a pipe, since a plain
1020
+ POSIX pipe hides a failure upstream and yields a truncated page;
1021
+ - rewrites `**plexdo-X**(N)` into a link to page `plexdo-X`, and fails when
1022
+ a link names a page that was not generated: a dangling reference is a
1023
+ build error, not a broken link on the wiki;
1024
+ - opens each page with a hidden `<!-- Generated from ... -->` comment.
1025
+
1026
+ `.github/workflows/wiki.yml` builds the pages in a `contents: read` job, on
1027
+ every push and pull request touching them, and uploads them as an artifact.
1028
+ A second job, only for `main` and never for a pull request, raises
1029
+ `contents: write` - the permission under which `GITHUB_TOKEN` pushes to the
1030
+ wiki - checks out `REPO.wiki`, and syncs: it deletes a page only when its
1031
+ **first line** is the generated mark and its source is gone, so a page
1032
+ written on the wiki by hand is never deleted, then copies the rest in and
1033
+ commits only when something changed. Check that the wiki repository exists
1034
+ first with `git ls-remote`: GitHub creates it only once a first page has
1035
+ been made by hand, and checkout's bare "repository not found" does not say
1036
+ so. The workflow is in a `wiki` concurrency group, queued rather than
1037
+ cancelled, since two pushes to the wiki at once would race.
1038
+
1039
+ Each command page has, in order: NAME, SYNOPSIS, DESCRIPTION, ARGUMENTS,
1040
+ OPTIONS, GLOBAL OPTIONS, OPTION INTERACTIONS, OUTPUT, EXIT STATUS, EXAMPLES,
1041
+ and SEE ALSO. GLOBAL OPTIONS says what **each** global flag does for that
1042
+ particular command - "no effect" is an answer, and `--dry-run` writing a
1043
+ file anyway is worth saying. OPTION INTERACTIONS covers every conflict and
1044
+ dependency, whether argparse enforces it (`-u`/`-a`) or the handler does
1045
+ (`find-missing -A` with SHOW, `wait --now` without `-r`). Document what the
1046
+ code does, checked against it, not what a help string implies. Sample tables
1047
+ are real output from `print_table` with an ASCII console, never hand-drawn.
1048
+
1049
+ scdoc accepts several mistakes silently, so follow these rules:
1050
+ - **Write every flag in prose bold**, `*--flag*`. A line starting with a
1051
+ bare `-` is a scdoc error, and wrapping puts flags at line starts.
1052
+ - **No spaced ` - ` dash in prose.** Wrapped to a line start it silently
1053
+ becomes a bullet. The NAME line's `name - summary` is the one exception.
1054
+ - **Escape a literal `*` as `\*`.** An unclosed one silently eats text.
1055
+ - **Never start a line with `[`, `|`, or `:`.** scdoc reads it as a table
1056
+ row anywhere, not only after a blank line; escape it as `\[`, which
1057
+ wrapped SYNOPSIS lines need. A line starting `; ` silently vanishes as a
1058
+ comment, and one starting `. ` is a numbered list.
1059
+ - **A word-initial `_` underlines.** Mid-word underscores are literal.
1060
+ - Indent with TABs only, and double every backslash, inside literal blocks
1061
+ too: a Windows path `\\NAS\media` is written `\\\\NAS\\media`.
1062
+ - Wrap at 80 columns, counting a TAB as eight.
1063
+
1064
+ Validate by compiling every page with scdoc and checking the roff with
1065
+ `groff -man -ww -z`, and check that every option string of every command
1066
+ appears bold in its page.
1067
+
830
1068
  ## DELIVERABLES
831
1069
 
832
1070
  1. The `plexdo` package under `src/`, laid out as above
833
1071
  2. `pyproject.toml`, `Makefile`, `MANIFEST.in`, `requirements.txt`,
834
1072
  `.gitignore`, `.gitattributes`
835
1073
  3. `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, `LICENSE`
836
- 4. `man/plexdo.1`
1074
+ 4. `man/plexdo.1`, and the scdoc command pages beside it
837
1075
  5. `completions/` and its mirror in `src/plexdo/data/`
838
1076
  6. `tests/`
839
- 7. `.github/workflows/ci.yml`
1077
+ 7. `.github/workflows/ci.yml`, `publish.yml`, and `wiki.yml`, with
1078
+ `tools/wiki-pages.sh`
840
1079
  8. `AI.prompt.md` - this file, containing the full prompt that regenerates the
841
1080
  project including this requirement itself
842
1081
 
@@ -4,6 +4,97 @@ All notable changes to this project are documented here. The format follows
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
5
  adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [1.1.29] - 2026-10-22
8
+
9
+ ### Fixed
10
+ - The `player-remote-play` tests for Plex Home members no longer read the
11
+ `plexdo.ini` of whoever runs them, so they pass where there is none, as
12
+ on CI, and a PIN in a real config cannot change their outcome.
13
+
14
+ ## [1.1.28] - 2026-10-15
15
+
16
+ ### Added
17
+ - `logout [-u USERNAME]` signs the saved tokens out of plex.tv, invalidating
18
+ them, and removes them from the token file: every one by default, or the
19
+ one saved under `-u`, which is an error when the file has no such name. A
20
+ token plex.tv already refuses is removed too; one that could not be signed
21
+ out is kept for another try, and the exit status is 1. A token file left
22
+ empty is deleted.
23
+ - `player-remote-play HOST ratingKey` connects directly to a Plex player and
24
+ tells it to start playing an item. A host name is resolved by plexdo and
25
+ only the IP address is sent, since some players refuse a Host header
26
+ carrying a name as a defence against DNS rebinding; each address is tried
27
+ until a player answers. Each Plex app listens on its own port, so unless
28
+ `--port` gives it the player is asked over GDM (UDP 32412), and one that
29
+ does not answer is tried on the common apps' ports: 32500 (Android, Fire
30
+ TV), 8324 (Roku), 32433 (Plex HTPC), 3005 (Plex Home Theater), skipping
31
+ any that take no TCP connection within two seconds. The command is sent as
32
+ plexdo's own account when it is the server's admin or is signed in to the
33
+ player, otherwise as an account from a `[<user_id>]` section that is
34
+ signed in to the player, and otherwise as plexdo's own anyway, with a
35
+ warning. `--player-user` names the account instead, by plex.tv user id,
36
+ username, or email, or a managed user's name. It may be plexdo's own
37
+ account; a member of plexdo's Plex Home, managed users included, which
38
+ plexdo switches into without a password (a PIN-protected member takes
39
+ `pin` from its `[<user_id>]` section); or an account with a
40
+ `[<user_id>]` section. Anything else is an error.
41
+ - The player is told to fetch from whichever of the server's addresses is
42
+ most like its own - the configured URL and every direct address plex.tv
43
+ lists, ranked by family, then private or global scope, then the longest
44
+ shared prefix - so a player on another routed private network, or at
45
+ another IPv6 site behind router ACLs, gets an address it can reach.
46
+ Loopback, link-local, and relayed addresses never qualify, and plex.tv
47
+ addresses go by their `plex.direct` names so https certificates check out.
48
+ `--server-url` gives the address outright, and the output shows the one
49
+ chosen.
50
+
51
+ ### Fixed
52
+ - plexapi's informational messages, such as `Failed to parse "" to
53
+ datetime`, no longer reach stderr without `-v`: plexapi sets its own
54
+ logger to INFO, and the stderr handler now filters by the level asked
55
+ for.
56
+
57
+ ## [1.1.27] - 2026-10-05
58
+
59
+ ### Added
60
+ - A detailed manual page for every command, in scdoc source format under
61
+ `man/`: `plexdo-COMMAND.1.scd` for each command, covering every option,
62
+ which options conflict with or depend on one another, what each global
63
+ option does for that command, its output, its exit status, and worked
64
+ examples; and `plexdo-conventions.7.scd` for what the commands share. The
65
+ sources ship in the sdist.
66
+ - `write-config-example -o/--overwrite`. Without it, an existing config file
67
+ is now refused rather than replaced.
68
+ - The command pages are published to the project wiki, one page each, by
69
+ `.github/workflows/wiki.yml` whenever one changes on `main`, and built on
70
+ pull requests to catch a page that does not compile. `make wiki` builds
71
+ them locally, with scdoc and pandoc. Pages written on the wiki by hand are
72
+ left alone.
73
+
74
+ ### Fixed
75
+ - `build-chronological` crashed on any film without a release date: the date
76
+ prompt read episode-only attributes. It now asks for a film's date just as
77
+ it does an episode's, names an episode with no number as `S01E??` rather
78
+ than crashing on it too, and stops with an explanation instead of a
79
+ traceback when there is no terminal to answer on.
80
+ - The config template lost its "Per-user credentials" heading, so that
81
+ paragraph began mid-sentence: the line had no opening quote and was read as
82
+ a Python comment.
83
+ - `write-config-example` replaced an existing config file without asking, and
84
+ ignored `--dry-run`, writing the file anyway. It now refuses an existing
85
+ file without `--overwrite`, and a dry run writes nothing.
86
+ - `find-missing` printed `No gaps found.` as plain text in every format,
87
+ breaking `--json` and the other machine-readable formats; they now get an
88
+ empty list.
89
+ - `copy-playlist-to-user` wrote two documents to a machine-readable stream,
90
+ the item list and then the outcome; it now writes the outcome alone.
91
+ - An unknown numeric playlist, or an unknown ratingKey given to `list-show`,
92
+ `build-interleaved`, or `build-chronological`, ended in a Python traceback
93
+ rather than a message.
94
+ - The manual page gave exit status 1 for an argument that cannot be parsed,
95
+ which exits 2, and said `rescan -s` lists scan jobs when it lists all of the
96
+ server's background activity.
97
+
7
98
  ## [1.1.26] - 2026-10-05
8
99
 
9
100
  ### Added
@@ -334,6 +425,9 @@ multi-user token handling, watched-state synchronisation, a status report,
334
425
  photo galleries, YAML/CSV/CLIXML output, shell completions for bash, zsh, and
335
426
  fish, a manual page, and packaging for PyPI. See the commit history.
336
427
 
428
+ [1.1.29]: https://github.com/sidusnare/plexdo/releases/tag/v1.1.29
429
+ [1.1.28]: https://github.com/sidusnare/plexdo/releases/tag/v1.1.28
430
+ [1.1.27]: https://github.com/sidusnare/plexdo/releases/tag/v1.1.27
337
431
  [1.1.26]: https://github.com/sidusnare/plexdo/releases/tag/v1.1.26
338
432
  [1.1.25]: https://github.com/sidusnare/plexdo/releases/tag/v1.1.25
339
433
  [1.1.24]: https://github.com/sidusnare/plexdo/releases/tag/v1.1.24
@@ -78,5 +78,25 @@ action left on an old major starts warning and eventually stops running;
78
78
  `actions/checkout@v7`, `setup-python@v7`, `upload-artifact@v7`, and
79
79
  `download-artifact@v8` are all on node24.
80
80
 
81
+ ## The wiki
82
+
83
+ `.github/workflows/wiki.yml` publishes every `man/*.scd` page to the project
84
+ wiki whenever one changes on `main`: `man/plexdo-wait.1.scd` becomes the
85
+ wiki page `plexdo-wait`. Pull requests touching the pages build them without
86
+ publishing, so a page that does not compile, or links to one that does not
87
+ exist, fails there first. `make wiki` does the same build locally, given
88
+ scdoc and pandoc.
89
+
90
+ It needs setting up once: enable the wiki under Settings > Features > Wikis
91
+ and create its first page by hand, since GitHub only creates the wiki's
92
+ repository then. Until then the publish job fails saying exactly that.
93
+
94
+ Change the pages in `man/`, never on the wiki: a generated page is
95
+ overwritten on the next run. Each starts with a hidden `Generated from`
96
+ comment, and a page carrying it whose source has been removed is deleted.
97
+ Pages written on the wiki by hand never carry it, so they are left alone,
98
+ unless one is given the same name as a generated page. Run the workflow
99
+ from the Actions tab to resync everything after editing the wiki by hand.
100
+
81
101
  `AI.prompt.md` is the authoritative specification. When behaviour changes,
82
102
  update it in the same commit.