@rackbops/plugin-tracker 0.4.0 → 0.6.0

package/README.md

@@ -5,9 +5,11 @@ on a rackbops-discord-bot instance. Plan of record: Rackbops/Tooling
 `research/city-hall-task-tracker.md` (sections 0, 5.1-5.3, 5.5, 5.8, 5.10). This version is the core
 (rackbops-bot-plugins#78), the Discord surface of the first slice (#79) -- reminders by slash
 command, delivered by DM, answered by button, with history -- the first slice of the web area
-(#80): sign-in by one-time link, my tasks, a task's history, and settings -- and renewals and
+(#80): sign-in by one-time link, my tasks, a task's history, and settings -- renewals and
 the price tracker (#81, plan E6): two more types on the notify side, no model, nothing sent to
-city-hall.
+city-hall -- the web area's task editor (#80, slice 2): make, edit, pause, resume and delete
+your own tasks from the web, under the commands' own rules -- and the admin view and forget-me (#80,
+slice 3).
 
 ## Commands
 
@@ -26,7 +28,7 @@ as in a server (plan 5.5, item 39).
 | `/task decide task choice [amount]` | the renewal's owner | Answers the renewal's latest ask -- keep, cancel or renewed -- with the amount actually paid when it changed (a button cannot carry one). Use it instead of the button, not after it: a run is answered once. |
 | `/task history task` | the owner, an accepted recipient, or an admin | Every run -- due, status, how it was answered, text replies -- and the task's changes; for a renewal, what each period cost and the total; for a price, the last check and the readings with the low and the high. |
 | `/task share task user` | the task's owner | Invites an admitted, registered member who can be DMed: they get one consent DM with accept and decline. |
-| `/task resume task` | the task's owner | Resumes a task paused because a recipient could not be DMed, taking that recipient off it. |
+| `/task resume task` | the task's owner | Resumes a paused task: one paused because a recipient could not be DMed goes on without that recipient; one its owner paused on the web simply goes on. |
 | `/settings hour hour` | registered | The preferred hour; recurring reminders with no time of their own move to it. |
 | `/web` | registered | A one-time link to sign in to the web area (below), good for 10 minutes and one use. Says so when `TRACKER_WEB_URL` is unset. |
 
@@ -58,9 +60,17 @@ served at a hashed path, cached for a year).
 
 | Path | What |
 |---|---|
-| `/` | My tasks: the same list as `/tasks` (active tasks owned and received, next run in your zone; paused ones and why), each linking to its history. |
-| `/tasks/<id>` | A task's history: the same as `/task history`, for the owner, an accepted recipient or an admin. Anyone else gets the same 404 as an unknown id. |
+| `/` | My tasks: the same list as `/tasks` (active tasks owned and received, next run in your zone; paused ones and why), each linking to its history, and links to make a new one. |
+| `/tasks/<id>` | A task's history: the same as `/task history`, for the owner, an accepted recipient or an admin. Anyone else gets the same 404 as an unknown id. The owner also sees Edit, Pause or Resume, and Delete. |
+| `/new/reminder`, `/new/renewal`, `/new/price` | The editor's new-task forms (GET), and making one (POST). |
+| `/tasks/<id>/edit` | The owner's edit form (GET) and saving it (POST). |
+| `/tasks/<id>/pause`, `/resume`, `/delete` | POST only. Delete answers a confirmation first; only a second post carrying `confirm=yes` deletes. |
 | `/settings` | Preferred hour and time zone, checked as `/register` checks them. |
+| `/forget` | Forget me (below): what it deletes (GET); a POST asks for the confirmation; a POST with `confirm=yes` and the word `forget` erases. Linked from Settings. |
+| `/admin` | Admins only: everyone on the list, the decline blocks in force (each with Lift), and a form to allow a person by Discord id. |
+| `/admin/tasks` | Admins only: every task in the store, with its owner, status and how many receive it, each linking to its page. |
+| `/admin/people/<id>` | Admins only: one person -- Discord id, registration, zone and hour, delivery, task counts, their tasks -- with Make admin or Revoke admin, Resume delivery (when paused), and Remove from the tracker. |
+| `/admin/allow`, `/admin/people/<id>/grant`, `/revoke`, `/resume-delivery`, `/forget`, `/admin/blocks/<id>/lift` | Admins only, POST only: the acts below. |
 | `/signin` | Where a request that is not signed in is sent: says to run `/web`. |
 | `/login?t=...` | The link `/web` gives. |
 
@@ -83,6 +93,33 @@ than `TRACKER_WEB_URL`'s is refused. The sign-in post has no session yet, so it
 double-submit token from a `SameSite=Strict` cookie the link's page sets: another site cannot sign
 you in as someone else. Sign out is a POST too.
 
+**The task editor** (slice 2). The forms take the options of `/remind`, `/renewal` and `/price`,
+and the same functions check and make them: the same defaults, limits and messages, the page read
+once before a price tracker is made, at most 20 price trackers per person wherever they were made,
+and `near` turned into the same bounded pattern; a person has one new price tracker's page read in
+flight at a time. Every person may have at most 200 active or paused tasks of all types together,
+made anywhere. The length limits are one set (`src/limits.ts`) for the slash options, the forms
+and the server's checks. An edit changes a reminder's text, time and repeat
+(an empty time keeps the one it has, unless the repeat changes); a renewal's name, amount,
+currency, date, unit, every, lead and note (a new amount is the one the next ask quotes; a new date
+gets `/renewal`'s first-ask rule, but a date a run already asked about is not asked again); a price's name, interval,
+drop and baseline, never its page. A schedule change cancels and replaces what is queued and keeps
+snoozes, as a zone move does, and each change is in the task's history. An empty field keeps what
+the task has (an empty note clears it; an empty price name is the page's address). A renewal date
+that is one of the schedule's own period dates keeps the schedule and its anchor as they are, so the
+31st stays the 31st; only a different date re-anchors. A finished task cannot be
+edited. Pause holds everything the task would send until Resume, and a person's delivery resuming
+does not undo it; a run missed while paused fires once, late, on resume, and a zone or hour change
+re-times the run a paused task holds -- same period date or local day, new zone or hour, still one
+run -- so it is neither lost nor sent at the old time. Resume on a task paused
+for failed DMs is `/task resume`. Delete archives the task: it leaves every list, its queued runs
+are dropped and nothing more is sent, but its history is kept (an admin can see every task) and
+its page stays for the owner. Every editor post passes the session, CSRF and `Origin` checks; the
+task is loaded by the id in the path and must be the viewer's own, checked again in the write
+queue, and anyone else's -- even one an admin can see -- answers the same 404 as an unknown id. A
+refused form comes back with what was typed and why. Form bodies are capped at 32 KiB, read no
+further than that.
+
 **Headers.** `Content-Security-Policy: default-src 'none'; style-src 'self'; img-src 'none';
 form-action 'self'; frame-ancestors 'none'; base-uri 'none'`, `X-Content-Type-Options: nosniff`,
 `X-Frame-Options: DENY`. Every value on a page is HTML-escaped. An unknown path is 404; a method
@@ -99,7 +136,86 @@ while the last confirmation is under 24 hours old, and are then signed out and t
 again. Concurrent requests share one lookup per person, and after a failed one that person is not
 looked up again for a minute, so an outage or rate limit does not pile up calls. A confirmation
 time in the future (a clock set back) counts as stale. Every lookup asks Discord (`force: true`),
-never discord.js's member cache, which with only the Guilds intent never learns that someone left. There is no way yet to take a person off the tracker (forget-me and the admin view, below).
+never discord.js's member cache, which with only the Guilds intent never learns that someone left.
+
+**The admin view** (slice 3, plan 5.8, 5.10). An admin is a person whose row in the tracker's store
+has the admin flag -- the one admin definition; `/allow` checks the same flag. `TRACKER_ADMIN_DISCORD_IDS`
+grants it at start; admins grant and revoke it here. The flag is read from the store on every
+request, and again inside the write queue before any admin act, so an admin whose flag is revoked is
+refused on their very next request. To a signed-in person who is not an admin, every `/admin` path --
+any method -- answers the same 404, byte for byte, as an unknown page; a visitor who is not signed in
+is sent to sign in, as on every other signed-in path. An admin sees every person, every task
+and every task's page and history, read-only: an admin never edits, pauses or deletes another
+person's task (the owner's acts answer them 404, as in slice 2). What an admin can do, each through
+the function the command path runs:
+
+- **Allow** a person by Discord id: `/allow`'s own `allowPerson`, with the same server-membership
+  check when `TRACKER_GUILD_ID` is set (one bounded lookup; no Discord client yet since a restart
+  refuses, as an unknown answer does). A form cannot tell a bot's id from a person's; a bot's row can
+  never `/register`.
+- **Make admin / Revoke admin** (plan 5.8). The last admin can be neither revoked nor removed. An
+  admin who revokes themselves lands on My tasks. Each change is logged (`u1 made u2 an admin`).
+  An admin named in `TRACKER_ADMIN_DISCORD_IDS` is made an admin again at every start, so their page
+  offers neither Revoke nor Remove, and both are refused: take them out of the configuration first.
+  Such an admin may still forget themselves (if another admin is left); the pages say that the next
+  start makes them again, as a new person, unless the configuration no longer names them.
+- **Resume delivery** of a person paused after failed DMs: `DeliveryHealth.resume`, what the
+  person's own next command does -- the count clears and the tasks nothing else holds go back on.
+- **Lift** a decline block in force: docket's `liftBlock`, recorded as that admin's lift.
+- **Remove from the tracker**: forget-me for that person (below), with the same confirmation.
+
+Not here yet, though plan 5.10 lists them: grants, budgets and retry (they belong to the execute
+lane, which is not built) and an admin pause of someone else's task.
+
+**Forget me** (plan 5.8). A signed-in person erases themselves from `/forget` (web only: the plan
+asks for no Discord command, so without `TRACKER_WEB_URL` the only path is an admin with the web
+area). Two posts: the first asks, the second must carry `confirm=yes` and the word `forget`. Then,
+in one SQLite transaction in the write queue, **deleted, not archived**:
+
+- every task they own, archived ones too, with everything under it: runs, run events, replies
+  (anyone's), history, series, recipients, delivery claims and pauses;
+- on everyone else's tasks: their recipient rows, their replies and answers, the history rows they
+  made or that name them (an invitation of them, a pause for them), the run events and delivery
+  claims of DMs to them, and their pause rows;
+- every decline block they are either side of;
+- their admission, delivery health, web sessions and unused sign-in links, and their person row.
+
+What stays, and why: another person's task that they received stays that owner's; one paused only
+because DMs to them failed goes back on. Another person's row keeps its own audit fact but not their
+id -- `admitted_by` of someone they admitted, and `lifted_by` of a block they lifted, become
+`forgotten` ("an admin since forgotten"; null already means "the configuration"). Text is matched
+only in the forms the code writes a person's id into -- docket's consent rows (`u5`, `u5 24h`), the
+tracker's `u5: ...` removals and `delivery to {u5} paused` pauses, docket's `u5 <message>` delivery
+events, and the notifier's error phrases (`recipient u5 cannot be messaged`, ...) -- never as any
+id-like word, so an address with `/u5/` in someone else's text is left alone. A history row or a
+delivery event of theirs is deleted; the error of someone else's run keeps its row and has the id
+replaced with `(forgotten)`. A pause for a recipient now names them by id and shows their current
+name when read; a pause row written before 0.6.0 names the recipient's display name of the time,
+and is deleted when it is on a task they were a recipient of, names their current name, and no
+other recipient of that task has that name. A row written under an older name of theirs, or shared
+with a same-named recipient, is kept: the one known gap. A reply other people wrote on the erased
+person's own tasks is deleted with those tasks. Outside the store, nothing is touched: the DMs the
+bot sent stay in the person's Discord DMs, and the host's log may hold their tracker id.
+
+Bytes: the database runs with `secure_delete` on, so a deleted row is overwritten, and the first
+start of 0.6.0 on an existing database runs one `VACUUM`, so pages freed before that are rewritten
+too. That one-time VACUUM is recorded in a small `tracker_meta` table, not by a schema bump: the
+schema stays at 3, so rolling back to 0.5.0 still opens the database. If the VACUUM cannot run (a
+reader holds the file), the start goes on, a warning is logged, and the next start tries again.
+Not a VACUUM per erasure: it rewrites the whole file under an
+exclusive lock, and `secure_delete` already covers every later delete. After an erasure the
+write-ahead log is checkpointed without waiting; when a reader keeps it busy, that is logged and
+SQLite's next checkpoint copies it back.
+
+Timing: forget-me first waits, outside the write queue, until no notify or poll tick is running (at
+most 20 seconds; then it answers 503, try again, and deletes nothing), so a reminder DM to them
+already in flight cannot be recorded after they are gone -- and no one else's command waits behind
+it. Inside the queue it only checks that no tick started meanwhile (else the same 503). A DM sent
+outside any tick -- an invitation's -- that fails after they are gone writes nothing: the failure
+count is not kept for a person no longer in the store, and the withdrawn invitation is not
+recorded. A `/price` whose page is read while its person is forgotten makes nothing. Their sessions
+are among the rows, so they are signed out everywhere at once, and the browser's cookie is cleared. They can come back only as someone new: an admin
+`/allow`s them again, and the tracker never reuses an id.
 
 **Choose the web origin's domain with care.** A host under the same parent domain as
 `TRACKER_WEB_URL` that you do not control can set a `__Secure-` cookie on the parent domain
@@ -114,13 +230,15 @@ The `__Host-` prefix, which would stop that, requires `Path=/` and so cannot be
 | Store | `src/store.ts`, `src/schema.ts` | docket's `Store` port on `bun:sqlite`, in `<dataDir>/tracker/tracker.sqlite` (WAL). A Discord id belongs to at most one user. Schema versioned by `PRAGMA user_version`; a shipped migration is never edited. `store.test.ts` runs docket's `STORE_CONTRACT` against it. |
 | Notify lane | `src/notify-lane.ts` | docket's `Lanes.tickNotify` on two host ticks, every 60 s, through a view of the store that skips a paused task's due runs: `notify` runs every type but the page readers, `poll` runs only them (`price`) with the Fetch port, so a slow page never holds up a reminder. Registers `reminder`, `renewal` and `price`. The execute lane is not ticked. |
 | Page reads | `src/fetch.ts` | docket's `Fetch` port for `price`: http or https on the default port, no credentials, every resolved address public (no loopback, private, link-local, CGNAT, multicast or reserved range, IPv4 or IPv6), redirects followed by hand and re-checked (at most 5), 15 s including the name lookup, at most 3 MB kept. The body is then rebuilt in linear time (`src/page.ts`) to just what extraction reads -- JSON-LD, meta tags, and the page with every `<` blanked, so `near` still reads text, attributes and script data -- because docket's extraction patterns take quadratic time on a page of unclosed tags. A read the tick's abort cuts short requeues its run instead of counting a miss. A DNS answer that changes between the check and the read is not caught here. |
-| Renewals, prices | `src/tracked.ts`, `src/series.ts`, `src/page.ts` | `/renewal`, `/price` and `/task decide`; the series lines of `/task history`. The series (docket's `series` table, schema 1) holds a renewal's paid amounts and a price's readings. |
+| Renewals, prices | `src/tracked.ts`, `src/price.ts`, `src/series.ts`, `src/page.ts` | `/renewal`, `/price` and `/task decide`; the series lines of `/task history`. The series (docket's `series` table, schema 1) holds a renewal's paid amounts and a price's readings. |
 | Delivery | `src/notifier.ts`, `src/claims.ts`, `src/buttons.ts` | docket's `Notifier` over `host.dm`, with the buttons. Each (occurrence, person) is claimed in `delivery_claims` before the DM is sent and settled after; a claim never settled is not resent -- it is logged once, as unconfirmed. |
 | Pause | `src/delivery-health.ts` | The per-person failure count, the pause and the resume. |
 | People | `src/people.ts`, `src/admissions.ts` | Discord id, time zone, preferred hour, admin flag -- in the tracker's store, never usr; who admitted each person and when they registered. `TRACKER_ADMIN_DISCORD_IDS` only ever grants admin. |
 | Commands | `src/discord.ts`, `src/interactions.ts`, `src/discord-common.ts` (discord.js); `src/actions.ts`, `src/press.ts`, `src/history.ts`, `src/access.ts` | The discord.js files read options and render; the rest is Discord-free over the injected store, clock and notifier. Store writes are handled one at a time; Discord lookups and DMs run outside that queue. |
 | Health | `src/health.ts` | `GET /tracker/healthz` (through the bot's HTTP router): `200` `ok`/`starting`, `503` `inactive`/`stale`/`blocked`. |
-| Web area | `src/web/` | `app.ts` routes (pure over the injected store and clock); `pages.ts` and `html.ts` render; `signin-link.ts` and `sessions.ts` hold the sign-in; `theme.ts` the stylesheet; `command.ts` is `/web`. |
+| Admin, forget-me | `src/admin.ts`, `src/roster.ts`; `src/web/admin.ts`, `src/web/admin-pages.ts` | The admin acts and forget-me, Discord-free; the SQL docket's Store has no method for (listing people and blocks, erasing a person); the routes and pages. |
+| Web area | `src/web/` | `app.ts` authenticates and dispatches (pure over the injected store and clock), `routes.ts` names the paths; `pages.ts`, `editor-pages.ts` and `html.ts` render; `editor.ts` reads the editor's forms and calls the shared rules; `signin-link.ts` and `sessions.ts` hold the sign-in; `theme.ts` the stylesheet; `command.ts` is `/web`. |
+| Task rules | `src/reminders.ts`, `src/tracked.ts`, `src/price.ts`, `src/edit.ts`, `src/manage.ts`, `src/limits.ts` | What makes, edits, pauses, resumes and deletes a task, and the limits on it, Discord-free, for the commands and the web editor alike. |
 
 ## Configuration
 
@@ -134,11 +252,11 @@ The `__Host-` prefix, which would stop that, requires `Path=/` and so cannot be
 
 ## Not yet
 
-- The rest of the web area (E5): editing tasks, the admin view, lifting a decline block, forget-me,
-  and the JSON task API. Until forget-me and the admin view exist, nobody can be taken off the
-  tracker, so a web session ends only by sign-out, expiry, or the membership re-check. Discord OAuth2 as a second sign-in method, if chosen (plan item 41).
+- The rest of the web area (E5): sharing a task from the web, the JSON task API, and the admin
+  view's grants, budgets and retry (with the execute lane). Discord OAuth2 as a second sign-in
+  method, if chosen (plan item 41).
 - The city-hall Executor adapter (the execute lane).
-- Editing a renewal or a price tracker after it is made (for now: `/task done`, or cancel, and make it again); a free-form pattern for `price` (`near` is the safe subset: a user's regular expression run on a large page could hang the bot).
+- Editing in Discord (the editor is on the web only), and changing a price tracker's page or `near` after it is made (make a new one); a free-form pattern for `price` (`near` is the safe subset: a user's regular expression run on a large page could hang the bot).
 - An optional Discord-role gate (plan 5.5), and showing unconfirmed deliveries to admins anywhere but the log.
 
 docket-core, docket-types and `@rackbops/styles` are `devDependencies`: `bun build` bundles them