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

166 lines
8.9 KiB
Markdown

# 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](https://github.com/koala73/worldmonitor)).
---
## 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
```bash
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.