diff --git a/openspec/changes/demo-activity-bot/.openspec.yaml b/openspec/changes/demo-activity-bot/.openspec.yaml new file mode 100644 index 0000000..c8af3f5 --- /dev/null +++ b/openspec/changes/demo-activity-bot/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-19 diff --git a/openspec/changes/demo-activity-bot/design.md b/openspec/changes/demo-activity-bot/design.md new file mode 100644 index 0000000..2925617 --- /dev/null +++ b/openspec/changes/demo-activity-bot/design.md @@ -0,0 +1,154 @@ +## Context + +The Journal runs on a single Hetzner Cloud container with Postgres + PostGIS, BRouter as a sibling compose service, and pg-boss already configured as the background-job queue (`apps/journal/server.ts` boots a worker on startup). `public-content-visibility` introduces a `visibility` column on routes + activities; once that lands, a piece of content marked `public` is viewable by logged-out visitors at its permanent URL and on the owner's `/users/:username` profile. + +This change layers a synthetic-content generator on top. The motivation is narrow — a non-empty feed for prospective users we're demoing to. The design matches that: **cheap, single-region, single-user, single-purpose**. Nothing here should generalise to "simulate a real community"; the bot is allowed to look slightly repetitive because it exists to fill an empty demo, not to fake scale. + +Adjacent context: +- BRouter runs internally and already rate-limits per-session at the Planner, but here we're inside the Journal server, so the bot controls its own cadence rather than sharing a limiter with user-driven routing. Load is low — at most a handful of routes per day. +- pg-boss supports cron-style recurring schedules and singleton jobs (no concurrent duplicates), which are exactly what we need. + +## Goals / Non-Goals + +**Goals:** +- A logged-out visitor landing on `trails.cool/users/demo` sees a recent-looking public profile with several routes and activities. +- The content is generated entirely on-host, with no third-party data calls. +- Synthetic content is trivially separable from real content (single boolean flag). +- The bot can be disabled without a deploy (env flag) and its output wiped with a single DELETE. +- Cadence is boring. One content item every few hours is enough — we are not trying to pretend a Strava-scale community. + +**Non-Goals:** +- Realistic social signals (likes, comments, follower counts). +- Multiple bot personas or multi-region coverage. +- Route topology tricks beyond "point-to-point via BRouter" (no multi-day, no loops, no no-go areas). +- Photos or media on activities. +- Running the bot in local dev / CI / staging — disabled by default everywhere except prod. + +## Decisions + +### Single bot user: Bruno the trail dog + +**Decision:** One account with: + +- Username: `bruno` (reserved; a later real registration with that username is blocked) +- Display name: `Bruno` +- Bio: short, whimsical, something like *"Professional park inspector. Currently accepting tennis balls."* +- Sentinel email: `bruno@` — unroutable, so magic-link login cannot succeed +- No passkey credentials +- `terms_accepted_at` / `terms_version` populated to the current values at bootstrap + +The persona is a park-walking dog whose "human" logs the walks. This choice: + +- Makes the bot legibly fictional at a glance — a dog account with emoji-laced names reads as *charming*, not as a real-user-you're-being-tricked-into-believing-in. +- Narrows the generator's parameter space (trekking profile only, short distances, urban parks) so output is consistent and failure-prone edge cases get pruned. +- Keeps the copy bank small and writable in one sitting. + +**Alternatives considered:** +- **"Finn" — realistic commuter-cyclist.** Fills the feed convincingly, but deception risk if a visitor later realises. Rejected. +- **"trails.cool test pilot" — explicitly diagnostic.** Honest but dead boring; kills the "lively feed" goal the bot exists for. Rejected. +- **Multi-persona community simulation.** Out of scope for v1. + +### Bruno's generation parameters + +**Decision:** The persona constrains the generator more tightly than the generic v1 draft: + +- **Profile pool**: `["trekking"]` only (dogs don't ride bikes). +- **Distance band**: 2–12 km crow distance between start and end — a realistic walk, not a hike. +- **Region**: Berlin inner (bbox roughly `13.25,52.45,13.55,52.60`), biased toward parks/green areas: Grunewald, Tiergarten, Tempelhofer Feld, Volkspark Friedrichshain, Treptower Park, Müggelsee shoreline. The bbox itself is permissive; the copy just reads as park-flavoured. +- **Started-at window**: 07:00–20:00 local, with a slight bias toward morning/evening ("walkies" times). +- **Copy templates**: a mix of serious-sounding audit language ("Grunewald north-loop patrol") and comic ("Bruno found three sticks today 🐕"). Bilingual EN + DE. + +**Why narrower:** the persona is a feature, not a limitation. Not every dog-walk needs to be in a park, but pretending Bruno walked 40 km across Brandenburg would break the illusion the whole persona exists to prop up. + +### Route generation: BRouter point-to-point in a seed region + +**Decision:** A configured seed region is a bounding box. For the Bruno persona: + +- Region: Berlin inner (`13.25,52.45,13.55,52.60`) — narrower than "Berlin + Brandenburg"; a dog-walk spanning Brandenburg breaks the illusion. +- Profile: `trekking` only (see the Bruno persona decision above). +- Start point: random within the box. +- End point: 2–12 km crow distance from start. +- Query BRouter with those two waypoints and `trekking`; reject and retry if BRouter returns no route or the computed distance is outside a sanity band (say, 1.5–18 km real distance). +- Persist the returned GPX as the route's source of truth and let existing enrichment compute the rest (PostGIS geom, distance, elevation). + +The bbox stays env-configurable; changing `DEMO_BOT_REGION` relocates Bruno without a code change. + +**Alternatives considered:** +- **Pre-recorded GPX files in a corpus.** Chosen by user to be (b) — synthesised via BRouter — in the conversation that led here. Keeps variety cheap and relocatable (change the bbox, new city). +- **Komoot import** — reject, external dependency. +- **Multi-waypoint (3+ stops)** — slight realism gain, much higher generation failure rate (more chances for BRouter to return no-route). Skip. + +### Activity generation follows the route + +**Decision:** When a route is generated, immediately derive an activity from it: + +- `route_id` links to the new route +- `name` and `description` drawn from a small templated set (e.g., "Weekend ride through the Havelland", "Evening loop around Müggelsee") +- `started_at` = today between 06:00 and 20:00 local (random), `duration` = distance ÷ an average speed per profile ± jitter +- `distance`, `elevation_gain`, `elevation_loss` = the route's computed values +- `gpx` = the route's GPX verbatim (the activity "happened" along the planned route) +- `visibility = 'public'`, `synthetic = true` + +**Why bundled:** keeping route + activity generation in one transaction means the feed item is coherent the moment it appears. Separating them just to pretend the user planned then rode feels like theatre — we're not hiding the bot, we're just filling the surface. + +### Cadence and guards + +**Decision:** A dog walks twice a day, sometimes three times, never six. The schedule should look like Bruno's day, not like a cron job. + +- A recurring pg-boss job `demo-bot:generate` fires **every 90 minutes** as a singleton. +- Most ticks decide to *not* walk: the handler rolls a per-tick probability and skips if it doesn't hit. The probability is **0.12 per tick during 07:00–21:00 local, 0 otherwise** — which yields roughly 2–3 walks per day across the day, biased to waking hours. +- This both looks human (walks aren't on a fixed cron) and makes the generation load tiny: one BRouter call per walk, so ~2–3 per day. +- The job skips itself entirely when `process.env.DEMO_BOT_ENABLED !== "true"`. Dev / CI / tests: no-op. +- Hard cap: if there are already ≥ 40 synthetic items in the last 14 days (≈ 3/day × 14 rounded up), skip for that tick. Stops runaway growth if the retention job fails. +- BRouter call per generation: 1. Bot traffic is rounding-error compared to real user traffic. + +**Alternatives considered:** +- **Fixed cron every 4 hours** — boring, too regular, a demo visitor with sharp eyes notices. +- **Poisson process with mean 3/day** — more faithful but more code. The 90-minute-tick-with-probability scheme is close enough. +- **Walk at specific realistic times** (morning, lunch, evening) — adds temporal pattern. Probably worth revisiting once we see the feed in practice, but not worth coding up front. + +### Retention + +**Decision:** A second recurring job `demo-bot:prune` runs daily and deletes synthetic routes + activities whose `created_at` is older than `DEMO_BOT_RETENTION_DAYS` (default 14). Route-version rows cascade-delete via existing FK. + +**Why daily, not weekly:** smaller blast radius if the prune gets something wrong, and it keeps the feed visibly "recent" rather than stable. + +### Flagging synthetic content at the DB level + +**Decision:** Add `synthetic boolean NOT NULL DEFAULT false` to `journal.routes` and `journal.activities`. Set `true` only when the bot inserts. + +**Why:** makes the "delete all bot content" operation a one-liner and lets future listing code exclude synthetic if we decide to, without introspecting content shape or owner. `owner_id = demo_user_id` would almost work as a proxy, but the dedicated flag decouples identity from status — if we later delete and re-seed the demo user we don't lose the signal. + +### Env surface + +**Decision:** +- `DEMO_BOT_ENABLED`: `"true"` turns the generator + prune on; anything else is off. Absent means off. +- `DEMO_BOT_RETENTION_DAYS`: integer, defaults to 14. +- `DEMO_BOT_REGION`: JSON `{ "bbox": [w,s,e,n] }`, defaults to inner Berlin (`13.25,52.45,13.55,52.60`) to suit Bruno's park-walker persona. +- No secrets. The whole feature is public-facing by design. + +## Risks / Trade-offs + +- **BRouter outages halt the feed** → acceptable; the job logs and skips. The feed will stop refreshing but existing items remain visible. +- **Uncanny repetition** (same start neighbourhoods, template names) → mitigated by varying the start point randomly and the templated copy, but still acceptable for a demo. A reviewer will obviously figure out it's synthetic if they look — we're not hiding it. +- **Mistaking bot content for real content during analytics** → mitigated by the `synthetic` flag; analytics queries filter `WHERE synthetic = false` when they want real usage. +- **Runaway insert if retention breaks** → mitigated by the hard cap (50 items in last 14 days) inside the generator. +- **GDPR / privacy concerns** → none new: the bot has no real PII, its content is first-party, and `demo@trails.cool` is a reserved sentinel address. +- **Someone logs in as `demo`** → the user has no credentials (no passkey, no magic-token). Email sentinel means a magic-link request can't succeed either (no inbox). Safe. +- **Accidentally enabled in dev** → mitigated by the explicit env opt-in; default-off in every environment but prod. + +## Migration Plan + +1. Merge schema + code; `drizzle-kit push --force` adds `synthetic` columns. +2. Set `DEMO_BOT_ENABLED=true` on the prod Journal container; leave every other environment off. +3. On next worker restart, the bootstrap step inserts the `demo` user. +4. First generation run produces one route + activity. Verify at `/users/demo`. +5. After a few ticks, verify the feed looks plausible and the prune doesn't fire unexpectedly (it won't, nothing is 14 days old). + +**Rollback:** `DEMO_BOT_ENABLED=false` and redeploy. To wipe all generated content: `DELETE FROM journal.activities WHERE synthetic = true; DELETE FROM journal.routes WHERE synthetic = true;`. The `demo` user row can stay — it's cheap and keeps the URL stable if we re-enable later. + +## Open Questions + +- **Do we want the profile to also get a "synthetic content" badge** so honest readers (and us, on demos) can tell at a glance? A tiny "demo account" pill on `/users/demo` is cheap. Decide during implementation. +- **Should the bot post a few backfilled items on first enablement** so the feed isn't just one item for the first four hours? Probably yes — a small one-time bootstrap that generates 3–5 items immediately if the synthetic-item count is 0. Proposing it as a task. +- **Should BRouter calls be recorded as `brouter_request_duration_seconds` the same as user requests**? Probably — same histogram is fine; synthetic traffic is a small addition and it keeps ops alerts meaningful. diff --git a/openspec/changes/demo-activity-bot/proposal.md b/openspec/changes/demo-activity-bot/proposal.md new file mode 100644 index 0000000..bf6814d --- /dev/null +++ b/openspec/changes/demo-activity-bot/proposal.md @@ -0,0 +1,35 @@ +## Why + +To demo trails.cool to prospective users and contributors we need live-looking content on the public surface introduced by `public-content-visibility`. Today a demo link opens to an empty profile. Even after visibility ships, the Journal has 3 users and 0 activities — the feed shows "nothing happened today," which is the worst possible first impression. + +A synthetic "demo" user that autonomously produces plausible activities closes that gap. It also keeps pressure on the content-creation code paths: if the bot is wedged, the import / routing / geometry pipelines are probably broken for real users too. + +This change is the direct follow-up to `public-content-visibility` and is only useful once that lands. + +## What Changes + +- A dedicated bot user account (username e.g. `demo`) is bootstrapped on first run with a stable ID, a public display name, and `visibility` defaults that mark its content public. +- A recurring pg-boss job (the existing background-jobs infrastructure on the Journal host) runs every few hours, chooses a random start + end point within a configured seed region, asks BRouter for a route, persists the route + a derived activity attributed to the demo user with `visibility = 'public'`. +- Synthetic rows are explicitly flagged at the database level (`synthetic boolean NOT NULL DEFAULT false`) so a single DELETE can clean them up and listings can optionally exclude them later. +- A retention job trims synthetic activities older than a configurable window (default 14 days) so the feed looks fresh, not a swamp of old rides. +- Everything is gated behind a `DEMO_BOT_ENABLED` env flag. Local dev, CI, and tests default to disabled. The flag is set on prod only. +- Route profiles vary: trekking and fastbike, with plausible distance ranges for each. Start times of day look reasonable. Names and descriptions draw from a small templated copy set (in both EN and DE). + +## Capabilities + +### New Capabilities +- `demo-activity-bot`: A bot user, a scheduler that seeds plausible public routes + activities using BRouter and a seed region, and a retention job to keep the feed bounded. + +### Modified Capabilities +- `route-management`: adds a `synthetic` flag alongside the `visibility` work from `public-content-visibility`, so listings and exports can distinguish bot content if they ever need to. +- `activity-feed`: same `synthetic` flag for symmetry. + +## Impact + +- **Code**: new `apps/journal/app/jobs/demo-bot.ts` for the job handlers, small helpers for picking seed coordinates and templating names, a one-time bootstrap that inserts the demo user if missing. +- **Data**: a schema change (the `synthetic` column on two tables) plus ongoing inserts into those same tables. Bounded by the retention job. +- **Infrastructure**: no new services — pg-boss is already in the stack. `DEMO_BOT_ENABLED` is a new env var on the prod Journal container. +- **External calls**: BRouter calls from the bot; throttled at the scheduler level so the bot never competes with real user traffic. No external API beyond BRouter. +- **Privacy**: the bot user has no real email, no PII, and its content is clearly author-attributed to `demo`. The legal / privacy pages do not need to change — this is first-party content the operator controls. +- **Non-goals (explicit)**: realistic social signals (no likes/comments on demo content), multi-user bot personas (one user for v1), cross-region variety (one seed region), multi-day tours, photos or media attachments. +- **Rollback**: flip `DEMO_BOT_ENABLED=false` — the job stops. A single `DELETE FROM ... WHERE synthetic = true` removes all bot content without touching real data. diff --git a/openspec/changes/demo-activity-bot/specs/activity-feed/spec.md b/openspec/changes/demo-activity-bot/specs/activity-feed/spec.md new file mode 100644 index 0000000..a2ec420 --- /dev/null +++ b/openspec/changes/demo-activity-bot/specs/activity-feed/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Synthetic activity flag +The Journal SHALL persist a `synthetic` boolean on every activity so automated / demo content can be distinguished from user-created content. + +#### Scenario: User-created activities default to non-synthetic +- **WHEN** an activity is created through any user-facing flow (GPX upload, sync import, Planner handoff) +- **THEN** the activity row is persisted with `synthetic = false` + +#### Scenario: Bot inserts flag their rows as synthetic +- **WHEN** the demo-activity-bot inserts an activity +- **THEN** the row is persisted with `synthetic = true` + +#### Scenario: Synthetic flag is not user-editable +- **WHEN** an activity owner edits the activity via any user-facing action +- **THEN** the stored `synthetic` value is not changed by the edit diff --git a/openspec/changes/demo-activity-bot/specs/demo-activity-bot/spec.md b/openspec/changes/demo-activity-bot/specs/demo-activity-bot/spec.md new file mode 100644 index 0000000..169c7ca --- /dev/null +++ b/openspec/changes/demo-activity-bot/specs/demo-activity-bot/spec.md @@ -0,0 +1,77 @@ +## ADDED Requirements + +### Requirement: Demo user bootstrap +The Journal SHALL ensure a dedicated bot user exists when the demo bot starts, creating it on first run if missing. + +#### Scenario: Bot user created on first run +- **WHEN** the Journal worker starts with `DEMO_BOT_ENABLED=true` and no `users` row matches the reserved demo username +- **THEN** a new `users` row is inserted with the reserved username, a public-facing display name, a sentinel email (`demo@`), no passkey credentials, and `terms_accepted_at` + `terms_version` populated at the current version +- **AND** subsequent worker startups are idempotent — no second row is inserted + +#### Scenario: Demo user has no usable credentials +- **WHEN** any request attempts to authenticate as the demo user via passkey or magic-link +- **THEN** authentication fails because no passkey is registered and no mailbox receives magic-link mails + +### Requirement: Synthetic content generation job +The Journal SHALL run a recurring background job that generates one public route and one linked public activity for the demo user per run, subject to an env flag and a rate cap. + +#### Scenario: Disabled in non-production environments +- **WHEN** the `DEMO_BOT_ENABLED` env var is absent or any value other than `"true"` +- **THEN** the job body is a no-op: no BRouter calls, no inserts, no errors + +#### Scenario: Enabled generation flow (decide-to-walk fires) +- **WHEN** `DEMO_BOT_ENABLED=true`, the local hour is within 07:00–21:00, the per-tick Bernoulli roll fires, and the hard cap has not been reached +- **THEN** the job picks a random start and end point within the configured seed region, calls BRouter with the `trekking` profile, persists the returned GPX as a new route with `visibility='public'` and `synthetic=true`, and inserts a linked activity with the same GPX, `visibility='public'`, `synthetic=true`, a plausible `started_at` and `duration`, and a templated Bruno-voiced name/description +- **AND** the route and activity are attributed to the demo user + +#### Scenario: Decide-to-walk does not fire +- **WHEN** the local hour is outside 07:00–21:00, or the Bernoulli roll does not fire +- **THEN** the job returns without inserting anything — Bruno just isn't walking right now + +#### Scenario: BRouter failure is tolerated +- **WHEN** the BRouter call returns no route, a rate-limit, or an error +- **THEN** the job logs the failure, inserts nothing, and exits without throwing — the next scheduled tick retries + +#### Scenario: Hard cap prevents runaway growth +- **WHEN** there are already 40 or more synthetic items created in the last 14 days +- **THEN** the job skips generation for that tick + +#### Scenario: Singleton scheduling prevents overlap +- **WHEN** a tick fires while the previous run is still executing +- **THEN** the new tick is skipped (pg-boss singleton semantics) so the job cannot overlap itself + +### Requirement: Synthetic content retention +The Journal SHALL run a recurring job that deletes synthetic routes and activities older than a configurable window. + +#### Scenario: Prune removes old synthetic content +- **WHEN** the prune job runs with `DEMO_BOT_RETENTION_DAYS=14` +- **THEN** every row in `journal.routes` and `journal.activities` with `synthetic=true` and `created_at < now() - 14 days` is deleted +- **AND** route-version rows cascade-delete via existing foreign keys +- **AND** rows with `synthetic=false` are never touched + +#### Scenario: Prune is a no-op when nothing is old +- **WHEN** the prune job runs and no synthetic rows exceed the retention window +- **THEN** no DELETE statements execute and the job returns normally + +#### Scenario: Disabled in non-production environments +- **WHEN** `DEMO_BOT_ENABLED` is not `"true"` +- **THEN** the prune job body is a no-op + +### Requirement: Initial backfill +On first enablement (when no synthetic content exists yet) the Journal SHALL populate the demo profile with a small batch of items so the first visitor does not see a single-item feed. + +#### Scenario: First enablement backfills several items +- **WHEN** the bot is enabled for the first time and the count of synthetic routes is 0 +- **THEN** the generation job produces 3–5 items in sequence during its first run +- **AND** subsequent runs produce one item at a time as normal + +### Requirement: Seed region is configurable +The Journal SHALL read the seed region (bounding box) from an env var so the deployment can change it without a code change. + +#### Scenario: Env-configured region +- **WHEN** `DEMO_BOT_REGION` is set to a JSON object containing a `bbox` array of four numbers `[west, south, east, north]` +- **THEN** all generated start and end points fall within that box + +#### Scenario: Sensible default +- **WHEN** `DEMO_BOT_REGION` is unset +- **THEN** the job uses a documented default region (inner Berlin) so that out-of-the-box runs still produce plausible Bruno-style walks diff --git a/openspec/changes/demo-activity-bot/specs/route-management/spec.md b/openspec/changes/demo-activity-bot/specs/route-management/spec.md new file mode 100644 index 0000000..a61f717 --- /dev/null +++ b/openspec/changes/demo-activity-bot/specs/route-management/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Synthetic route flag +The Journal SHALL persist a `synthetic` boolean on every route so automated / demo content can be distinguished from user-created content. + +#### Scenario: User-created routes default to non-synthetic +- **WHEN** a route is created through any user-facing flow (New Route, GPX import, Planner handoff) +- **THEN** the route row is persisted with `synthetic = false` + +#### Scenario: Bot inserts flag their rows as synthetic +- **WHEN** the demo-activity-bot inserts a route +- **THEN** the row is persisted with `synthetic = true` + +#### Scenario: Synthetic flag is not user-editable +- **WHEN** a route owner edits a route via any user-facing action +- **THEN** the stored `synthetic` value is not changed by the edit diff --git a/openspec/changes/demo-activity-bot/tasks.md b/openspec/changes/demo-activity-bot/tasks.md new file mode 100644 index 0000000..f8170a8 --- /dev/null +++ b/openspec/changes/demo-activity-bot/tasks.md @@ -0,0 +1,72 @@ +## 1. Schema + +- [ ] 1.1 Add `synthetic boolean NOT NULL DEFAULT false` to `journal.routes` in `packages/db/src/schema/journal.ts` +- [ ] 1.2 Add the same column to `journal.activities` +- [ ] 1.3 Verify existing CRUD helpers (`createRoute`, `updateRoute`, `createActivity`, `listRoutes`, `listActivities`) compile and ignore the new column for default callers + +## 2. Bruno bootstrap + +- [ ] 2.1 Reserved username: `bruno`. Sentinel email: `bruno@`. Display name: `Bruno`. Bio: a short whimsical line (finalise exact wording during apply — e.g. "Professional park inspector. Currently accepting tennis balls."). +- [ ] 2.2 Add an `ensureDemoUser()` helper in `apps/journal/app/lib/demo-bot.server.ts` that inserts the `bruno` row only if missing (idempotent via `ON CONFLICT DO NOTHING` on `username`), with `terms_accepted_at` and `terms_version` populated. +- [ ] 2.3 Call `ensureDemoUser()` from the worker startup sequence when `DEMO_BOT_ENABLED === "true"`. +- [ ] 2.4 Confirm Bruno has no credentials row; the passkey and magic-link login paths both fail for his email (no mailbox exists for `bruno@`). + +## 3. Region + generation helpers + +- [ ] 3.1 Add `loadRegion()` that reads `DEMO_BOT_REGION` JSON (with `bbox: [w,s,e,n]`) and falls back to the inner-Berlin default `[13.25, 52.45, 13.55, 52.60]` +- [ ] 3.2 Add `pickEndpoints(bbox)` — random start + end, 2–12 km crow distance apart (dog-walk scale) +- [ ] 3.3 Profile is fixed to `trekking` (Bruno doesn't ride bikes); no `pickProfile()` needed for v1 +- [ ] 3.4 Add `templateName(startedAt)` + `templateDescription()` — EN + DE Bruno-voiced copy, mixing serious-audit flavour ("Grunewald north-loop patrol") and comic ("Bruno found three sticks today 🐕"); 10–15 entries in each pool, picked deterministically from the day + started-at to avoid same-day repeats + +## 4. BRouter client for the bot + +- [ ] 4.1 Reuse the existing `computeRoute` helper where possible; otherwise add a minimal `brouter-client.server.ts` that POSTs to `process.env.BROUTER_URL` and returns parsed GPX + stats +- [ ] 4.2 On no-route / 5xx / timeout, return a typed "no route" error — the job handles it, does not throw out of the worker + +## 5. Generation job + +- [ ] 5.1 Register a pg-boss recurring job `demo-bot:generate` to fire every 90 minutes, singleton mode +- [ ] 5.2 Handler: skip immediately if `DEMO_BOT_ENABLED !== "true"` +- [ ] 5.3 Decide-to-walk gate: compute local hour; if outside 07:00–21:00 → skip. Otherwise roll a Bernoulli with p=0.12 and skip if it doesn't fire. Expected output: ~2–3 walks/day +- [ ] 5.4 Hard cap: `SELECT count(*) FROM routes WHERE synthetic AND created_at > now() - interval '14 days'`; skip if >= 40 +- [ ] 5.5 Pick region + endpoints (profile is fixed to `trekking`); call BRouter; on failure log and return +- [ ] 5.6 Insert route with `visibility='public'`, `synthetic=true`, owner = Bruno; insert linked activity with derived `started_at` = now, `duration` = distance ÷ ~4.5 km/h ± jitter, stats, and the same GPX + +## 6. Initial backfill + +- [ ] 6.1 At the top of the generation handler, check if `count(synthetic routes) == 0`; if so, loop up to 5 times running the full generation body sequentially (each call independent — if one fails, keep going) +- [ ] 6.2 After the backfill path, fall through to the normal single-item generation + +## 7. Retention job + +- [ ] 7.1 Register a pg-boss recurring job `demo-bot:prune` with a cron like `15 3 * * *` (daily at 03:15 UTC), singleton +- [ ] 7.2 Handler: skip if `DEMO_BOT_ENABLED !== "true"` +- [ ] 7.3 Read `DEMO_BOT_RETENTION_DAYS` with default 14 +- [ ] 7.4 `DELETE FROM journal.activities WHERE synthetic AND created_at < now() - interval ?`; same for routes +- [ ] 7.5 Log the count removed for observability + +## 8. Ops + env surface + +- [ ] 8.1 Document `DEMO_BOT_ENABLED`, `DEMO_BOT_RETENTION_DAYS`, `DEMO_BOT_REGION` in `infrastructure/secrets.app.env`'s commented template (do not enable in any environment file except prod) +- [ ] 8.2 Set `DEMO_BOT_ENABLED=true` only in prod +- [ ] 8.3 Expose counts via a Prometheus gauge (e.g. `demo_bot_synthetic_routes_total`, `demo_bot_synthetic_activities_total`) and reuse the existing `brouter_request_duration_seconds` histogram for the bot's BRouter calls — no new metric plumbing needed + +## 9. UX tweaks + +- [ ] 9.1 "🐕 demo account" badge on `/users/bruno` so honest readers can tell at a glance; gate on `user.username === 'bruno'` +- [ ] 9.2 i18n: `demo.badge` key in EN + DE (e.g. "Demo account" / "Demo-Konto") + +## 10. Tests + +- [ ] 10.1 Unit: `ensureDemoUser` is idempotent; second call is a no-op and does not duplicate +- [ ] 10.2 Unit: `pickEndpoints` stays within bbox; distance bands match profile +- [ ] 10.3 Unit: `templateName` / `templateDescription` return non-empty strings in both locales +- [ ] 10.4 Integration (tests DB): the generation handler inserts one route + one activity with `synthetic=true, visibility='public'` when enabled, and inserts nothing when disabled +- [ ] 10.5 Integration: the prune handler deletes only `synthetic=true` rows past the window; real rows are untouched + +## 11. Rollout + +- [ ] 11.1 Merge schema + code; deploy — the bot stays disabled everywhere because no env flag is set +- [ ] 11.2 Flip `DEMO_BOT_ENABLED=true` on prod via the SOPS env file + redeploy +- [ ] 11.3 On next worker start: verify `ensureDemoUser` created the `demo` user, the backfill produced 3–5 items, and `/users/demo` renders them publicly +- [ ] 11.4 After 24 h: verify cadence looks right and the prune job ran without deleting anything yet diff --git a/openspec/changes/public-content-visibility/.openspec.yaml b/openspec/changes/public-content-visibility/.openspec.yaml new file mode 100644 index 0000000..c8af3f5 --- /dev/null +++ b/openspec/changes/public-content-visibility/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-19 diff --git a/openspec/changes/public-content-visibility/design.md b/openspec/changes/public-content-visibility/design.md new file mode 100644 index 0000000..390df32 --- /dev/null +++ b/openspec/changes/public-content-visibility/design.md @@ -0,0 +1,111 @@ +## Context + +The Journal uses a straightforward "logged-in or you're not seeing anything" access model today. Routes and activities are owned by a single user via `owner_id` foreign keys, and every detail-page loader calls `getSessionUser(request)` then either serves the page or (implicitly) returns the "route not found" error. There is no notion of cross-user visibility. + +The Planner is separately anonymous, so that's not a concern here — this change is Journal-only. + +Two near-term pressures shape the design: + +- **The demo plan** (send a URL to a prospective user or contributor and have them see real content without signing up). Anything that requires a friction step on arrival defeats the demo. +- **Upcoming `demo-activity-bot`** that generates synthetic activities. That content has to be publicly viewable or the bot is pointless. + +What this design deliberately *does not* touch: +- Followers / subscriptions / per-user feeds +- Reactions / comments / any write surface for non-owners +- ActivityPub / Fedify / federation +- Per-segment privacy on a single route + +Those are all future chapters. Keeping the first step narrow means less to get wrong and less to re-design later. + +## Goals / Non-Goals + +**Goals:** +- A route or activity owner can mark a piece of content as public. +- Logged-out visitors can open that content at its permanent URL. +- A logged-out visitor can find the rest of that user's public content via `/users/:username`. +- Sharing a public URL on Slack / Twitter / Bluesky / email produces a decent preview. +- Default stays private — nothing already in the database becomes visible just because this change ships. + +**Non-Goals:** +- Discovery (there is no "browse public routes" page on the instance yet). +- Indexing control beyond the default (no per-route `robots` override). +- Changing the Planner's anonymous model. +- Any write access for non-owners on public content. + +## Decisions + +### Visibility model: three values, not two + +**Decision:** `visibility` enum `'private' | 'unlisted' | 'public'`. Stored as a text column for simplicity; can be migrated to a native enum later if worth it. + +- `private` (default) — only the owner can fetch the detail page; listings never show it. +- `unlisted` — anyone with the URL can view; excluded from the owner's public profile and any future discovery pages. +- `public` — anyone can view; appears on the owner's public profile. + +**Alternatives:** +- **Just `private | public`** — simpler, but kills the useful "I want to share with someone without putting it on my profile" case. Every other sharing-oriented service has an unlisted tier; it's cheap to add now and irritating to retrofit later. +- **Sharing via time-limited tokens** (Google-Docs-style) — more powerful but out of scope for the demo goal. Parked. + +### Default is `private` for all existing rows + +**Decision:** The new column ships with `DEFAULT 'private'` and every existing row — two real routes and zero activities — remains private. Users opt in to publication by explicitly changing the value. + +**Why:** This change cannot silently un-privatise data anyone uploaded under the old rules. That principle outweighs the demo inconvenience (we'll mark the demo user's seeded content public at insert time). + +### Access check lives in route loaders + +**Decision:** Each detail-page loader (`routes.$id.tsx`, `activities.$id.tsx`) resolves the content row, compares `visibility` + `owner_id` against the session user: + +- `visibility === 'public'` → serve. +- `visibility === 'unlisted'` AND the request is a direct detail page URL → serve. +- otherwise → serve only if the requester is the owner, else 404 (not 403 — leaking existence is a privacy bug). + +A small helper `canView(content, user)` in `~/lib/auth.server` centralises the rule so list endpoints use the same logic. + +**Alternatives:** +- **Route-level middleware** (before loaders) — cleaner in theory but React Router 7 loaders are the right place for content-specific auth, and centralising via a helper avoids coupling the router tree to visibility semantics. + +### Public profile page reuses the existing `/users/:username` route + +**Decision:** That route exists today but is auth-gated (and renders the current user's own routes/activities). Broaden it: + +- Publicly accessible. +- Shows public routes + public activities of the requested username, most recent first. +- 404 if the user has no public content at all. This hides the existence of private-only accounts; an attacker can't enumerate accounts by username. +- A "This is your profile" control strip visible only to the logged-in owner, with a quick link to settings. + +### Open Graph / Twitter Card meta tags + +**Decision:** Each public route / activity detail page emits OG tags via React Router's `meta` export: + +- `og:title` — route or activity name + "· trails.cool" +- `og:description` — user description (truncated) or a sensible default +- `og:type` — `"article"` +- `og:site_name` — `"trails.cool"` +- `twitter:card` — `"summary"` (summary, not summary_large_image; we don't have social cards yet) + +A future `social-preview-images` follow-up can add rendered static map PNGs. Explicitly out of scope here. + +### `robots` control + +**Decision:** Public route / activity pages emit no `robots` meta (defaults to indexable). The legal pages keep their existing `noindex`. No sitemap is generated; discovery via search is passive. + +## Risks / Trade-offs + +- **Username enumeration via profile 404** → Mitigation: 404 both for "no such user" and "user exists but has no public content", so the two are indistinguishable. Timing-side-channel on the DB lookup is not defended against in v1; acceptable at this scale. +- **Future listing pages will want more data** → The `canView` helper already supports it. Adding an `index` boolean or "discoverable" flag is additive. +- **`unlisted` is only private-ish** → If the URL leaks it's effectively public. That's the Internet; same as every other unlisted-sharing feature. Documented in the settings UI copy. +- **Content previously private becomes linkable** → Once a user makes a route public and shares it, they can't fully retract — archives exist. Same as any web publish. No new warning for v1; the visibility selector itself is unambiguous. +- **Spec drift risk** → `route-management` and `activity-feed` both gain modified requirements; keep the delta specs tight so the archive survives review. + +## Migration Plan + +1. Merge schema change; `drizzle-kit push --force` on deploy adds the column with default `'private'`. +2. Logged-out access to public pages is a new code path — nothing existing regresses since all rows remain `'private'` until a user changes them. +3. `demo-activity-bot` is the first caller that will create rows with `visibility: 'public'` at insert time. +4. Rollback: `UPDATE routes SET visibility = 'private'; UPDATE activities SET visibility = 'private';` restores the prior behaviour without any code change; the public code path becomes dead but harmless. + +## Open Questions + +- Should the settings page add a default-visibility preference per user (e.g. "make new routes public by default")? Probably nice but not in this spec; revisit after observing real usage. +- Do we want to emit `` on unlisted pages to discourage indexing of the URL if it leaks? Low-cost, worth considering during implementation. diff --git a/openspec/changes/public-content-visibility/proposal.md b/openspec/changes/public-content-visibility/proposal.md new file mode 100644 index 0000000..b2996e9 --- /dev/null +++ b/openspec/changes/public-content-visibility/proposal.md @@ -0,0 +1,37 @@ +## Why + +trails.cool currently has no way to show its content to anyone who isn't logged in. Route and activity detail pages require auth, there is no public-facing profile page, and shared URLs have no Open Graph metadata — so a link pasted in Slack or on a social platform looks like a blank trails.cool card. + +Two immediate reasons to fix this: + +1. **Demos + acquisition.** The next phase of the project is onboarding more users and contributors. The pitch lands better when you can send a URL that opens directly to "look at this route / this weekend's ride" without making the visitor register first. +2. **Prerequisite for any `demo-activity-bot` work.** A synthetic-activity generator is pointless if the generated content isn't publicly viewable. This change unblocks that follow-up. + +This is also the smallest possible step into the "social" direction the Journal was always described as heading for. It does not introduce follow/follower, cross-user feeds, reactions, or ActivityPub — those remain future work. + +## What Changes + +- New `visibility` column on routes and activities with values `private` (default for existing rows), `unlisted` (reachable only by direct URL, excluded from listings), `public` (visible everywhere). +- Logged-out visitors can view **public** route and activity detail pages. Private / nonexistent routes return 404, just like logged-in requests to other users' private content. Unlisted renders for anyone with the URL but does not appear in listings. +- New public profile page at `/users/:username` that lists that user's **public** routes and activities. Returns 404 if the user has no public content (keeps the existence of private-only accounts itself private). +- Route detail page gains a visibility selector for owners (the existing edit page is the natural home). +- Open Graph / Twitter Card meta tags on public route and activity detail pages so shared URLs preview nicely (title, description, a small route preview image for future, the instance name as site). +- **BREAKING for spec-readers only**: several existing requirements in `route-management` and `activity-feed` are modified to reflect the new "auth-or-public" access rule. The default in migration is `private`, so **behaviour for existing users does not change** — their routes stay inaccessible to logged-out visitors until they explicitly make one public. + +## Capabilities + +### New Capabilities +- `public-profiles`: Public-facing user pages at `/users/:username` listing a user's public routes and activities, with nothing shown for users who have no public content. + +### Modified Capabilities +- `route-management`: adds visibility field + modified access rules so public routes are viewable without auth; owners can change visibility. +- `activity-feed`: adds visibility field; public activities render to logged-out visitors. + +## Impact + +- **Code**: schema (`visibility` column on `routes` + `activities`), loader auth changes on `routes.$id.tsx` / `activities.$id.tsx`, new route `users.$username.tsx` (already exists but is auth-gated today), a visibility selector somewhere in the route edit flow, a `meta` export on public detail pages for OG tags. +- **Data**: default `visibility = private` for all existing rows — three users, zero activities, two empty routes — so migration is effectively a no-op for behaviour. No backfill needed. +- **Privacy**: this change explicitly reduces the default privacy posture *only if a user opts in by marking content public*. A short sentence in `/legal/privacy` notes public content is world-visible. No new third-party surface. +- **Search engines**: public pages are not actively promoted (no sitemap). `robots: noindex` stays on legal pages and settings; `routes` and `activities` public pages get a permissive default (search-indexable) so demo URLs work well. +- **Non-goals (explicit)**: follow/follower, a cross-user feed, reactions/comments, federation, route privacy per-section. Keeping scope tight. +- **Rollback**: flipping the default back to `private` everywhere is a single UPDATE. Pages gating on visibility degrade to "auth-only" if we remove the public path. diff --git a/openspec/changes/public-content-visibility/specs/activity-feed/spec.md b/openspec/changes/public-content-visibility/specs/activity-feed/spec.md new file mode 100644 index 0000000..b0cffab --- /dev/null +++ b/openspec/changes/public-content-visibility/specs/activity-feed/spec.md @@ -0,0 +1,48 @@ +## MODIFIED Requirements + +### Requirement: Activity detail page +The Journal SHALL display an activity detail page with map, stats, and description. Access depends on the activity's `visibility`: `public` activities are viewable by anyone including unauthenticated visitors, `unlisted` activities are viewable by anyone who has the URL, and `private` activities are viewable only by the owner. + +#### Scenario: Owner views own activity +- **WHEN** a logged-in user navigates to an activity they own at any visibility +- **THEN** they see the activity name, description, a map with the GPS trace, distance, duration, and elevation stats + +#### Scenario: Anyone views a public activity +- **WHEN** any visitor (including unauthenticated) navigates to a `public` activity's URL +- **THEN** they see the full activity detail page as above + +#### Scenario: Anyone with the URL views an unlisted activity +- **WHEN** any visitor navigates directly to an `unlisted` activity's URL +- **THEN** they see the full activity detail page as above + +#### Scenario: Non-owner is blocked from a private activity +- **WHEN** a visitor who is not the owner requests a `private` activity URL +- **THEN** the server responds with HTTP 404 (not 403), so the existence of the private activity is not leaked + +#### Scenario: Public and unlisted activity pages emit social-share metadata +- **WHEN** a visitor loads a `public` or `unlisted` activity detail page +- **THEN** the response emits Open Graph and Twitter Card meta tags (`og:title`, `og:description`, `og:type="article"`, `og:site_name`, `twitter:card="summary"`) + +## ADDED Requirements + +### Requirement: Activity visibility +The Journal SHALL persist a `visibility` value on every activity and SHALL allow the owner to change it. + +#### Scenario: New activities default to private +- **WHEN** an activity is created without an explicit visibility +- **THEN** the activity row is persisted with `visibility = 'private'` + +#### Scenario: Owner changes an activity's visibility +- **WHEN** an activity owner selects a different visibility (`private`, `unlisted`, `public`) and saves +- **THEN** the stored visibility is updated and subsequent access checks use the new value immediately + +### Requirement: Activity listings respect visibility +The Journal's own-activities feed SHALL show the owner everything regardless of visibility, while any cross-user listing SHALL only include activities with `visibility = 'public'`. + +#### Scenario: Own activity feed is unchanged +- **WHEN** a logged-in user views their own activity feed +- **THEN** the feed includes all of their own activities regardless of visibility + +#### Scenario: Public profile lists only public activities +- **WHEN** a visitor loads `/users/:username` +- **THEN** the rendered list of activities includes only the user's `public` activities; `unlisted` and `private` activities are omitted diff --git a/openspec/changes/public-content-visibility/specs/public-profiles/spec.md b/openspec/changes/public-content-visibility/specs/public-profiles/spec.md new file mode 100644 index 0000000..e2f4cd0 --- /dev/null +++ b/openspec/changes/public-content-visibility/specs/public-profiles/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Public profile page +The Journal SHALL serve a public profile page at `/users/:username` that lists the user's public routes and activities in reverse chronological order, viewable without authentication. + +#### Scenario: Logged-out visitor views a profile with public content +- **WHEN** an unauthenticated visitor navigates to `/users/:username` for a user with at least one `public` route or activity +- **THEN** the page renders that user's display name (falling back to username), the `@username@domain` handle, and a reverse-chronological list of their `public` routes and `public` activities +- **AND** items marked `unlisted` or `private` do NOT appear in the list + +#### Scenario: Profile 404 when there is no public content +- **WHEN** a visitor navigates to `/users/:username` for a user whose content is all `private` or `unlisted`, or for a username that does not exist +- **THEN** the server responds with HTTP 404 +- **AND** the response does NOT distinguish the two cases, so existence of a private-only account is not leaked + +#### Scenario: Owner sees their own profile +- **WHEN** a user navigates to their own `/users/:username` while logged in +- **THEN** the page renders exactly the same as for a logged-out visitor, plus a small owner-only control strip linking to settings + +#### Scenario: Profile page emits social-share metadata +- **WHEN** any visitor loads a populated `/users/:username` +- **THEN** the page emits Open Graph tags (`og:title`, `og:site_name`, `og:type="profile"`) so links shared on social platforms render a meaningful preview diff --git a/openspec/changes/public-content-visibility/specs/route-management/spec.md b/openspec/changes/public-content-visibility/specs/route-management/spec.md new file mode 100644 index 0000000..fe804d0 --- /dev/null +++ b/openspec/changes/public-content-visibility/specs/route-management/spec.md @@ -0,0 +1,52 @@ +## MODIFIED Requirements + +### Requirement: View route +The Journal SHALL display route details including map, metadata, and elevation stats. Access depends on the route's `visibility`: `public` routes are viewable by anyone including unauthenticated visitors, `unlisted` routes are viewable by anyone who has the URL, and `private` routes are viewable only by the owner. + +#### Scenario: Owner views own route +- **WHEN** a logged-in user navigates to a route they own at any visibility +- **THEN** they see the route name, description, a map with the route polyline, distance, and elevation gain/loss + +#### Scenario: Anyone views a public route +- **WHEN** any visitor (including unauthenticated) navigates to a `public` route's URL +- **THEN** they see the full route detail page as above + +#### Scenario: Anyone with the URL views an unlisted route +- **WHEN** any visitor navigates directly to an `unlisted` route's URL +- **THEN** they see the full route detail page as above + +#### Scenario: Non-owner is blocked from a private route +- **WHEN** a visitor who is not the owner requests a `private` route URL +- **THEN** the server responds with HTTP 404 (not 403), so the existence of the private route is not leaked + +#### Scenario: Public and unlisted route pages emit social-share metadata +- **WHEN** a visitor loads a `public` or `unlisted` route detail page +- **THEN** the response emits Open Graph and Twitter Card meta tags (`og:title`, `og:description`, `og:type="article"`, `og:site_name`, `twitter:card="summary"`) + +## ADDED Requirements + +### Requirement: Route visibility +The Journal SHALL persist a `visibility` value on every route and SHALL allow the owner to change it. + +#### Scenario: New routes default to private +- **WHEN** a route is created without an explicit visibility +- **THEN** the route row is persisted with `visibility = 'private'` + +#### Scenario: Owner changes a route's visibility +- **WHEN** a route owner selects a different visibility (`private`, `unlisted`, `public`) in the edit flow and saves +- **THEN** the stored visibility is updated and subsequent access checks use the new value immediately + +#### Scenario: Non-owner cannot change visibility +- **WHEN** a request to update visibility arrives from a user who is not the route owner +- **THEN** the server rejects it with HTTP 403 or 404 (matching the current update-route behaviour), and the stored value is unchanged + +### Requirement: Route listings respect visibility +Any listing that exposes routes beyond the owner's own dashboard SHALL only include routes with `visibility = 'public'`. + +#### Scenario: Public profile lists only public routes +- **WHEN** a visitor loads `/users/:username` +- **THEN** the rendered list of routes includes only the user's `public` routes; `unlisted` and `private` routes are omitted + +#### Scenario: Owner's own routes list is unchanged +- **WHEN** a logged-in user views their own routes list at `/routes` +- **THEN** the list includes all of their own routes regardless of visibility diff --git a/openspec/changes/public-content-visibility/tasks.md b/openspec/changes/public-content-visibility/tasks.md new file mode 100644 index 0000000..4196ff5 --- /dev/null +++ b/openspec/changes/public-content-visibility/tasks.md @@ -0,0 +1,62 @@ +## 1. Schema + +- [ ] 1.1 Add `visibility text NOT NULL DEFAULT 'private'` to `journal.routes` in `packages/db/src/schema/journal.ts` +- [ ] 1.2 Add the same column to `journal.activities` in the same file +- [ ] 1.3 Export a shared type `type Visibility = 'private' | 'unlisted' | 'public'` from `packages/db/src/schema/journal.ts` (or a small adjacent module) and reuse at the app layer + +## 2. Server-side access helper + +- [ ] 2.1 Add `canView(content, user)` in `apps/journal/app/lib/auth.server.ts` that returns `true` for `public`, `true` for `unlisted` (the direct-URL case — callers pass `true` when routed to a detail page, `false` when generating listings), and ownership-checked otherwise +- [ ] 2.2 Unit test the three matrix cells + +## 3. Route detail access + +- [ ] 3.1 Update `apps/journal/app/routes/routes.$id.tsx` loader: fetch route, then apply `canView`; return 404 when not allowed +- [ ] 3.2 Expose `visibility` on the loader's returned shape so the component can render the current-visibility badge to the owner +- [ ] 3.3 Emit Open Graph / Twitter Card `meta` for `public` and `unlisted` routes (title, description, `og:type="article"`, `og:site_name="trails.cool"`, `twitter:card="summary"`) + +## 4. Activity detail access + +- [ ] 4.1 Mirror 3.1 in `apps/journal/app/routes/activities.$id.tsx` +- [ ] 4.2 Mirror 3.3 for activities + +## 5. Visibility selector in the edit flow + +- [ ] 5.1 Add a visibility `