Bulletins for web and term server

[awehttam]

Add bulletins that are shown at login in both web and telnet. Add a bulletins sub-item to messaging as well.

[awehttam]

Draft — This proposal was generated by AI and may not have been reviewed for accuracy. It is a design document and has not yet been implemented.

Bulletins System Proposal

Overview

A sysop-managed bulletins system that shows ordered announcements to users on login — before the dashboard (web) and before the shoutbox (terminal server). Supports multiple bulletins with per-page navigation. Each bulletin is tracked per-user so it is shown once until dismissed.

---

Design Decisions

Question	Decision
Storage	Dedicated bulletins + bulletin_reads tables
Format	Two-value enum: plain (ANSI decode + autolink) or markdown
Seen tracking	Per-bulletin dismiss via bulletin_reads junction table
Web (login)	Redirect to /bulletins interstitial if unread bulletins exist
Web (nav)	Accessible from Messaging menu as "Bulletins"
Web (dashboard)	Dashboard widget showing unread count
Terminal	Shown after login, before the shoutbox, in BbsSession::run()

---

Schema

Migration: database/migrations/vX.Y.Z_bulletins.sql (check current highest version in that directory before creating)

CREATE TYPE bulletin_format AS ENUM ('plain', 'markdown');

CREATE TABLE bulletins (
    id           SERIAL PRIMARY KEY,
    title        VARCHAR(255) NOT NULL,
    body         TEXT NOT NULL,
    format       bulletin_format NOT NULL DEFAULT 'plain',
    sort_order   INT NOT NULL DEFAULT 0,
    is_active    BOOLEAN NOT NULL DEFAULT TRUE,
    active_from  TIMESTAMP WITH TIME ZONE,   -- NULL = no start constraint
    active_until TIMESTAMP WITH TIME ZONE,   -- NULL = no end constraint
    created_by   INT REFERENCES users(id) ON DELETE SET NULL,
    created_at   TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT (NOW() AT TIME ZONE 'UTC'),
    updated_at   TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT (NOW() AT TIME ZONE 'UTC')
);

CREATE TABLE bulletin_reads (
    user_id     INT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    bulletin_id INT NOT NULL REFERENCES bulletins(id) ON DELETE CASCADE,
    seen_at     TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT (NOW() AT TIME ZONE 'UTC'),
    PRIMARY KEY (user_id, bulletin_id)
);

CREATE INDEX idx_bulletins_active ON bulletins (is_active, sort_order)
    WHERE is_active = TRUE;

Active bulletin query must filter:

is_active = TRUE
AND (active_from IS NULL OR active_from <= NOW())
AND (active_until IS NULL OR active_until > NOW())

---

Backend: src/BulletinManager.php

New class. Key methods:

Method	Description
getActiveBulletins(): array	All currently-active bulletins, ordered by sort_order
getUnreadBulletins(int $userId): array	Active bulletins not yet in bulletin_reads for this user
markRead(int $userId, int $bulletinId): void	Insert into bulletin_reads
markAllRead(int $userId, array $bulletinIds): void	Batch dismiss
create(array $data): int	Insert; return new id
update(int $id, array $data): void	Update existing bulletin
delete(int $id): void	Delete bulletin and cascade reads
reorder(array $orderedIds): void	Update sort_order from ordered id list

---

API Endpoints

Add to routes/api-routes.php:

Method	Path	Description
GET	/api/bulletins	List active bulletins; includes is_read flag per user
POST	/api/bulletins/{id}/read	Mark one bulletin read for current user
POST	/api/bulletins/read-all	Batch dismiss list of bulletin IDs
GET	/admin/api/bulletins	Admin: list all bulletins (any status)
POST	/admin/api/bulletins	Admin: create bulletin
PUT	/admin/api/bulletins/{id}	Admin: update bulletin
DELETE	/admin/api/bulletins/{id}	Admin: delete bulletin
POST	/admin/api/bulletins/reorder	Admin: update sort order

---

Web Routes

Add to routes/web-routes.php:

/bulletins — auth required

Renders templates/bulletins.twig. Passes all active bulletins; JS handles read status and paging.

Login redirect in / route

After the existing auth check, before rendering the dashboard:

$bulletinManager = new \BinktermPHP\BulletinManager();
$unread = $bulletinManager->getUnreadBulletins((int)$user['id']);
if (!empty($unread) && !isset($_GET['skip_bulletins'])) {
    return SimpleRouter::response()->redirect('/bulletins');
}

/admin/bulletins — admin only

Renders templates/admin/bulletins.twig.

---

Templates

templates/bulletins.twig

Full-page bulletin viewer:

• Title + position indicator ("Bulletin 1 of 3")
• Body rendered by format: markdown → rendered HTML, plain → ANSI-decoded + autolinked text (same pipeline as echomail plain messages)
• Prev / Next / Skip All / Done buttons
• Done marks remaining as read and redirects to /

templates/admin/bulletins.twig

Admin management UI:

• Sortable list (up/down or drag handles) for sort_order
• Create / edit with: title, body textarea, format selector (plain / markdown), active toggle, optional active_from / active_until date pickers
• When markdown is selected, initialize the Toast UI Editor (same as templates/compose.twig) in place of the plain textarea. Sync editor content back to a hidden textarea on change, following the same initMarkdownEditor() pattern used for echomail compose.
• Preview pane showing rendered output
• Delete with confirmation

Dashboard widget in templates/dashboard.twig

Add a bulletins card to the default layout via DashboardCardRegistry. Shows unread count and link to /bulletins.

---

Navigation

Per the template resolution rules, both nav templates must be updated to add a "Bulletins" link under the Messaging section:

• templates/base.twig
• templates/shells/web/base.twig

---

Terminal Server

telnet/src/BulletinsHandler.php — new class

Constructor receives $server, $conn, $state. Primary method showBulletins():

• Fetches unread bulletins for the logged-in user via BulletinManager::getUnreadBulletins().
• For each unread bulletin:
  • Render with TerminalMarkupRenderer (handles both plain and markdown), display in TerminalBoxRenderer::showPagedBox() with the bulletin title as the box header.
  • Prompt: [Enter] Next [S] Skip All
• After showing (or skipping) all bulletins, batch-marks them read via BulletinManager::markAllRead().

Injection point in telnet/src/BbsSession.php

Insert in run() after showSystemNews() (line ~439), before the shoutbox:

$bulletinsHandler = new BulletinsHandler($this->server, $conn, $state);
$bulletinsHandler->showBulletins();

require_once in daemon entrypoints

BulletinsHandler is not Composer-autoloaded for the telnet/SSH daemons. Add require_once for it in:

• telnet/telnet_daemon.php
• ssh/ssh_daemon.php

Terminal main menu

Add a "Bulletins" item to the Messaging or Community section of the procedural menu in BbsSession::run() (lines ~461–602).

---

i18n Keys

Add to every locale directory under config/i18n/ (en, es, it, fr) in common.php:

ui.bulletins.title
ui.bulletins.count            (e.g. "Bulletin {current} of {total}")
ui.bulletins.no_new
ui.bulletins.next
ui.bulletins.prev
ui.bulletins.skip_all
ui.bulletins.done
ui.admin.bulletins.title
ui.admin.bulletins.create
ui.admin.bulletins.edit
ui.admin.bulletins.delete_confirm
ui.admin.bulletins.sort_order
ui.admin.bulletins.format
ui.admin.bulletins.active_from
ui.admin.bulletins.active_until

---

Files to Create or Modify

File	Change
database/migrations/vX.Y.Z_bulletins.sql	New migration (check current highest version first)
src/BulletinManager.php	New class
routes/api-routes.php	Bulletin API + admin API endpoints
routes/web-routes.php	/bulletins route + redirect logic in / + /admin/bulletins
templates/bulletins.twig	New template
templates/admin/bulletins.twig	New admin template
templates/base.twig	Add Bulletins nav link
templates/shells/web/base.twig	Add Bulletins nav link
templates/dashboard.twig	Add bulletins dashboard card
telnet/src/BulletinsHandler.php	New terminal handler class
telnet/src/BbsSession.php	Inject BulletinsHandler::showBulletins() at line ~439
telnet/telnet_daemon.php	Add require_once for BulletinsHandler
ssh/ssh_daemon.php	Add require_once for BulletinsHandler
config/i18n/en/common.php (+ es, it, fr)	New i18n keys
public_html/sw.js	Bump CACHE_NAME

---

Verification

1. Create a bulletin in the admin panel; confirm it appears in the database.
2. Log out, log back in → redirected to /bulletins interstitial.
3. Page through all bulletins, click Done → lands on dashboard; dashboard widget shows "No new bulletins".
4. Log out, log back in → no redirect (all bulletins dismissed).
5. Create a new bulletin → login redirects to /bulletins again, showing only the new one.
6. Terminal: login via telnet/SSH → bulletin appears before the shoutbox; Enter advances; S skips all remaining.
7. Plain-format bulletin: verify ANSI codes are decoded and URLs are autolinked on both web and terminal.
8. Scheduling: bulletin with active_until in the past must not appear.
9. Run i18n check scripts before committing:
   • php scripts/check_i18n_hardcoded_strings.php
   • php scripts/check_i18n_error_keys.php

[awehttam]

Implemented in 1.9.5