Swamp Pulse

A leaderboard-style activity dashboard for the swamp project itself: it tracks Lab issues, GitHub commits and GitHub releases, merges the three views of one change into a single ranked item, and renders six linked static HTML pages. WHAT IT DOES

Turns the raw firehose of swamp-project activity into a ranked, readable dashboard. A release, its commit and its pull request are the same event, so instead of listing them three times Pulse joins them into one merged item and ranks items by a synthesized significance hierarchy (tier first, recency as tie-break). It renders a documentation summary, an activity leaderboard, an extension-registry page (new / updated / most-pulled), and releases, changes and issues detail pages, each with 24-hour, 7-day and current-month windows and every item linked back to its source. Prefer it over reading the commit log or the issue tracker directly: it answers "what shipped, and does it matter?" in one page, and runs hourly.

INSTALL

# One pull; the declared dependencies install automatically.
swamp extension pull @svendowideit/swamp-pulse

DEPENDENCIES

@webframp/github (extended for the commit/release collectors) and @svendowideit/github-pages (opt-in publishing), both declared in dependencies: and installed by the single pull above. Serving the pages over HTTP additionally uses @svendowideit/systemd-service, and the Caddy publish target uses @svendowideit/caddy; both are optional and only needed if you enable those features.

RUN

# Collect, rank and render in one pass; scheduled hourly by default.
swamp workflow run @svendowideit/swamp-pulse

# Track a specific repository instead of the default set.
swamp workflow run @svendowideit/swamp-pulse \
  --input 'repos:json=["swamp-club/swamp"]'

# See every setting, its current value, and the exact command to change it.
swamp model @svendowideit/swamp-pulse method run setup pulse

Output lands in ~/.swamp/swamp-pulse/ (index.html, leaderboard.html, extensions.html, changes.html, releases.html, issues.html). Publishing is opt-in and never runs by default.

CONFIGURE

All settings are optional and public data needs no secrets. Configure the pulse model instance with global args, or per run with --input:

publishMode       false | caddy | github-pages   (default false)
pagesRepo         owner/repo for github-pages    (required when publishing)
pagesBranch       Pages branch                   (required when publishing)
pagesPath         / or /docs                     (default /)
pagesCname        custom domain
caddyHostname / caddyUpstream                    (for caddy mode)
outputDir         where the HTML is written      (default ~/.swamp/swamp-pulse)
windows           time windows to render         (default 24h, 7d, month)

Precedence is per-run --input > model global arg > schema default, so a bare swamp workflow run never overrides a configured instance. The repositories to track are a workflow input (repos), not a model global.

WHAT IT INSTALLS

No services, triggers, or webhooks on the host by default — it writes static HTML into outputDir when the workflow runs. If you enable the local server (ensure-server step), it installs a systemd user service (via @svendowideit/systemd-service) and enables lingering so the page is served at boot; publishing to GitHub Pages or Caddy commits/serves the pages only when you explicitly select that mode.