Files
worldwideview/AGENTS.md
Silvertakana a7d96f208f feat: Phase 2 install auth gate (ADR-003 closeout) (#192)
* fix(e2e): guard marketplace webServer and exclude per-app tests from main Playwright config

Root cause: playwright.config.ts unconditionally started the marketplace dev server at
../worldwideview-marketplace. In CI only worldwideview is checked out, so spawn() received
a non-existent cwd which Node.js surfaces as "spawn /bin/sh ENOENT", crashing the entire
test run before any browser launched.

Two targeted fixes:
1. Wrap the marketplace webServer entry in fs.existsSync(MARKETPLACE_DIR) so CI skips it
   gracefully. Use playwright.marketplace.config.ts to run cross-app marketplace tests locally.
2. Add testIgnore for web-auth.spec.ts and marketplace-from-instance.spec.ts — both target
   sibling repos (worldwideview-web / worldwideview-marketplace) and have their own dedicated
   configs (playwright.web.config.ts / playwright.marketplace.config.ts). The main config
   should only exercise the worldwideview app itself.

* feat(09-02): add playwright.cross-app.config.ts and .env.test for cross-origin specs

- Add playwright.cross-app.config.ts with dual webServer array (wwv.local:3001 + marketplace.wwv.local:3002)
- testMatch targets both upcoming cross-app spec files; baseURL set to marketplace.wwv.local:3002
- Create worldwideview/.env.test with PLAYWRIGHT_TEST_EMAIL + PLAYWRIGHT_TEST_PASSWORD (gitignored)
- Add explicit .env.test entry to .gitignore (was not covered by existing .env/.env.local patterns)
- Bump version 2.20.2 -> 2.21.0 (feat: minor)

* feat(09-02): add cross-app Playwright specs for redirect handshake and sign-out (REQ-16)

- Add marketplace-redirect-handshake.spec.ts: 2 tests verifying next= param construction and login-then-redirect-back flow
- Add marketplace-sign-out.spec.ts: 1 test verifying avatar dropdown sign-out clears session and returns to marketplace home
- Update playwright.cross-app.config.ts to load .env.test credentials via fs (no dotenv package required)
- All specs target https://marketplace.wwv.local:3002 (never localhost:3002) for correct .wwv.local cookie domain
- 3 tests total listed by playwright --list

* feat: add planning-sync hook script for .planning branch isolation

* fix: guard planning-sync against missing .planning, wrong repo, and silent checkout failures

- Exit early if .planning/.git doesn't exist (avoids false-success on machines without the private repo)
- Exit early if CWD is not a worldwideview repo or worktree (prevents syncing from wwv-data-engine etc.)
- Wrap both checkout calls in exit-code checks so failures emit WARNING messages instead of false success

* feat: add post-checkout hook for .planning auto-sync

* fix: add existence guard to post-checkout hook before calling planning-sync

* docs: add .planning branch convention to worktree-bootstrap skill

* feat(11-01): add LegalFooter component and .legal-footer CSS class

- Create src/components/layout/LegalFooter.tsx as a Server Component
- Export named function LegalFooter with two external anchors
- Both anchors use target="_blank" rel="noopener noreferrer" (T-11-01)
- Links target locked URLs: privacy-policy and cloud-terms-of-service
- Append .legal-footer + a + a:hover rules to globals.css
- position:fixed bottom:0 z-index:10 per UI-SPEC
- Bump version 2.23.2 -> 2.23.3

* feat(11-01): remove Vercel Analytics, mount LegalFooter in root layout

- Remove @vercel/analytics/next import from layout.tsx (D-02)
- Remove {process.env.VERCEL && <Analytics />} JSX (D-02, T-11-02)
- Add import { LegalFooter } from @/components/layout/LegalFooter
- Render <LegalFooter /> as last child of <body> (D-04)
- Remove @vercel/analytics from dependencies in package.json
- Regenerate pnpm-lock.yaml after dependency removal
- AdSense block (lines 27-37) untouched per D-03
- Bump version 2.23.3 -> 2.23.4

* fix(worktree): fix link_planning hook path conversion for Windows

Worktrunk substitutes {{ worktree_path }} as a Unix-style path
(/c/dev/...) which cmd.exe cannot resolve. It also strips $ sigils
from variable names before executing hook commands, making inline
PowerShell variables unusable.

Extract junction logic to .agents/scripts/link-planning.ps1 and
unlink-planning.ps1. The hooks now call powershell -File with
the path as an argument, avoiding both issues entirely.

* docs: add ADR-004 and phase-2 implementation plans

Adds the Supabase session cookies httponly ADR alongside the six
implementation plan documents produced during the auth gate phase.

* feat(auth): implement Phase 2 cloud auth gate (ADR-003 closeout)

- Cloud edition login page redirects to NEXT_PUBLIC_AUTH_HOST_URL;
  local/demo editions keep the NextAuth credentials form
- Delete signup pages and Supabase PKCE callback route from worldwideview
  (auth host owns them per ADR-003)
- Add Supabase SSR helpers (cookieOptions, server, client) with
  httpOnly:true cookies per ADR-004
- Dual-dispatch install-redirect and grant-token: Supabase on cloud,
  NextAuth on local/demo; redirect param unified to ?next=
- Add streaming mode to safeFetch for MJPEG camera proxy streams
- Extract LoginForm into its own component
- Update Playwright config to conditionally start marketplace dev server

* fix(types): cast undici ReadableStream body to BodyInit to satisfy DOM types

node:stream/web ReadableStream is structurally incompatible with the DOM
ReadableStream expected by the Response constructor -- the pipeThrough
signature differs on the T | undefined generic bound. Cast to BodyInit
(which is the correct type for the streaming pass-through) to resolve
the TS2345 error in ssrf.ts line 112.

* fix(e2e): exclude cross-app marketplace specs from default Playwright run

marketplace-redirect-handshake.spec.ts and marketplace-sign-out.spec.ts
require a running marketplace.wwv.local:3002 instance (cross-app
environment). They were being picked up by playwright.config.ts in CI
where that host does not exist, causing ERR_NAME_NOT_RESOLVED failures.
Added both files to testIgnore alongside the existing exclusions; they
should be run via playwright.cross-app.config.ts only.

* fix: add pointer event support to bottom panel resize for webkit

Playwright's webkit engine dispatches pointermove/pointerup reliably
during synthetic drags but mousemove sometimes does not fire. Add
pointermove and pointerup listeners alongside the existing mouse
listeners, and add onPointerDown to the drag handle, so the resize
test passes across all three browser engines.
2026-05-28 21:03:14 +12:00

8.9 KiB

WorldWideView — Agent Rules

1. Project Identity

WorldWideView is a real-time geospatial intelligence engine visualizing live global data on an interactive 3D globe. Built with Next.js 16, CesiumJS, React 19, and Zustand. Design/feature target: www.worldmonitor.app (reference repo).


2. Tech Stack

Layer Technology
Framework Next.js 16 (App Router, output: "standalone")
Language TypeScript 5, strict mode
3D Engine CesiumJS + Resium (Google Photorealistic 3D Tiles)
State Zustand (9 slices: globe, layers, timeline, ui, filter, data, config, favorites, geojson)
Event Bus Custom typed DataBus (pub/sub singleton)
Styling Vanilla CSS — no Tailwind
Database PostgreSQL via Prisma 7
Auth NextAuth v5 beta (Credentials provider, JWT sessions)
Package Manager pnpm (monorepo with pnpm-workspace.yaml)
Testing Vitest + jsdom + React Testing Library
Deployment Docker multi-stage build → Coolify

3. Critical Invariants

Agents MUST respect these at all times:

  • Plugin source of truth: @worldwideview/wwv-plugin-sdk — never define plugin types locally.
  • All-Bundle Model: every plugin is dynamically imported via loadPluginFromManifest using import(/* webpackIgnore: true */ entry). Legacy StaticDataPlugin / DeclarativePlugin runtimes are deprecated.
  • Agnostic frontend: each plugin MUST declare its own streamUrl; do not assume one shared pipe.
  • Nine Zustand slices under src/core/state/: access via useStore in React, useStore.getState() elsewhere.
  • Primitive-based rendering: Point/Billboard/Label/Polyline collections only. Never mix size/outlineWidth/outlineColor onto billboard entities — GPU silently clips.
  • Three editions via NEXT_PUBLIC_WWV_EDITION (local / cloud / demo); feature flags in src/core/edition.ts.
  • Nested git clones: local-plugins/ (community plugins) and local-seeders/community/ + local-seeders/private/ (seeders) are independent git repos cloned inside this repo, gitignored from it. Each has its own remote. Run git pull inside each before editing; commits/pushes there go to their own upstream — not to worldwideview. See .agents/context/ecosystem-repositories.md.

4. Conventions

  • File size: ~300 lines max. Extract helpers, split components, use hooks.
  • Import aliases: @/* → ./src/*; @worldwideview/wwv-plugin-sdk → ./packages/wwv-plugin-sdk/src
  • CSS: Vanilla CSS only. Global: src/app/globals.css. Scoped: CSS Modules. HUD: src/styles/hud-animations.css.
  • Rendering entities: Points use type: "point" + size/outlineColor/outlineWidth. Billboards use type: "billboard" + iconUrl/iconScale. NEVER mix.
  • Plugin registration: Built-ins via AppShell.tsx → PluginRegistry → PluginManager. Marketplace plugins via InstalledPluginsLoader.
  • Workspace: Use "workspace:*" (not "*") for internal deps. New packages/ plugins need transpilePackages in next.config.ts.
  • Temp files: Save debugging scripts/outputs exclusively in /local-scripts/ — never in root.
  • Cleanliness: Remove dead code, unused imports, debug console.log before finalising. Never use any or @ts-ignore. Never create .mdc files.

5. AI Meta-Directives

Warning

  • Always use .md extensions. Never .mdc. Never reference Cursor IDE rules.
  • MUST bump semver in package.json before every commit via /commit workflow (feat: → Minor, fix/refactor/perf: → Patch).
  • MUST explain complex concepts simply — include an everyday-life analogy.
  • MUST require explicit user authorization before any state-changing action that isn't simple/safe.
  • MUST ask clarifying questions rather than assume when requirements are unclear.
  • MUST update .agents/rules/ files immediately whenever an architectural shift invalidates them.

6. Environment & Configuration

See .agents/context/environment-config.md for required environment variables and secrets.


7. Development & Deployment

pnpm dev          # Frontend only (auto-runs prisma db push + copy-cesium)
pnpm dev:all      # Frontend + data engine via Docker Compose
pnpm build        # Production build
pnpm test         # Vitest
pnpm db:reset     # Wipe + re-migrate DB (destructive)

See .agents/context/ → [deployment and testing details in .agents/rules/deployment-and-testing.md] for Docker architecture, Coolify rules, and CSP headers.


8. On-Demand Rules (path-scoped, auto-load on file access)

These load automatically when you read/edit files matching their paths:

Rule Triggers on
.agents/rules/cesium-rendering.md src/core/globe/**, src/plugins/**, packages/wwv-plugin-*/src/**
.agents/rules/state-management.md src/core/state/**, src/components/**
.agents/rules/plugin-architecture.md src/core/plugins/**, packages/wwv-plugin-*/src/**, local-plugins/**
.agents/rules/marketplace-architecture.md src/lib/marketplace/**, src/app/api/marketplace/**
.agents/rules/cloud-auth-architecture.md src/lib/auth*, src/app/api/auth/**, src/core/auth.ts
.agents/rules/database-migrations.md prisma/**
.agents/rules/monorepo-workflow.md packages/**, pnpm-workspace.yaml, local-plugins/**
.agents/rules/data-engine-architecture.md packages/**, local-seeders/**, docker-compose.yml
.agents/rules/deployment-and-testing.md Dockerfile, docker-compose.yml, .github/**, next.config.ts
.agents/rules/e2e-testing.md tests/**, public/e2e-fixtures/**, playwright.config.ts

9. On-Demand Context (read explicitly when needed)

See .agents/context/INDEX.md for the full navigation table. Key files:

When to read File
Product vision, business model, Edition system .agents/context/platform-architecture.md
Finding files, repo layout .agents/context/directory-structure.md
Routing fix to correct repository .agents/context/ecosystem-repositories.md
Next.js, data pipeline, Redis, DB schema .agents/context/application-architecture.md
Debugging plugin data, namespace collisions .agents/context/troubleshooting-and-debugging.md
SSH, Coolify MCP .agents/context/server-management.md
Coding principles, Definition of Done .agents/context/coding-principles.md
.env variables and secrets .agents/context/environment-config.md

10. Slash Commands

Command Description File
/commit Required before every commit — bump semver + conventional commit .agents/skills/commit/SKILL.md
/remember Save a lesson or fact into permanent memory .agents/skills/remember/SKILL.md
/pr-review 6-role comprehensive pull request review .agents/skills/pr-review/SKILL.md
/local-dev Check, start, troubleshoot local dev environment .agents/workflows/local-dev.md
/data-engine-cli Use the wwv-data-engine CLI wrapper .agents/workflows/data-engine-cli.md
/debugging-coolify Troubleshoot deployed apps on Coolify via MCP/SSH .agents/workflows/debugging-coolify.md
/five Five Whys root cause analysis .agents/workflows/five.md
/stitch-to-nextjs Generate UI with Stitch MCP, port into Next.js .agents/workflows/stitch-to-nextjs.md
/branch-cleanup Post-merge teardown — commit leftovers, delete plan file, remove worktree via worktree-manager .agents/skills/branch-cleanup/SKILL.md

11. Agent Skills Reference

Skill When to Use
worldwideview-plugin-creation Use when creating any plugin — strict architectural checklist
plugin-creation-master-guide.md Decision matrix for choosing plugin architecture
osm-static-plugin-creation.md Creating static GeoJSON plugins from OpenStreetMap
database-operations.md Prisma schema changes, migrations, database queries
database-incident-recovery-procedures.md Safely restoring a broken production database

52 global skills available. See .agents/global-skills-index.md.


12. Pull Request & Commit Guidelines

  • Commit format: Conventional Commits (feat:, fix:, refactor:, perf:). Use /commit workflow.
  • Required checks: pnpm test and pnpm build must pass before merge.
  • Review: Use /pr-review for comprehensive multi-role review.
  • Worktrees: Use git-wt switch --create <branch> and git-wt remove (never rm -rf a worktree — orphans the PostgreSQL Docker volume). After a PR merges, use /branch-cleanup to commit leftovers, delete the plan file, and remove the worktree in one flow.

Hard Rule

Always interface-based, extensible, composable, modular. Never band-aids on band-aids.

Read .agents/context/coding-principles.md before any non-trivial code change.