tracker

16.7 KB

1. # tracker.worldapi.org
3. The new tracker: a Hybriel app that will track the TV shows (and later movies) the creator
4. follows and watches. **`CONCEPT.md` (the creator's) is the source of truth** — read it first;
5. nothing is built that it does not describe. Built step by step, one ticket per step
6. (tracker.worldapi.org#1, #2, …).
8. **Built so far — step 1 (ticket #1)**: the shell. The header carries the ident login (an
9. identity selector, like calendar/gitoria) and sign-out; the homepage itself stays empty. No
10. design carried over from the old app.
12. **Step 2 (ticket #2)**: the old tracker's MongoDB export is now in `storage/mpackdb/` (new
13. mpackdb ids, every reference re-pointed) — see "Data" and `STATUS.md`. Nothing is shown in the
14. UI yet; the homepage still renders empty. That is a later step, from the creator.
16. **Step 4 (ticket #4)**: the show page, `/shows/:slug` (`components/show.hl`) — poster, title,
17. genre pills, plot, cast (as described in "What it does (step 4)" below), every season with its
18. episodes, and the watch check (episode and season, season bulk-toggles its episodes).
20. **Step 5 (ticket #5)**: `/unwatched` (`components/unwatched.hl`) — every already-released,
21. unwatched episode of a show the signed-in user follows, newest release first (see "What it does
22. (step 5)" below).
24. **Step 6 (ticket #6)**: `/schedule` (`components/schedule.hl`) — every not-yet-released episode
25. of a show the signed-in user follows, soonest first, no check icons (see "What it does (step 6)"
26. below). The homepage itself is still empty.
28. Written in **Hybriel** on **hl:web**, same stack and conventions as `ident.worldapi.org`
29. (vendored plugins/binary copied from there, see "Vendored Hybriel").
31. ## Run (dev, Loreana)
33. ```bash
34. cd /media/STORAGE/projects/tracker.worldapi.org
35. TRACKER_PORT=8700 setsid nohup ./bin/hybriel project.hl > server.log 2>&1 < /dev/null & echo $! > server.pid
36. # stop: kill $(cat server.pid)
37. ```
39. * Config (env; the real environment outranks nothing here — there is no `.env` reader in
40. project.hl, unlike ident's SMTP settings — set these in the shell or `docker-compose.yml`):
42. | Variable | Default | |
43. |---|---|---|
44. | `TRACKER_PORT` | 45008 | |
45. | `TRACKER_URL` | `http://127.0.0.1:<port>` | this app's own origin — the ident login button's `return=` is built from it |
46. | `IDENT_URL` | `https://ident.worldapi.org` | |
47. | `TRACKER_KEY` / `TRACKER_SECRET` | `''` | this app's API key + secret, from ident's `/apps` (register once, origin = `TRACKER_URL`) — **not set yet on Byrodin**: the first deploy (architect) registers the app in the live ident and puts these in `.env` next to `docker-compose.yml`, exactly like ident's own `.env` holds its SMTP settings |
48. | `TRACKER_WATCH` | on | `0` = no dev watcher (the container) |
49. | `TRACKER_STORAGE` | `./storage/mpackdb` | the `usersTable` directory |
50. | `TRACKER_SESSIONS` | `./.sessions` (hl:web's own default) | this app's own session store |
51. | `HL_HOST` (or `HOST`) | 0.0.0.0 | interface to bind; `127.0.0.1` on Byrodin |
53. Without `TRACKER_KEY`/`TRACKER_SECRET`, `/` still renders (signed out, the selector and "Log
54. in with ident" show in the header); a login attempt answers `'login is not set up on this
55. server (TRACKER_KEY / TRACKER_SECRET missing)'` instead of exchanging a code — so the app is
56. never a dead 500 while waiting for that one-time setup.
58. ## What it does (step 1)
60. * **Login, copied unchanged from calendar.worldapi.org** (rejected once for a centered
61. sign-in and no header selector — architect, 2026-09-27): ident only, no own passwords
62. (ident's login button flow, ident.worldapi.org README "How apps use ident"), the identity
63. selector (`<ident-selector>`, ident's `/selector.js`) sits in the header
64. (`components/main.hl`, `userBox`), a plain "Log in with ident" link beside it when signed
65. out. Choosing an identity in the selector fires `ident-login` (one-time code); `login.js`
66. (an external-component bridge, allowed per the creator: "login.js is correct, as thats for
67. externals in general") hands the code to a hidden input, whose `change` calls the server
68. face `trackerLogin` (`users.hl` `exchangeCode`, `POST <ident>/api/exchange` — nothing else:
69. ident does not hand over a display name yet, ident#23 done / ident#11 on hold), which makes
70. or finds this app's own user record (`usersTable`, `storage/mpackdb/users.db`) and sets
71. `session.user = { id }`. `/login/callback` is the same exchange as a plain redirect (the
72. login button's return URL) for a client that has no socket yet. "Log out" in the header
73. calls `trackerLogOut`; ident's own login is untouched. This app's own session cookie is
74. `trackersid` (cookies ignore ports, an own name keeps it apart from ident's `identsid` on
75. the same dev host, hybriel#10/#17).
76. * **The empty homepage** (`/`, `components/home.hl`): no content at all, signed in or out —
77. the header alone carries the login state. Nothing else.
78. * **One mpackdb table**: `storage/mpackdb/users.db` (`identity` → this app's user id — no
79. display name, no other per-user data yet). Step 2 (tracker.worldapi.org#2, open) brings the
80. old tracker's data across.
82. ## What it does (step 4)
84. `/shows/:slug` (`components/show.hl`, slug = the migrated `urlSegment`), read-only data from
85. `shows.hl`, per-user watch state from `watches.hl` (both reused as-is by `/unwatched` and
86. `/schedule`, tickets #5/#6 — "reuse, don't copy"):
88. * **Header**: poster on the left (`/posters/<name>`, `project.hl` `posterRoute` — served from
89. `storage/mpackdb/posters/`; the real poster files were never in the Mongo backup, see
90. `DECISIONS.md` "tracker concept" — a placeholder SVG shows until a later TMDB step brings
91. real ones back), title, genre pills (blue, link to `/genre/<slug>`) and the plot summary to
92. its right, the cast below as comma-separated red links to `/person/<slug>`.
93. * **Seasons**, latest first, the latest expanded and every other one collapsed to start; each
94. row: a round check icon (a disc with a check, drawn in SVG/CSS, no icon font), the season
95. title/number, its episode count. Its episodes (number + title, and their own check icon)
96. show once expanded (click the row to toggle).
97. * **The watch check** (signed-in only — signed out, no check icons show at all): clicking an
98. episode's check toggles that one watch; clicking a season's check toggles the season's own
99. watch AND every one of its episodes at once (`watches.hl` `setSeasonWatched`). Every click is
100. a server round trip (`emit server showToggleEpisode` / `showToggleSeason` / `showRows` for
101. collapse/expand) that rebuilds the row list server-side and reassigns it whole — a season has
102. at most a few dozen episodes, cheap. A **Hybriel gap found here** (filed as hybriel#115,
103. reported after this ticket's first attempt): a plain per-instance member function that calls
104. an hl:mpackdb-backed import comes back `null` when called from inside an `on server` face,
105. even though the very same call works as a member's own top-level initializer — the fix is to
106. declare such helpers `static` (the same shape calendar.worldapi.org's `soonOf` already uses).
107. `components/show.hl`'s own helpers (`buildRows`, `genreRowsOf`, …) are `static` for exactly
108. this reason.
109. * **Data fix**: `tools/relink-episode-seasons.hl`, a one-off idempotent tool that links every
110. episode whose `season` was still null in the migrated data (36,194 of them, ticket #2) to its
111. season by matching `(show, seasonNumber)` — never touches an episode whose season is already
112. set, never runs `update()` on the live table (hybriel#113; it rebuilds a fresh episodes table
113. and swaps the files over, the same rule `tools/migrate.hl` follows). Not run against the live
114. data yet — the architect runs it (stop the container first, `storage/mpackdb` is not shared
115. across processes, hybriel#21).
117. ## What it does (step 5)
119. `/unwatched` (`components/unwatched.hl`): every episode of a show the signed-in user follows
120. (`follows.hl`, new) that is already released (`release` ≤ today) and not yet watched
121. (`watches.hl` `isWatched`), newest release first. Creator: "/unwatched lists all unwatched
122. episodes of shows followed in release date desc order"; "check icon is a disc with a check in
123. it" — the SAME icon/class (`watches.hl` `watchClassOf`, moved there from `components/show.hl` so
124. both pages share one definition instead of each declaring its own) and the same
125. `setWatched`/`isWatched` watch logic as the show page (step 4), not copied.
127. * Each row: check icon, the show's title (linking to `/shows/:slug`), "Ep `<number>` ·
128. `<title>`", the release date.
129. * A row only ever shows an unwatched episode, so a click always marks it watched (never toggles
130. back, unlike the show page's checks) — the row leaves the list. Signed out: no rows, a
131. "Sign in to see the shows you follow." message instead.
132. * `follows.hl` (new): read-only per-user follow data (`followedShowIds`), kept apart from
133. `shows.hl`/`watches.hl` the same way, for `/schedule` (ticket #6) to reuse.
135. ## What it does (step 6)
137. `/schedule` (`components/schedule.hl`): every episode of a show the signed-in user follows
138. (`follows.hl`) that is NOT yet released (`release` > today), soonest first. Creator: "/schedule
139. has a similar list without check icons for the upcoming episodes of shows followed" — same row
140. layout as `/unwatched` (show title linking to `/shows/:slug`, "Ep `<number>` · `<title>`", the
141. release date), minus the check icon and minus any click handling: the page is read-only, so it
142. needs no `on server` face at all. Signed out: no rows, the same "Sign in to see the shows you
143. follow." message as `/unwatched`.
145. ## Test
147. ```bash
148. node tests/browser.mjs # THE GATE: this app's own server + its OWN ident (a copy of
149. # ident's code without .env, codes to a mail sink — no live
150. # ident, no real mail; tests/identkit.mjs, same as calendar's
151. # gate) + a real headless Chrome: signed out (header shows the
152. # selector + "Log in with ident", the page itself is empty) ->
153. # sign in -> header shows "Log out", page still empty -> sign
154. # out -> signed out again -> a reload stays signed out. Also
155. # checks the header has no bottom border and filled buttons
156. # (incl. the ident selector's) have none, while inverted ones
157. # ("Log out") keep theirs.
158. # tracker.worldapi.org#4: a fixture show (tests/seed-show.hl,
159. # written into the gate's own storage before the server starts)
160. # proves /shows/:slug — header renders, no checks signed out;
161. # signed in, click an episode check (turns solid), click a
162. # season check (itself AND its episodes turn solid, proven
163. # after a reload — server-side, not just client state).
164. # tracker.worldapi.org#5: the same fixture (now followed by the
165. # test user) proves /unwatched — signed out, no rows; signed in,
166. # only the two already-released episodes show, newest first, the
167. # far-future one excluded; click a check, the row disappears
168. # (proven server-side after a reload).
169. # tracker.worldapi.org#6: the same fixture proves /schedule —
170. # signed out, no rows; signed in, only the far-future episode
171. # shows (the two already-released ones excluded), no check icons
172. # at all, unaffected by any watch toggle on the other pages.
173. # 38 checks. Own servers :8700 (this app) / :8701 (ident copy);
174. # own storage .scratch/gate-store; Chrome on 8702-8709.
175. ps -eo pid,args | grep [h]l-browser-tier # must print nothing afterwards
176. ```
178. ## Deploy (Byrodin)
180. Target: `/CONTAINERS/projects/tracker.worldapi.org` on Byrodin, container
181. `tracker.worldapi.org` (`docker-compose.yml`: debian:12-slim, host network,
182. `HL_HOST=127.0.0.1`, `TRACKER_PORT=45008`, `TRACKER_WATCH=0`, the folder mounted at
183. `/home/tracker`, `./bin/hybriel project.hl`), public https://tracker.worldapi.org/ via
184. nginx (TLS ends there; no baseUrl/tls in the app, like ident/notes).
185. * **First deploy: done by the architect** (folder, nginx vhost with WebSocket Upgrade
186. headers, cert, DNS, **and registering this app in the live ident** — `/apps` → name +
187. origin `https://tracker.worldapi.org` → the API key + secret go into `.env` next to
188. `docker-compose.yml`, `TRACKER_KEY=… TRACKER_SECRET=…`).
189. * **Later: `./deploy.sh`** on Loreana, in this folder: runs the gate (refuses on a failure;
190. `--skip-tests` skips it LOUDLY), rsyncs the code to
191. `[email protected]:/CONTAINERS/projects/tracker.worldapi.org` (never `storage/`,
192. `.sessions/`, `.env`, `.scratch/`, `server.*`, logs — the preview is checked for them; no
193. `--delete`), `docker compose up -d && docker compose restart` over `ssh -F /dev/null`,
194. then waits for https://tracker.worldapi.org/ to answer 200.
195. * `./deploy.sh --dry-run` = the gate + `rsync -n` + the commands it would run (no restart, no
196. URL check). `--target DIR|HOST:DIR` and `--url URL` point it elsewhere (tested against a
197. local directory, see STATUS.md).
199. ## Data
201. `storage/mpackdb/`: `users.db` (`identity` → this app's own user id, `users.hl`) plus, since
202. step 2, the old tracker's data — `genres.db` (27), `persons.db` (15157), `shows.db` (9453),
203. `seasons.db` (6430), `episodes.db` (231584), `follows.db` (128), `watches.db` (11692), all with
204. fresh mpackdb ids and every reference re-pointed (`tools/migrate.hl`); the one old user is this
205. app's user for ident short id `az5b2`. Counts and the referential-integrity proof:
206. `STATUS.md` "ticket #2". Nothing of this is shown in the UI yet.
208. ## Files
210. | File | |
211. |---|---|
212. | `CONCEPT.md` | the creator's concept — do not edit |
213. | `project.hl` | manifest: routes (`/login/callback`, `/login/failed`, `/login.js`, `/` component Home), the app's own session cookie |
214. | `users.hl` | the ident exchange + the `usersTable`, copied from calendar.worldapi.org's `users.hl` |
215. | `login.js` | bridge between `<ident-selector>`'s `ident-login` event and the shell, copied verbatim from calendar.worldapi.org |
216. | `components/home.hl` | `/`: the empty homepage — no content, signed in or out |
217. | `components/main.hl` | the shell (header: brand, `<ident-selector>`, log in / log out) |
218. | `components/loginfailed.hl` | `/login/failed`: why a login didn't work |
219. | `components/show.hl` | `/shows/:slug`: the show page (header, seasons, episodes, watch check) |
220. | `components/unwatched.hl` | `/unwatched`: unwatched, already-released episodes of followed shows, newest first |
221. | `components/schedule.hl` | `/schedule`: not-yet-released episodes of followed shows, soonest first, no checks |
222. | `shows.hl` | read-only data access (shows/seasons/episodes/genres/persons), reused by `/unwatched`/`/schedule` |
223. | `follows.hl` | read-only per-user follow data (`followedShowIds`), reused by `/unwatched`/`/schedule` |
224. | `watches.hl` | per-user watch state (episode/season checks, the shared check-icon class `watchClassOf`), reused by `/unwatched`/`/schedule` |
225. | `styles.hl` | all CSS (imports the tokens from `shared/tokens.hl`; accent green `#4ec9b0`) |
226. | `shared/tokens.hl` | the WorldAPI tokens, vendored verbatim from `ident.worldapi.org/shared/tokens.hl` |
227. | `tests/browser.mjs` | the gate (above) |
228. | `tests/seed-show.hl` | writes the gate's fixture show (two seasons, three episodes) and, since ticket #5, a follow of it for the test user, before the server starts |
229. | `tests/identkit.mjs` | starts a throwaway ident copy for the gate, copied from calendar.worldapi.org's `tests/` |
230. | `tests/cdp.mjs`, `tests/ports.mjs` | the CDP browser driver, copied from `ident.worldapi.org/tests/` |
231. | `docker-compose.yml`, `Dockerfile`, `deploy.sh` | Byrodin container; the deploy from Loreana (section "Deploy") |
232. | `tools/migrate.hl` | one-off: old MongoDB export → `storage/mpackdb/` (step 2, idempotent, see `STATUS.md`) |
233. | `tools/verify.hl` | one-off: proves the migrated data against a COPY of `storage/mpackdb/` (counts, zero dangling references, one show end to end) |
234. | `tools/relink-episode-seasons.hl` | one-off: links episodes with no `season` (step 2 leftovers) by `(show, seasonNumber)` — not run against the live data yet, see "What it does (step 4)" |
236. ## Vendored Hybriel
238. `bin/hybriel` + `plugins/` copied verbatim from `ident.worldapi.org` (2026-09-27), sha256
239. `9e5e95b33680eb68a016e9e48a76c9f92193fd2ffdbdf437c1aab1bda2731a0d` — hybriel master
240. 837fe120 (ident's mission 036), the newest vendored+gated build available locally. No local
241. patch. Re-vendor the same way: copy `bin/hybriel` + `plugins/` from a current worldapi app,
242. run the gate.