* 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.
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
loadPluginFromManifestusingimport(/* webpackIgnore: true */ entry). LegacyStaticDataPlugin/DeclarativePluginruntimes 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 viauseStorein React,useStore.getState()elsewhere. - Primitive-based rendering: Point/Billboard/Label/Polyline collections only. Never mix
size/outlineWidth/outlineColoronto billboard entities — GPU silently clips. - Three editions via
NEXT_PUBLIC_WWV_EDITION(local/cloud/demo); feature flags insrc/core/edition.ts. - Nested git clones:
local-plugins/(community plugins) andlocal-seeders/community/+local-seeders/private/(seeders) are independent git repos cloned inside this repo, gitignored from it. Each has its own remote. Rungit pullinside each before editing; commits/pushes there go to their own upstream — not toworldwideview. 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 usetype: "billboard"+iconUrl/iconScale. NEVER mix. - Plugin registration: Built-ins via
AppShell.tsx→PluginRegistry→PluginManager. Marketplace plugins viaInstalledPluginsLoader. - Workspace: Use
"workspace:*"(not"*") for internal deps. Newpackages/plugins needtranspilePackagesinnext.config.ts. - Temp files: Save debugging scripts/outputs exclusively in
/local-scripts/— never in root. - Cleanliness: Remove dead code, unused imports, debug
console.logbefore finalising. Never useanyor@ts-ignore. Never create.mdcfiles.
5. AI Meta-Directives
Warning
- Always use
.mdextensions. Never.mdc. Never reference Cursor IDE rules.- MUST bump semver in
package.jsonbefore every commit via/commitworkflow (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/commitworkflow. - Required checks:
pnpm testandpnpm buildmust pass before merge. - Review: Use
/pr-reviewfor comprehensive multi-role review. - Worktrees: Use
git-wt switch --create <branch>andgit-wt remove(neverrm -rfa worktree — orphans the PostgreSQL Docker volume). After a PR merges, use/branch-cleanupto 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.