Compare commits

...
Author SHA1 Message Date
Antigravity AI a0646a5ab1 fix: merge origin/main, resolve version conflict (bump to 2.48.24)
Merged latest main (2.48.23) into fix/hardcoded-engine-urls. Resolved the
single conflict in package.json by taking main's changes and bumping the
version to 2.48.24 per the patch-level commit rule.
2026-06-05 00:28:16 +12:00
Silvertakana 9a5adb832e docs(rules): seeder authoring contract + close-context-gaps meta-directive (#240)
* docs(rules): add seeder authoring contract to data-engine-architecture rule

Adds section 8 documenting how to write a seeder: the auto-discovery model,
the three module shapes (interval+fetch, cron+fn, init), the { redis }-only
ctx, and publishing via @worldwideview/seeder-sdk. Includes good/bad examples
contrasting the ctx.setLiveSnapshot trap (which caused a silent CI failure)
against the two correct shapes. This rule auto-loads on local-seeders/** edits.

* docs(rules): add close-context-gaps AI meta-directive to AGENTS.md

When missing/wrong/undocumented context causes an error, a long struggle, or
slow understanding, agents must fix the doc/context (or add a guardrail) at its
source, or ask the user to; in autonomous mode, log the gap to revisit. Codifies
the lesson from the seeder ctx.setLiveSnapshot incident for all contributors.
2026-06-05 00:25:44 +12:00
Antigravity AI 3200d38194 refactor(env): rename NEXT_PUBLIC_WWV_DATA_ENGINE_URL to NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL
Rename the env var to make its scope unambiguous: it is a local dev
override only and must never be set in production. Split the old single
var into two with clearly documented purposes:

- NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL (local dev, .env.local, browser+server)
  Used by resolveEngineUrl.ts and engineManifest.ts to redirect WS
  connections to a locally-running engine during plugin development.
  Each worktree should use a different port to avoid collisions.

- WWV_DATA_ENGINE_URL (production, docker-compose/Coolify, server-side only)
  Used by service.ts for MCP REST calls to the engine. NOT read by
  the browser. Set in docker-compose, not in .env.local.

service.ts shim reads WWV_DATA_ENGINE_URL first so existing production
docker-compose deployments are not broken by this rename.

Also fixes stale dataengine.worldwideview.dev subdomain references in
hostGlobals.ts (cloud fallback URLs now correctly point to dataenginev2).
2026-06-05 00:24:27 +12:00
Silvertakana f447bd7e72 fix(ci): stub seeder interval+fetch + drop redundant compose mount (#239)
Companion to wwv-data-engine fix/ci-stub-interval-fetch. The source-of-truth
stub (docker/ci/stub-seeder) used cron+fn and called ctx.setLiveSnapshot,
which the seeder ctx ({ redis }) does not expose — the snapshot never landed.
Switch to interval+fetch (return the array; scheduler auto-wraps + stores it).

Also remove the plugin-CI compose's ./stub-seeder volume mount and the stale
'Known foundation gap (deferred)' comment: the stub is now baked into the :ci
image at /app/seeders/stub, so the compose needs no host path and a consumer
repo can run it with only this YAML.
2026-06-04 23:58:20 +12:00
Silvertakana a833cf4790 fix(ci-probe): subscribe to pluginId on /stream + safe stub + plugin-CI auth bypass (#238) 2026-06-04 23:40:08 +12:00
SilvertakanaandClaude Sonnet 4.6 352fbce768 feat: CI smoke-test foundation (probe + mock-upstream + isolated docker CI) (#236)
* feat: CI smoke-test foundation (probe + docker compose + rule updates)

Phase 1 of multi-repo CI initiative for catching plugin/seeder integration
failures (ADR-0002 id drift, missing mapWebsocketPayload, namespace
collisions, BOM in package.json) that current CI misses.

- packages/wwv-ci-probe: shared CLI with `seeder`, `ws`, `id-contract`
  subcommands. README documents why no `plugin` subcommand (Playwright belongs
  in wwv-plugins, not coupled to this probe). `files` + `prepublishOnly`
  configured for clean npm publish.
- docker/ci/: reusable docker-compose stacks for plugin-CI and seeder-CI,
  plus mock-upstream HTTP fixture server and CI-only stub-seeder. Compose
  comments document scope boundary (consumer workflow owns user/plugin-row
  injection via Playwright globalSetup pattern) and the deferred stub-seeder
  bake-in for wwv-data-engine.
- .github/workflows/docker-publish.yml: adds `:ci` tag alias for downstream
  consumers (one-line edit).
- .agents/rules/*: rename worldwideview-plugins → wwv-plugins (4 files) to
  reflect repo rename + clarify it lives at local-plugins/ as its own git
  working tree.

Bump 2.15.16 → 2.16.0 (Minor — new ci-probe package + new docker/ci
infrastructure are net-new features for the CI ecosystem).

Foundation has NOT been booted end-to-end yet — ghcr.io/silvertakana/
worldwideview:ci doesn't exist until this lands on main and the workflow
publishes. Next session: validate via real compose-up, then mirror the :ci
tag in wwv-data-engine repo and wire consumer workflows in wwv-plugins.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

* refactor(ci-probe): extract shared payload-shape validator with contract tests

* fix(ci): add /__health route to mock-upstream and gate engine on service_healthy

* chore: bump version to 2.48.18 for CI foundation landing

* chore: bump to 2.48.19 and reconcile lockfile after merging main (validateManifest fix)

---------

Co-authored-by: Claude Sonnet 4.6 <[email protected]>
2026-06-04 23:00:02 +12:00
Antigravity AI 1831e7e5d8 docs(rules): document data engine agnosticism separation of concern
Add an explicit rule section clarifying that plugins own their streamUrl,
WWV never overrides it globally, and the NEXT_PUBLIC_WWV_DATA_ENGINE_URL var
is for server-side REST calls only -- not plugin streaming.
2026-06-04 22:35:45 +12:00
Antigravity AI 0f43baacf0 fix(engine): replace stale dataengine subdomain with dataenginev2
hostGlobals.ts and resolveEngineUrl.ts comment both referenced the old
dataengine.worldwideview.dev subdomain; updated to dataenginev2.worldwideview.dev.
2026-06-04 22:35:17 +12:00
Antigravity AI 138f26c8e8 refactor(data-engine): consolidate engine URL to single NEXT_PUBLIC_WWV_DATA_ENGINE_URL
Replaces two separate env vars (NEXT_PUBLIC_WWV_LOCAL_ENGINE_PORT and
WWV_DATA_ENGINE_URL) with one: NEXT_PUBLIC_WWV_DATA_ENGINE_URL (full
HTTP base URL, default http://localhost:5000). Available both client-side
and server-side so it only needs to be defined once.

- engineManifest.ts: getLocalEngineBase() reads the new var directly
- resolveEngineUrl.ts: getLocalWsUrl() converts http->ws from the new var
- service.ts: getEngineUrl() reads the new var (fixes 5001->5000 default)
- Tests updated to set the full URL instead of a port number
- .env.example documents the new var with local and Docker examples
2026-06-04 22:24:08 +12:00
Antigravity AI cdad4dc776 fix(data-engine): replace hardcoded engine URLs with env var
Deduplicates the WWV_DATA_ENGINE_URL fallback: discoveryHelpers.ts now
calls getEngineUrl() from data-query/service instead of inlining the
same logic. Comments and test mocks that referenced literal localhost:5001
or localhost:5000 now reference NEXT_PUBLIC_WWV_LOCAL_ENGINE_PORT or use
a generic test host. Closes #182.
2026-06-04 21:10:21 +12:00
33 changed files with 1379 additions and 23 deletions

No files matched your search

+57
View File
@@ -89,3 +89,60 @@ This means:
> [!CAUTION]
> The most common silent bug: seeder sends `{ items: [...] }` (an object), frontend plugin omits `mapWebsocketPayload`. Data arrives but WsClient drops it with a console warning. The globe stays empty. Always implement `mapWebsocketPayload` for any plugin whose seeder sends an object payload.
## 8. Seeder Authoring Contract — the module shape
§7 covers what a seeder **sends**. This covers how you **write** one. The engine
auto-discovers a seeder by scanning `SEEDERS_DIR` for any folder with
`dist/index.mjs` and importing its **default export**. The seeder's `id` is the
**folder name**, not the `name` field. You never call a register function — the
authoritative reference is `wwv-data-engine/README.md` → "Authoring a Seeder".
The default export is `{ name }` plus **one** of these shapes:
| Shape | You provide | How data is published |
|---|---|---|
| `interval` + `fetch(ctx)` | `fetch` **returns** the array | scheduler wraps + stores + broadcasts it for you |
| `cron` + `fn(ctx)` | `fn` publishes itself | `import { setLiveSnapshot } from '@worldwideview/seeder-sdk'` and call it |
| `init(ctx)` | a persistent listener | publish via the SDK as push data arrives |
**The trap (this caused a real, silent CI failure):** `ctx` is **only `{ redis }`**.
There is no `ctx.setLiveSnapshot`. Reaching for it throws at runtime and the
snapshot never lands. Publish helpers come from `@worldwideview/seeder-sdk`, not
from `ctx`. The engine now types `ctx` as `SeederContext { redis }`, so this is a
compile error for any typed seeder — but `.mjs` seeders without type-checking get
no such safety net, so know the contract.
<bad-example>
```ts
// cron + fn reaching for a method that does not exist on ctx
export default {
name: "earthquakes",
cron: "0 * * * *",
fn: async (ctx) => {
await ctx.setLiveSnapshot("earthquakes", items, 3600); // ❌ not a function — dies silently
},
};
```
</bad-example>
<good-example>
```ts
// Option A — cron + fn: publish via the SDK (dominant idiom)
import { setLiveSnapshot } from "@worldwideview/seeder-sdk";
export default {
name: "earthquakes",
cron: "0 * * * *",
fn: async () => {
await setLiveSnapshot("earthquakes", { source: "earthquakes", fetchedAt: new Date().toISOString(), items, totalCount: items.length }, 3600);
},
};
// Option B — interval + fetch: just return the array, scheduler does the rest
export default {
name: "earthquakes",
interval: 60_000,
fetch: async () => items, // ✅ no publishing call needed
};
```
</good-example>
+16
View File
@@ -12,6 +12,22 @@ paths:
## Purpose
The standard operating procedure for instantiating, modifying, and registering a new data source plugin within the engine.
## Data Engine Agnosticism (Separation of Concern)
> [!IMPORTANT]
> **WWV is agnostic to which data engine a plugin uses.** Each plugin MUST declare its own `streamUrl` in `getServerConfig()`. The WWV application never controls or overrides plugin stream URLs.
This is intentional architectural separation: a user can have 30 plugins pointing to 30 different custom backend servers, and WWV opens 30 separate WebSocket connections without caring. The WWV app does not have a "the data engine" — each plugin has its own.
**Practical rules:**
- Plugins hardcode their cloud engine URL (e.g. `wss://dataenginev2.worldwideview.dev/stream`) — this is correct and by design.
- Do not add env vars to let WWV override a plugin's `streamUrl` globally — that breaks the separation.
- When editing a plugin's fallback fetch URL, use `https://dataenginev2.worldwideview.dev` (note the `v2`).
- `NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL` is a local dev only var (`.env.local` only, never production) that routes locally-developed plugin seeders to a local engine instance. It is NOT injected into plugin stream URLs.
- `WWV_DATA_ENGINE_URL` is the production server-side var (docker-compose / Coolify) for the WWV app's own REST calls (MCP tools, entity search). Never set `NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL` in production.
---
## The WorldPlugin Contract
All data ingest flows through `WorldPlugin` (defined entirely within `@worldwideview/wwv-plugin-sdk`).
+13
View File
@@ -96,6 +96,19 @@ PROXY_HOST_ALLOWLIST=*
# Comma-separated list of plugin IDs
NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS=
# Local Engine URL (local dev only — set in .env.local, NEVER in production)
# Points at your local data engine instance for per-plugin WS stream routing.
# Each worktree should use a different port so their engines don't collide.
# Local dev (engine on host): http://localhost:5000
NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL=
# Data Engine REST URL (production / Docker Compose — server-side only)
# Used by MCP data tools and server-side entity queries to reach the engine REST API.
# NOT read by the browser. Set this in docker-compose or Coolify, not in .env.local.
# Docker Compose (same network): http://wwv-data-engine:5000
# External engine: http://<engine-host-ip>:5002
# WWV_DATA_ENGINE_URL=
# Edition: "local" | "cloud" | "demo"
NEXT_PUBLIC_WWV_EDITION=local
+1
View File
@@ -61,6 +61,7 @@ jobs:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=raw,value=latest,enable={{is_default_branch}}
type=raw,value=ci,enable={{is_default_branch}}
type=ref,event=branch
type=sha,format=short
+1
View File
@@ -60,6 +60,7 @@ Agents MUST respect these at all times:
> - **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.
> - **MUST** close context gaps: when missing/wrong/undocumented context made you err, struggle, or go slow, fix the relevant doc/context (or add a type/guardrail) at its source — or ask the user to update it when it depends on their knowledge. In autonomous mode, log the gap to revisit later. Never fix only the symptom and leave the trap armed for the next contributor.
---
+97
View File
@@ -0,0 +1,97 @@
# Reusable compose for plugin smoke CI (consumed by wwv-plugins repo).
#
# Boots a full stack with a STUB seeder that emits known-good GeoEntity[]
# data under the plugin-under-test's id. This isolates "is the frontend
# wiring correct" from "is the real backend healthy" — a broken real seeder
# cannot fail plugin CI.
#
# ─── Scope boundary (what THIS compose does vs what the workflow does) ───
#
# This compose only boots services. The consuming workflow's Playwright
# `globalSetup` is responsible for:
# 1. Inserting the test user into `users` (for NextAuth credentials login)
# 2. Inserting the `InstalledPlugin` row with the plugin's manifest JSON
# (entry URL → http://localhost:3000/plugins-local/<PLUGIN_ID>/frontend.mjs)
# 3. UI login → save storageState.json
# 4. Running the smoke spec
#
# Reuse the pattern from worldwideview/tests/global.setup.ts. DB migrations
# are handled automatically by the wwv-app entrypoint at container start.
#
# ─── Stub seeder source ───
#
# The stub seeder is baked into the `wwv-data-engine:ci` image at
# /app/seeders/stub (see wwv-data-engine/Dockerfile.ci). The compose only needs
# to set STUB_PLUGIN_ID — no volume mount, so a consumer repo can download just
# this YAML and run it without the worldwideview source tree present.
#
# Expected env vars from consuming workflow:
# PLUGIN_ID — kebab-case id of the plugin under test (e.g. "aviation")
# PLUGIN_BUNDLE_DIR — host path to the plugin's compiled dist/ (mounted into wwv-app)
# CI_IMAGE_TAG — image tag to pull (default: ci)
services:
db:
image: postgres:15-alpine
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: worldwideview
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d worldwideview"]
interval: 3s
timeout: 3s
retries: 20
wwv-redis:
image: redis:7-alpine
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 3s
timeout: 3s
retries: 10
wwv-data-engine:
image: ghcr.io/silvertakana/wwv-data-engine:${CI_IMAGE_TAG:-ci}
command: ["node", "dist/server.js"]
ports:
- "5000:5000"
environment:
PORT: 5000
REDIS_URL: redis://wwv-redis:6379
SEEDERS_DIR: /app/seeders
DB_PATH: /tmp/engine.db
# Stub seeder reads the target plugin id from this env var
STUB_PLUGIN_ID: ${PLUGIN_ID}
WWV_SKIP_WS_AUTH: "true"
NODE_ENV: ci
# No volume mount: the stub seeder is baked into the :ci image at
# /app/seeders/stub, so the engine discovers it as id "stub" with no host
# path dependency.
depends_on:
wwv-redis:
condition: service_healthy
wwv-app:
image: ghcr.io/silvertakana/worldwideview:${CI_IMAGE_TAG:-ci}
ports:
- "3000:3000"
environment:
AUTH_SECRET: ci-placeholder-secret-not-used-in-tests
DATABASE_URL: postgresql://postgres:postgres@db:5432/worldwideview?schema=public
NEXT_PUBLIC_WWV_EDITION: local
NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL: http://localhost:5000
volumes:
# Mount the plugin's compiled bundle so the app can load it locally
- ${PLUGIN_BUNDLE_DIR}:/app/public/plugins-local/${PLUGIN_ID}:ro
depends_on:
db:
condition: service_healthy
wwv-data-engine:
condition: service_started
healthcheck:
test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1"]
interval: 5s
timeout: 5s
retries: 30
start_period: 30s
+64
View File
@@ -0,0 +1,64 @@
# Reusable compose for seeder smoke CI (consumed by wwv-seeders-* repos).
#
# Runs the REAL seeder against a MOCK upstream HTTP server. This isolates
# "is the seeder code correct" from "is the upstream provider up" — a
# NASA FIRMS / OpenSky / Overpass outage cannot fail seeder CI.
#
# Expected env vars from consuming workflow:
# SEEDER_NAME — kebab-case name of the seeder under test
# SEEDER_DIST_DIR — host path to the seeder's compiled dist/ + package.json
# FIXTURE_DIR — host path to the seeder's __fixtures__ directory
# CI_IMAGE_TAG — image tag to pull (default: ci)
#
# Plus any seeder-specific upstream env vars (e.g. OPENSKY_API_BASE)
# already exported in the workflow shell, all pointing at http://mock-upstream:8080
services:
wwv-redis:
image: redis:7-alpine
ports:
- "6379:6379"
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 3s
timeout: 3s
retries: 10
mock-upstream:
build:
context: ./mock-upstream
volumes:
- ${FIXTURE_DIR}:/fixtures:ro
environment:
FIXTURE_DIR: /fixtures
PORT: 8080
healthcheck:
test: ["CMD-SHELL", "wget -q -O- http://localhost:8080/__health || exit 1"]
interval: 5s
timeout: 3s
retries: 5
wwv-data-engine:
image: ghcr.io/silvertakana/wwv-data-engine:${CI_IMAGE_TAG:-ci}
command: ["node", "dist/server.js"]
ports:
- "5000:5000"
volumes:
# Mount ONLY this seeder under /app/seeders/community/<name> — isolates
# the test from any cross-seeder dependencies or collisions.
- ${SEEDER_DIST_DIR}:/app/seeders/community/${SEEDER_NAME}:ro
environment:
PORT: 5000
REDIS_URL: redis://wwv-redis:6379
SEEDERS_DIR: /app/seeders
DB_PATH: /tmp/engine.db
# Seeder-specific upstream env vars are injected by the consuming
# workflow via `environment:` overrides or `env_file:`.
env_file:
- path: ./.seeder.env
required: false
depends_on:
wwv-redis:
condition: service_healthy
mock-upstream:
condition: service_healthy
+5
View File
@@ -0,0 +1,5 @@
FROM node:22-alpine
WORKDIR /mock
COPY server.mjs ./
EXPOSE 8080
CMD ["node", "/mock/server.mjs"]
+48
View File
@@ -0,0 +1,48 @@
# mock-upstream
Tiny HTTP server used in CI to stand in for upstream data APIs (OpenSky, NASA FIRMS, Overpass, etc.) so seeder CI can run hermetically without real API keys or network flakiness.
## How it works
Mount a fixture directory at `/fixtures`. The directory must contain a `routes.json` mapping request paths → fixture filenames:
```json
{
"/api/states/all": "opensky-states.json",
"/api/v2/flights": "flights.json"
}
```
When the server receives `GET /api/states/all`, it serves the contents of `/fixtures/opensky-states.json`.
## Env vars
| Var | Default | Purpose |
|---|---|---|
| `FIXTURE_DIR` | `/fixtures` | Directory mounted from the seeder repo |
| `ROUTES_FILE` | `${FIXTURE_DIR}/routes.json` | Override the routes manifest path |
| `PORT` | `8080` | Listen port |
## Per-seeder convention
Each seeder ships its own `__fixtures__/` folder next to `src/`:
```
wwv-seeders-community/aviation/
├── src/index.ts
└── __fixtures__/
├── routes.json
└── opensky-states.json
```
In CI compose, that folder is mounted into the mock-upstream container at `/fixtures` for the duration of the seeder smoke test.
## Architectural contract
Seeders MUST read upstream URLs from documented env vars with the production URL as the default, e.g.:
```ts
const UPSTREAM = process.env.OPENSKY_API_BASE ?? "https://opensky-network.org";
```
The CI compose then overrides `OPENSKY_API_BASE=http://mock-upstream:8080`. Without this convention, CI mocking is impossible — hardcoded URLs cannot be intercepted.
+61
View File
@@ -0,0 +1,61 @@
import { createServer } from "node:http";
import { readFileSync, existsSync } from "node:fs";
import { resolve, join } from "node:path";
const FIXTURE_DIR = process.env.FIXTURE_DIR ?? "/fixtures";
const PORT = Number(process.env.PORT ?? 8080);
const ROUTES_FILE = process.env.ROUTES_FILE ?? join(FIXTURE_DIR, "routes.json");
if (!existsSync(ROUTES_FILE)) {
console.error(`[mock-upstream] no routes file at ${ROUTES_FILE}`);
process.exit(1);
}
let routes;
try {
routes = JSON.parse(readFileSync(ROUTES_FILE, "utf8"));
} catch (err) {
console.error(`[mock-upstream] failed to parse ${ROUTES_FILE}:`, err);
process.exit(1);
}
console.log(`[mock-upstream] loaded ${Object.keys(routes).length} routes from ${ROUTES_FILE}`);
createServer((req, res) => {
const path = req.url?.split("?")[0] ?? "/";
if (path === "/__health") {
res.statusCode = 200;
res.setHeader("content-type", "application/json");
res.end(JSON.stringify({ status: "ok" }));
return;
}
const file = routes[path];
if (!file) {
console.warn(`[mock-upstream] 404 ${req.method} ${path}`);
res.statusCode = 404;
res.setHeader("content-type", "application/json");
res.end(JSON.stringify({ error: "no fixture", path }));
return;
}
const filePath = resolve(FIXTURE_DIR, file);
if (!filePath.startsWith(resolve(FIXTURE_DIR))) {
res.statusCode = 400;
res.end("bad fixture path");
return;
}
try {
const body = readFileSync(filePath);
res.statusCode = 200;
res.setHeader("content-type", file.endsWith(".json") ? "application/json" : "text/plain");
res.end(body);
console.log(`[mock-upstream] 200 ${req.method} ${path} -> ${file}`);
} catch (err) {
console.error(`[mock-upstream] 500 ${req.method} ${path}:`, err);
res.statusCode = 500;
res.end("fixture read failed");
}
}).listen(PORT, () => {
console.log(`[mock-upstream] listening on :${PORT}`);
});
+55
View File
@@ -0,0 +1,55 @@
// CI-only stub seeder. Emits a known-good GeoEntity[] payload under the
// plugin id provided via STUB_PLUGIN_ID. Used by plugin-CI to isolate
// frontend wiring from real backend health.
//
// NOTE: This bypasses ADR-0002's compile-time name rule on purpose — the
// data engine reads `name` once at load time, so an env-driven name is
// fine in CI. Do NOT copy this pattern into real seeders.
const pluginId = process.env.STUB_PLUGIN_ID;
// When unconfigured (e.g. seeder-CI, where this stub is baked into the shared
// :ci image but unused), export a nameless module so the seeder-loader skips
// it instead of crashing the engine.
//
// Uses the interval+fetch seeder contract: fetch() RETURNS the array and the
// scheduler auto-wraps it into a snapshot stored under the seeder id. The
// cron+fn contract would require the engine-internal setLiveSnapshot, which is
// NOT exposed on the seeder ctx (ctx is only { redis }).
function makeEntities() {
const now = new Date().toISOString();
return [
{
id: `${pluginId}-stub-1`,
pluginId,
latitude: 0,
longitude: 0,
altitude: 0,
timestamp: now,
label: "Stub entity 1",
properties: { source: "ci-stub" },
},
{
id: `${pluginId}-stub-2`,
pluginId,
latitude: 10,
longitude: 10,
altitude: 0,
timestamp: now,
label: "Stub entity 2",
properties: { source: "ci-stub" },
},
];
}
export default pluginId
? {
name: pluginId,
interval: 10000,
fetch: async () => {
const entities = makeEntities();
console.log(`[stub-seeder] emitting ${entities.length} entities for ${pluginId}`);
return entities;
},
}
: {};
+7
View File
@@ -0,0 +1,7 @@
{
"name": "stub-seeder",
"version": "0.1.0",
"type": "module",
"main": "dist/index.mjs",
"private": true
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "worldwideview",
"version": "2.48.18",
"version": "2.48.24",
"private": true,
"type": "module",
"packageManager": "[email protected]",
+55
View File
@@ -0,0 +1,55 @@
# @worldwideview/wwv-ci-probe
CI probe — asserts plugin/seeder integration health for the WorldWideView ecosystem.
Used by the smoke-test workflows in [`wwv-plugins`](https://github.com/silvertakana/wwv-plugins), [`wwv-seeders-community`](https://github.com/silvertakana/wwv-seeders-community), and [`wwv-seeders-private`](https://github.com/silvertakana/wwv-seeders-private).
## Install
```bash
# Via npx (recommended in CI)
npx --yes @worldwideview/wwv-ci-probe <subcommand>
# Or as a dev dependency
pnpm add -D @worldwideview/wwv-ci-probe
```
## Subcommands
### `seeder <name>`
Polls Redis for `data:<name>:live` and validates the payload shape. Accepts `GeoEntity[]`, `{ items: [...] }`, or `{ <key>: [...] }`. Use this in seeder CI after booting the data engine against a mock upstream.
```bash
wwv-probe seeder aviation --redis redis://localhost:6379 --timeout 60000
```
### `ws <name>`
Connects to the data engine's `/stream` WebSocket and waits for a `data` message matching the given `pluginId`. Validates the same payload shapes as `seeder`. Use this when you want to assert the engine is broadcasting (not just persisting).
```bash
wwv-probe ws aviation --url ws://localhost:5000/stream --timeout 30000
```
### `id-contract <seederDist>`
Statically validates that a compiled seeder exports a kebab-case `name` (ADR-0002). Optionally checks the name matches an expected id.
```bash
wwv-probe id-contract ./dist/index.mjs --expect aviation
```
## Plugin smoke testing — not in this probe
The probe deliberately does **not** include a `plugin` subcommand. Plugin smoke tests need to exercise the full Next.js + Cesium frontend (plugin bundle loading, `mapWebsocketPayload`, DataBus wiring), which requires a real browser via Playwright.
The `wwv-plugins` repo writes its own Playwright spec for that — it reuses the auth bootstrap pattern from `worldwideview/tests/global.setup.ts` (insert test user + `InstalledPlugin` row, UI login to capture `storageState.json`, then run the plugin-toggle smoke).
Keeping that logic inside `wwv-plugins` avoids coupling this probe to `@playwright/test` and to the specific UI structure of the Next.js frontend.
## Exit codes
- `0` — assertion passed within the timeout
- `1` — assertion failed (timeout exceeded, invalid payload shape, or contract violation)
- `2` — fatal probe error (unhandled exception)
+30
View File
@@ -0,0 +1,30 @@
{
"name": "@worldwideview/wwv-ci-probe",
"version": "0.1.0",
"type": "module",
"description": "CI probe — asserts plugin/seeder integration health (ADR-0002, WS payload contract, Redis snapshots)",
"main": "dist/index.js",
"bin": {
"wwv-probe": "dist/index.js"
},
"files": [
"dist",
"README.md"
],
"scripts": {
"build": "tsc",
"dev": "tsc --watch",
"clean": "rm -rf dist",
"prepublishOnly": "tsc"
},
"dependencies": {
"commander": "^14.0.3",
"ioredis": "^5.4.1",
"ws": "^8.18.0"
},
"devDependencies": {
"@types/node": "^25.9.1",
"@types/ws": "^8.5.13",
"typescript": "^5.0.0"
}
}
+51
View File
@@ -0,0 +1,51 @@
import { pathToFileURL } from "node:url";
import { resolve } from "node:path";
const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
/**
* Validates ADR-0002: a seeder's exported `name` field must be kebab-case
* and (optionally) match an expected plugin id.
*
* @returns true if the contract holds; false (with stderr explanation) otherwise.
*/
export async function probeIdContract(opts: {
seederDist: string;
expectId?: string;
}): Promise<boolean> {
const absPath = resolve(opts.seederDist);
let mod: any;
try {
mod = await import(pathToFileURL(absPath).href);
} catch (err) {
console.error(`[id-contract] failed to import ${absPath}:`, err);
return false;
}
const seeder = mod.default ?? mod;
if (!seeder || typeof seeder !== "object") {
console.error(`[id-contract] ${absPath} has no default export (or export is not an object)`);
return false;
}
const name = seeder.name;
if (typeof name !== "string" || name.length === 0) {
console.error(`[id-contract] seeder default export missing required string field 'name'`);
return false;
}
if (!KEBAB_RE.test(name)) {
console.error(`[id-contract] seeder name "${name}" is not valid kebab-case (must match ${KEBAB_RE})`);
return false;
}
if (opts.expectId && opts.expectId !== name) {
console.error(
`[id-contract] seeder name "${name}" does not match expected plugin id "${opts.expectId}" (ADR-0002 violation)`,
);
return false;
}
console.log(`[id-contract] OK — seeder name "${name}"${opts.expectId ? ` matches expected id` : ""}`);
return true;
}
+60
View File
@@ -0,0 +1,60 @@
#!/usr/bin/env node
import { Command } from "commander";
import { probeSeeder } from "./seeder.js";
import { probeWs } from "./ws.js";
import { probeIdContract } from "./id-contract.js";
const program = new Command();
program
.name("wwv-probe")
.description("WorldWideView CI probe — asserts plugin/seeder integration health")
.version("0.1.0");
program
.command("seeder")
.description("Wait for Redis key data:<name>:live to be populated and validate payload shape")
.argument("<name>", "Canonical plugin id (kebab-case)")
.option("--redis <url>", "Redis URL", "redis://localhost:6379")
.option("--timeout <ms>", "Timeout in milliseconds", "60000")
.action(async (name: string, opts: { redis: string; timeout: string }) => {
const ok = await probeSeeder({
name,
redisUrl: opts.redis,
timeoutMs: Number(opts.timeout),
});
process.exit(ok ? 0 : 1);
});
program
.command("ws")
.description("Connect to engine /stream and wait for a data payload for the given pluginId")
.argument("<name>", "Canonical plugin id (kebab-case)")
.option("--url <url>", "WebSocket URL", "ws://localhost:5000/stream")
.option("--timeout <ms>", "Timeout in milliseconds", "30000")
.action(async (name: string, opts: { url: string; timeout: string }) => {
const ok = await probeWs({
name,
wsUrl: opts.url,
timeoutMs: Number(opts.timeout),
});
process.exit(ok ? 0 : 1);
});
program
.command("id-contract")
.description("Verify seeder dist exports a kebab-case name matching the expected plugin id (ADR-0002)")
.argument("<seederDist>", "Path to compiled seeder dist/index.mjs")
.option("--expect <id>", "Expected plugin id (if omitted, only validates kebab-case)")
.action(async (seederDist: string, opts: { expect?: string }) => {
const ok = await probeIdContract({
seederDist,
expectId: opts.expect,
});
process.exit(ok ? 0 : 1);
});
program.parseAsync().catch((err) => {
console.error("[wwv-probe] fatal:", err);
process.exit(2);
});
@@ -0,0 +1,38 @@
import { describe, it, expect } from "vitest";
import { validatePayloadValue, validatePayloadString } from "./payloadShape.js";
describe("validatePayloadValue", () => {
it("accepts a non-empty GeoEntity array", () => {
expect(validatePayloadValue([{ id: "a" }])).toEqual({ ok: true, shape: "geo-entity-array" });
});
it("rejects an empty array", () => {
expect(validatePayloadValue([])).toEqual({ ok: false, reason: "GeoEntity[] is empty" });
});
it("accepts a non-empty items object", () => {
expect(validatePayloadValue({ items: [1] })).toEqual({ ok: true, shape: "items-object" });
});
it("rejects an empty items array", () => {
expect(validatePayloadValue({ items: [] })).toEqual({ ok: false, reason: "items[] is empty" });
});
it("accepts a single named collection", () => {
expect(validatePayloadValue({ quakes: [1, 2] })).toEqual({ ok: true, shape: "named-collection" });
});
it("rejects an object with no array field", () => {
const r = validatePayloadValue({ a: 1, b: 2 });
expect(r.ok).toBe(false);
});
it("rejects a non-object, non-array value", () => {
const r = validatePayloadValue(42);
expect(r.ok).toBe(false);
});
});
describe("validatePayloadString", () => {
it("parses then validates", () => {
expect(validatePayloadString('[{"id":"x"}]')).toEqual({ ok: true, shape: "geo-entity-array" });
});
it("rejects invalid JSON", () => {
const r = validatePayloadString("{not json");
expect(r.ok).toBe(false);
});
});
+59
View File
@@ -0,0 +1,59 @@
/**
* Shared payload-shape validator for the WWV data contract (data-engine-architecture.md §7).
* A valid live payload is one of three non-empty shapes:
* - geo-entity-array: a top-level non-empty array
* - items-object: an object with a non-empty `items` array
* - named-collection: an object whose single array-valued key is non-empty
*/
export type PayloadShape = "geo-entity-array" | "items-object" | "named-collection";
export type PayloadValidation =
| { ok: true; shape: PayloadShape }
| { ok: false; reason: string };
/**
* Validate an already-parsed payload value.
* @param p - parsed JSON value
* @returns ok with the detected shape, or a reason for rejection
*/
export function validatePayloadValue(p: unknown): PayloadValidation {
if (Array.isArray(p)) {
return p.length > 0
? { ok: true, shape: "geo-entity-array" }
: { ok: false, reason: "GeoEntity[] is empty" };
}
if (p && typeof p === "object") {
const obj = p as Record<string, unknown>;
if (Array.isArray(obj.items)) {
return obj.items.length > 0
? { ok: true, shape: "items-object" }
: { ok: false, reason: "items[] is empty" };
}
const arrayKeys = Object.keys(obj).filter((k) => Array.isArray(obj[k]));
if (arrayKeys.length === 1) {
const arr = obj[arrayKeys[0]] as unknown[];
return arr.length > 0
? { ok: true, shape: "named-collection" }
: { ok: false, reason: `${arrayKeys[0]}[] is empty` };
}
return {
ok: false,
reason: `payload object has no recognizable array field (keys: ${Object.keys(obj).join(", ")})`,
};
}
return { ok: false, reason: `payload is neither array nor object (typeof=${typeof p})` };
}
/**
* Parse a raw JSON string, then validate the resulting value's shape.
* @param raw - raw JSON string from Redis
*/
export function validatePayloadString(raw: string): PayloadValidation {
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch (err) {
return { ok: false, reason: `not valid JSON (${(err as Error).message})` };
}
return validatePayloadValue(parsed);
}
+52
View File
@@ -0,0 +1,52 @@
import { Redis } from "ioredis";
import { validatePayloadString } from "./payloadShape.js";
/**
* Polls Redis for `data:<name>:live` and validates that the seeder produced a
* non-empty payload in one of the three accepted shapes (see
* data-engine-architecture.md §7).
*
* @returns true if a valid payload arrived within the timeout; false otherwise.
*/
export async function probeSeeder(opts: {
name: string;
redisUrl: string;
timeoutMs: number;
}): Promise<boolean> {
const redis = new Redis(opts.redisUrl, { lazyConnect: true, maxRetriesPerRequest: 1 });
const key = `data:${opts.name}:live`;
const deadline = Date.now() + opts.timeoutMs;
const pollIntervalMs = 1000;
try {
await redis.connect();
} catch (err) {
console.error(`[seeder] cannot connect to Redis at ${opts.redisUrl}:`, err);
return false;
}
console.log(`[seeder] waiting for ${key} (timeout ${opts.timeoutMs}ms)`);
while (Date.now() < deadline) {
const raw = await redis.get(key);
if (raw && raw.length > 0) {
const validation = validatePayloadString(raw);
await redis.quit();
if (!validation.ok) {
console.error(`[seeder] payload present but invalid: ${validation.reason}`);
return false;
}
console.log(`[seeder] OK — ${key} populated (shape: ${validation.shape}, bytes: ${raw.length})`);
return true;
}
await sleep(pollIntervalMs);
}
await redis.quit();
console.error(`[seeder] timed out — ${key} never populated within ${opts.timeoutMs}ms`);
return false;
}
function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
+36
View File
@@ -0,0 +1,36 @@
import { describe, it, expect, afterEach } from "vitest";
import { WebSocketServer } from "ws";
import { probeWs } from "./ws.js";
let server: WebSocketServer | undefined;
afterEach(() => { server?.close(); server = undefined; });
function startEngine(opts: { pluginId: string; requireSubscribe: boolean }) {
server = new WebSocketServer({ port: 0 });
server.on("connection", (sock) => {
sock.send(JSON.stringify({ type: "welcome", engine: "test", plugins: [opts.pluginId] }));
const send = () =>
sock.send(JSON.stringify({ type: "data", pluginId: opts.pluginId, payload: [{ id: "x" }] }));
if (!opts.requireSubscribe) { setInterval(send, 20); return; }
sock.on("message", (raw) => {
const msg = JSON.parse(raw.toString());
if (msg.action === "subscribe" && msg.pluginId === opts.pluginId) send();
});
});
const addr = server.address();
const port = typeof addr === "object" && addr ? addr.port : 0;
return `ws://127.0.0.1:${port}/stream`;
}
describe("probeWs", () => {
it("receives data from a subscribe-required engine (sends subscribe frame)", async () => {
const url = startEngine({ pluginId: "stub", requireSubscribe: true });
const ok = await probeWs({ name: "stub", wsUrl: url, timeoutMs: 3000 });
expect(ok).toBe(true);
});
it("times out (false) when the plugin never produces data", async () => {
const url = startEngine({ pluginId: "other", requireSubscribe: true });
const ok = await probeWs({ name: "stub", wsUrl: url, timeoutMs: 800 });
expect(ok).toBe(false);
});
});
+74
View File
@@ -0,0 +1,74 @@
import WebSocket from "ws";
import { validatePayloadValue } from "./payloadShape.js";
/**
* Connects to the data-engine's /stream WebSocket and resolves when a
* `{ type: "data", pluginId: <name>, payload: ... }` message arrives for the
* given plugin id (see data-engine-architecture.md §7).
*
* Rejects with exit code 1 if no matching payload arrives within the timeout
* — which is the signature of an ADR-0002 id mismatch or a silently-dropped
* object payload.
*/
export async function probeWs(opts: {
name: string;
wsUrl: string;
timeoutMs: number;
}): Promise<boolean> {
return new Promise((resolve) => {
const ws = new WebSocket(opts.wsUrl);
let settled = false;
const timer = setTimeout(() => {
if (settled) return;
settled = true;
console.error(
`[ws] timed out — no data message with pluginId="${opts.name}" in ${opts.timeoutMs}ms ` +
`(check ADR-0002 seeder.name vs plugin id, and that the seeder is producing data)`,
);
ws.terminate();
resolve(false);
}, opts.timeoutMs);
ws.on("open", () => {
// The engine is subscribe-required: it only broadcasts a plugin's data to
// connections that have subscribed to it (websocket.ts broadcastPluginData).
// Auth is bypassed in CI via WWV_SKIP_WS_AUTH=true, so no auth frame is sent.
ws.send(JSON.stringify({ action: "subscribe", pluginId: opts.name }));
console.log(`[ws] connected to ${opts.wsUrl}, subscribed to pluginId="${opts.name}"`);
});
ws.on("message", (raw) => {
let msg: any;
try {
msg = JSON.parse(raw.toString());
} catch {
return;
}
if (msg?.type !== "data" || msg.pluginId !== opts.name) return;
if (settled) return;
const payload = msg.payload;
const valid = validatePayloadValue(payload);
if (!valid.ok) {
console.error(`[ws] received message for "${opts.name}" but payload invalid: ${valid.reason}`);
// Keep waiting — a later message might be valid.
return;
}
settled = true;
clearTimeout(timer);
console.log(`[ws] OK — received valid payload for "${opts.name}" (shape: ${valid.shape})`);
ws.close();
resolve(true);
});
ws.on("error", (err) => {
if (settled) return;
settled = true;
clearTimeout(timer);
console.error(`[ws] connection error:`, err);
resolve(false);
});
});
}
+16
View File
@@ -0,0 +1,16 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"noEmit": false
},
"include": ["src/**/*"]
}
+371
View File
@@ -234,6 +234,276 @@ importers:
specifier: ^4.1.7
version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))
local-plugins/wwv-plugin-air-defense:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
devDependencies:
'@types/node':
specifier: ^22.0.0
version: 22.19.19
'@types/react':
specifier: ^19.0.0
version: 19.2.16
typescript:
specifier: ^5.0.0
version: 5.9.3
local-plugins/wwv-plugin-airports:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
local-plugins/wwv-plugin-aviation:
dependencies:
'@worldwideview/wwv-lib-aviation':
specifier: workspace:*
version: link:../../packages/wwv-lib-aviation
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
lucide-react:
specifier: '>=0.576.0'
version: 1.17.0([email protected])
local-plugins/wwv-plugin-borders:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
local-plugins/wwv-plugin-camera:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
lucide-react:
specifier: '>=0.576.0'
version: 1.17.0([email protected])
react:
specifier: '>=18'
version: 19.2.7
local-plugins/wwv-plugin-civil-unrest:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
cesium:
specifier: ^1.139.0
version: 1.142.0
lucide-react:
specifier: ^0.477.0
version: 0.477.0([email protected])
react:
specifier: ^19.0.0
version: 19.2.7
resium:
specifier: 1.19.4
version: 1.19.4([email protected])([email protected]([email protected]))([email protected])
devDependencies:
'@vitejs/plugin-react':
specifier: ^6.0.1
version: 6.0.2([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))
vite:
specifier: ^8.0.8
version: 8.0.16(@types/[email protected])([email protected])([email protected])([email protected])([email protected])
local-plugins/wwv-plugin-conflict-events:
dependencies:
'@worldwideview/wwv-lib-incidents':
specifier: workspace:*
version: link:../../packages/wwv-lib-incidents
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
cesium:
specifier: ^1.139.0
version: 1.142.0
lucide-react:
specifier: ^0.477.0
version: 0.477.0([email protected])
react:
specifier: ^19.0.0
version: 19.2.7
resium:
specifier: 1.19.4
version: 1.19.4([email protected])([email protected]([email protected]))([email protected])
devDependencies:
'@vitejs/plugin-react':
specifier: ^6.0.1
version: 6.0.2([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))
vite:
specifier: ^8.0.8
version: 8.0.16(@types/[email protected])([email protected])([email protected])([email protected])([email protected])
local-plugins/wwv-plugin-cyber-attacks:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
lucide-react:
specifier: ^1.14.0
version: 1.17.0([email protected])
devDependencies:
'@vitejs/plugin-react':
specifier: ^6.0.1
version: 6.0.2([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))
vite:
specifier: ^8.0.8
version: 8.0.16(@types/[email protected])([email protected])([email protected])([email protected])([email protected])
local-plugins/wwv-plugin-earthquakes:
dependencies:
'@worldwideview/wwv-lib-incidents':
specifier: workspace:*
version: link:../../packages/wwv-lib-incidents
'@worldwideview/wwv-plugin-sdk':
specifier: ^1.4.10
version: 1.5.0([email protected])
lucide-react:
specifier: ^1.14.0
version: 1.17.0([email protected])
local-plugins/wwv-plugin-fortiguard:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
devDependencies:
typescript:
specifier: ^5.0.0
version: 5.9.3
local-plugins/wwv-plugin-gps-jamming:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
cesium:
specifier: ^1.139.0
version: 1.142.0
h3-js:
specifier: ^4.4.0
version: 4.4.0
lucide-react:
specifier: ^0.477.0
version: 0.477.0([email protected])
react:
specifier: ^19.0.0
version: 19.2.7
resium:
specifier: 1.19.4
version: 1.19.4([email protected])([email protected]([email protected]))([email protected])
devDependencies:
'@vitejs/plugin-react':
specifier: ^6.0.1
version: 6.0.2([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))
vite:
specifier: ^8.0.8
version: 8.0.16(@types/[email protected])([email protected])([email protected])([email protected])([email protected])
local-plugins/wwv-plugin-international-sanctions:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
lucide-react:
specifier: ^1.14.0
version: 1.17.0([email protected])
devDependencies:
'@vitejs/plugin-react':
specifier: ^6.0.1
version: 6.0.2([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))
vite:
specifier: ^8.0.8
version: 8.0.16(@types/[email protected])([email protected])([email protected])([email protected])([email protected])
local-plugins/wwv-plugin-iranwarlive:
dependencies:
'@worldwideview/wwv-lib-incidents':
specifier: workspace:*
version: link:../../packages/wwv-lib-incidents
'@worldwideview/wwv-plugin-sdk':
specifier: ^1.4.10
version: 1.5.0([email protected])
local-plugins/wwv-plugin-maritime:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
lucide-react:
specifier: '>=0.576.0'
version: 1.17.0([email protected])
local-plugins/wwv-plugin-military-aviation:
dependencies:
'@worldwideview/wwv-lib-aviation':
specifier: workspace:*
version: link:../../packages/wwv-lib-aviation
'@worldwideview/wwv-plugin-sdk':
specifier: ^1.4.10
version: 1.5.0([email protected])
lucide-react:
specifier: '>=0.576.0'
version: 1.17.0([email protected])
local-plugins/wwv-plugin-nz-traffic-cameras:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
devDependencies:
'@types/node':
specifier: ^20.0.0
version: 20.19.41
typescript:
specifier: ^5.0.0
version: 5.9.3
vitest:
specifier: ^4.1.8
version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))
local-plugins/wwv-plugin-satellite:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: ^1.4.10
version: 1.5.0([email protected])
local-plugins/wwv-plugin-wildfire:
dependencies:
'@worldwideview/wwv-plugin-sdk':
specifier: workspace:*
version: link:../../packages/wwv-plugin-sdk
lucide-react:
specifier: '>=0.576.0'
version: 1.17.0([email protected])
packages/wwv-ci-probe:
dependencies:
commander:
specifier: ^14.0.3
version: 14.0.3
ioredis:
specifier: ^5.4.1
version: 5.11.0
ws:
specifier: ^8.18.0
version: 8.21.0
devDependencies:
'@types/node':
specifier: ^25.9.1
version: 25.9.1
'@types/ws':
specifier: ^8.5.13
version: 8.18.1
typescript:
specifier: ^5.0.0
version: 5.9.3
packages/wwv-cli:
dependencies:
commander:
@@ -2056,6 +2326,12 @@ packages:
'@types/[email protected]':
resolution: {integrity: sha512-dRLjCWHYg4oaA77cxO64oO+7JwCwnIzkZPdrrC71jQmQtlhM556pwKo5bUzqvZndkVbeFLIIi+9TC40JNF5hNQ==}
'@types/[email protected]':
resolution: {integrity: sha512-ECymXOukMnOoVkC2bb1Vc/w/836DXncOg5m8Xj1RH7xSHZJWNYY6Zh7EH477vcnD5egKNNfy2RpNOmuChhFPgQ==}
'@types/[email protected]':
resolution: {integrity: sha512-dyh/xO2Fh5bYrfWaaqGrRQQGkNdmYw6AmaAUvYeUMNTWQtvb796ikLdmTchRmOlOiIJ1TDXfWgVx1QkUlQ6Hew==}
'@types/[email protected]':
resolution: {integrity: sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg==}
@@ -3508,6 +3784,10 @@ packages:
[email protected]:
resolution: {integrity: sha512-5ykVn/EXM1hF0XCaWh05VbYvEiOL2lY1kBxZtaYsyvjp7cmWOU1XsAdfQBwClraEofXDT197lFbXOEVMHpvQOg==}
[email protected]:
resolution: {integrity: sha512-DvJh07MhGgY2KcC4OeZc8SSyA+ZXpdvoh6uCzGpoKvWtZxJB+g6VXXC1+eWYkaMIsLz7J/ErhOalHCpcs1KYog==}
engines: {node: '>=4', npm: '>=3', yarn: '>=1.3.0'}
[email protected]:
resolution: {integrity: sha512-Oqluz6zhGX8cyRaTQlFMPw80bSJVG2x/cFb8ZPhUILGgHka9SsokCCOQgpveePerqidZOrT14ipqfJb7ILcW5Q==}
engines: {node: '>=4'}
@@ -4061,6 +4341,11 @@ packages:
resolution: {integrity: sha512-DqC6n3QQ77zdFpCMASA1a3Jlb64Hv2N2DciFGkO/4L9+q/IpIAuRlKOvCXabtRW6cQf8usbmM6BE/TOPysCdIA==}
engines: {bun: '>=1.0.0', deno: '>=1.30.0', node: '>=8.0.0'}
[email protected]:
resolution: {integrity: sha512-yCf7aYxerFZAbd8jHJxjwe1j7jEMPptjnaOqdYeirFnEy85cNR3/L+o0I875CYFYya+eEVzZSbNuRk8BZPDpVw==}
peerDependencies:
react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
[email protected]:
resolution: {integrity: sha512-9FA9evdox/JQL5PT57fdA1x/yg8T7knJ98+zjTL3UfKza6pflQUUh3XtaQIHKvnsJw1lmsEyHVlt5jchYxOQ5w==}
peerDependencies:
@@ -4712,6 +4997,14 @@ packages:
resolution: {integrity: sha512-QT7FVMXfWOYFbeRBF6nu+I6tr2Tf3u0q8RIEjNob/heKY/nh7drD/k7eeMFmSQgnTtCzLDcCu/XEnpW2wk4xCQ==}
engines: {node: '>=9.3.0 || >=8.10.0 <9.0.0'}
[email protected]:
resolution: {integrity: sha512-RW0ffHlQUbgqbc0jDaF2Dnor/GKbiz5s5AKdamEKxMJfxiwQNgtgfaKK7UvafFpX25Y2J4DZP1MclTlEQ/5YUw==}
engines: {node: '>=20.19.0'}
peerDependencies:
cesium: 1.x
react: '>=18.2.0'
react-dom: '>=18.2.0'
[email protected]:
resolution: {integrity: sha512-pR+ySBudmCstgYOBFY+qcPQt0+xPmsdhSkD3u7JBfaiHcx/pxyuigjYoL0ET7Ak2a2uZ7jEu47cdZKThZx8A5w==}
engines: {node: '>=20.19.0'}
@@ -5265,6 +5558,9 @@ packages:
[email protected]:
resolution: {integrity: sha512-DXtD3ZtEQzc7M8m4cXotyHR+FAS18C64asBYY5vqZexfYryNNnDc02W4hKg3rdQuqOYas1jkseX0+nZXjTXnvQ==}
[email protected]:
resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
[email protected]:
resolution: {integrity: sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==}
@@ -7324,6 +7620,14 @@ snapshots:
'@types/[email protected]': {}
'@types/[email protected]':
dependencies:
undici-types: 6.21.0
'@types/[email protected]':
dependencies:
undici-types: 6.21.0
'@types/[email protected]':
dependencies:
undici-types: 7.24.6
@@ -7548,6 +7852,14 @@ snapshots:
chai: 6.2.2
tinyrainbow: 3.1.0
'@vitest/[email protected]([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))':
dependencies:
'@vitest/spy': 4.1.8
estree-walker: 3.0.3
magic-string: 0.30.21
optionalDependencies:
vite: 8.0.16(@types/[email protected])([email protected])([email protected])([email protected])([email protected])
'@vitest/[email protected]([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))':
dependencies:
'@vitest/spy': 4.1.8
@@ -9060,6 +9372,8 @@ snapshots:
[email protected]: {}
[email protected]: {}
[email protected]: {}
[email protected]:
@@ -9598,6 +9912,10 @@ snapshots:
[email protected]: {}
[email protected]([email protected]):
dependencies:
react: 19.2.7
[email protected]([email protected]):
dependencies:
react: 19.2.7
@@ -10269,6 +10587,12 @@ snapshots:
transitivePeerDependencies:
- supports-color
[email protected]([email protected])([email protected]([email protected]))([email protected]):
dependencies:
cesium: 1.142.0
react: 19.2.7
react-dom: 19.2.7([email protected])
[email protected]([email protected])([email protected]([email protected]))([email protected]):
dependencies:
cesium: 1.142.0
@@ -10912,6 +11236,8 @@ snapshots:
[email protected]: {}
[email protected]: {}
[email protected]: {}
[email protected]: {}
@@ -10994,6 +11320,21 @@ snapshots:
'@vimeo/player': 2.29.0
media-played-ranges-mixin: 0.1.0
[email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]):
dependencies:
lightningcss: 1.32.0
picomatch: 4.0.4
postcss: 8.5.15
rolldown: 1.0.3
tinyglobby: 0.2.17
optionalDependencies:
'@types/node': 20.19.41
esbuild: 0.28.0
fsevents: 2.3.3
jiti: 2.7.0
terser: 5.48.0
tsx: 4.22.4
[email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]):
dependencies:
lightningcss: 1.32.0
@@ -11009,6 +11350,36 @@ snapshots:
terser: 5.48.0
tsx: 4.22.4
[email protected](@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected])):
dependencies:
'@vitest/expect': 4.1.8
'@vitest/mocker': 4.1.8([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))
'@vitest/pretty-format': 4.1.8
'@vitest/runner': 4.1.8
'@vitest/snapshot': 4.1.8
'@vitest/spy': 4.1.8
'@vitest/utils': 4.1.8
es-module-lexer: 2.1.0
expect-type: 1.3.0
magic-string: 0.30.21
obug: 2.1.1
pathe: 2.0.3
picomatch: 4.0.4
std-env: 4.1.0
tinybench: 2.9.0
tinyexec: 1.2.4
tinyglobby: 0.2.17
tinyrainbow: 3.1.0
vite: 8.0.16(@types/[email protected])([email protected])([email protected])([email protected])([email protected])
why-is-node-running: 2.3.0
optionalDependencies:
'@opentelemetry/api': 1.9.1
'@types/node': 20.19.41
'@vitest/coverage-v8': 4.1.8([email protected])
jsdom: 28.1.0
transitivePeerDependencies:
- msw
[email protected](@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected])):
dependencies:
'@vitest/expect': 4.1.8
+2 -2
View File
@@ -15,7 +15,7 @@
import type { PluginDataSnapshot } from "@/lib/data-query/types";
import type { RegionOptions } from "@/lib/data-query/types";
import type { FilterDefinition } from "@/core/plugins/PluginTypes";
import { getAllPluginSnapshots } from "@/lib/data-query/service";
import { getAllPluginSnapshots, getEngineUrl } from "@/lib/data-query/service";
import { getLocalSourceIds } from "@/lib/data-query/localSources";
import { readActiveSessions, readGlobeState } from "@/lib/globeStateStore";
import { readSessionCatalog } from "@/lib/mcpSessionCatalog";
@@ -112,7 +112,7 @@ export interface ListStreamingPluginsResult {
* are not blocked waiting for a slow engine.
*/
async function probeEngineReachable(): Promise<boolean> {
const engineUrl = (process.env.WWV_DATA_ENGINE_URL ?? "http://localhost:5001") + "/manifest";
const engineUrl = getEngineUrl() + "/manifest";
try {
const res = await fetch(engineUrl, { signal: AbortSignal.timeout(2000) });
return res.ok;
+1 -1
View File
@@ -64,7 +64,7 @@ describe("resolveEngineUrl", () => {
await fetchLocalEngineManifest();
const url = resolveEngineUrl("plugin-local");
expect(url).toContain("localhost:5000/stream");
expect(url).toMatch(/ws:\/\/localhost:\d+\/stream/);
});
it("should fall back to plugin's custom streamUrl if not local", () => {
@@ -0,0 +1,46 @@
// src/core/data/__tests__/engineManifest.test.ts
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { fetchLocalEngineManifest, resetManifestCache } from '../engineManifest';
const mockFetch = vi.fn();
describe('fetchLocalEngineManifest', () => {
beforeEach(() => {
resetManifestCache();
mockFetch.mockReset();
vi.stubGlobal('fetch', mockFetch);
});
afterEach(() => {
vi.unstubAllGlobals();
delete process.env.NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL;
});
it('probes port 5000 when NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL is not set', async () => {
mockFetch.mockResolvedValue({ ok: false } as Response);
await fetchLocalEngineManifest();
expect(mockFetch).toHaveBeenCalledWith(
expect.stringContaining(':5000/manifest'),
expect.any(Object)
);
});
it('probes the env-configured URL when NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL is set', async () => {
process.env.NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL = 'http://localhost:5003';
mockFetch.mockResolvedValue({ ok: false } as Response);
await fetchLocalEngineManifest();
expect(mockFetch).toHaveBeenCalledWith(
expect.stringContaining(':5003/manifest'),
expect.any(Object)
);
});
it('returns plugin list when engine responds successfully', async () => {
mockFetch.mockResolvedValue({
ok: true,
json: async () => ({ plugins: ['flight-tracker', 'ais-tracker'] }),
} as Response);
const result = await fetchLocalEngineManifest();
expect(result).toEqual(['flight-tracker', 'ais-tracker']);
});
});
@@ -0,0 +1,42 @@
// src/core/data/__tests__/resolveEngineUrl.test.ts
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
vi.mock('../engineManifest', () => ({
localEngineHasPlugin: vi.fn(),
}));
vi.mock('@/core/plugins/PluginManager', () => ({
pluginManager: {
getPlugin: vi.fn().mockReturnValue(null),
getManifest: vi.fn().mockReturnValue(null),
},
}));
import { resolveEngineUrl } from '../resolveEngineUrl';
import { localEngineHasPlugin } from '../engineManifest';
describe('resolveEngineUrl', () => {
beforeEach(() => {
vi.mocked(localEngineHasPlugin).mockReset();
});
afterEach(() => {
delete process.env.NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL;
});
it('uses port 5000 by default when no env var is set', () => {
vi.mocked(localEngineHasPlugin).mockReturnValue(true);
expect(resolveEngineUrl('test-plugin')).toContain(':5000/stream');
});
it('uses the configured URL when NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL is set', () => {
process.env.NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL = 'http://localhost:5003';
vi.mocked(localEngineHasPlugin).mockReturnValue(true);
expect(resolveEngineUrl('test-plugin')).toContain(':5003/stream');
});
it('falls back to cloud URL when local engine does not have the plugin', () => {
vi.mocked(localEngineHasPlugin).mockReturnValue(false);
expect(resolveEngineUrl('test-plugin')).toContain('worldwideview.dev');
});
});
+5 -8
View File
@@ -8,16 +8,13 @@ let manifestFetched = false;
/**
* Resolve the base URL of the local data engine.
*
* Always checks localhost:5000 — the port docker-compose.yml binds for
* wwv-data-engine. NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL is intentionally
* NOT used here: that variable belongs to each plugin's own declared engine
* URL (production, third-party, etc.) and must not poison local detection.
* Mixing the two caused the production engine to be reported as "local".
* Reads NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL (default http://localhost:5000).
* Only set this in .env.local for local development — never in production.
* Each plugin owns its own streamUrl; this variable is only for routing
* locally-developed plugin seeders to a local engine instance.
*/
function getLocalEngineBase() {
const port = process.env.NEXT_PUBLIC_WWV_LOCAL_ENGINE_PORT || '5000';
if (typeof window === "undefined") return `http://localhost:${port}`;
return `${window.location.protocol}//${window.location.hostname}:${port}`;
return process.env.NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL ?? 'http://localhost:5000';
}
/**
+5 -5
View File
@@ -20,19 +20,19 @@ function toWsStreamUrl(url: string): string {
const DEFAULT_ENGINE_URL = toWsStreamUrl(RAW_ENGINE_URL);
function getLocalWsUrl() {
const port = process.env.NEXT_PUBLIC_WWV_LOCAL_ENGINE_PORT || '5000';
if (typeof window === "undefined") return `ws://localhost:${port}/stream`;
return `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.hostname}:${port}/stream`;
const base = process.env.NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL ?? 'http://localhost:5000';
const ws = base.replace(/^https:\/\//, 'wss://').replace(/^http:\/\//, 'ws://');
return ws.replace(/\/+$/, '') + '/stream';
}
/**
* Resolves the WebSocket engine URL for a given plugin.
*
* Resolution order:
* 1. Local engine (if running at localhost:5000 and has this plugin's seeder)
* 1. Local engine (if running at NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL and has this plugin's seeder)
* 2. Plugin's ServerPluginConfig.streamUrl (code-based plugins)
* 3. Plugin's PluginManifest.dataSource.streamUrl (manifest-based plugins)
* 4. NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL env var
* 5. Fallback: wss://dataengine.worldwideview.dev/stream (cloud)
* 5. Fallback: wss://dataenginev2.worldwideview.dev/stream (cloud)
*/
export function resolveEngineUrl(pluginId: string): string {
// 1. Local engine (split-routing) - PRIORITY #1
+4 -4
View File
@@ -70,18 +70,18 @@ export async function injectHostGlobals(): Promise<void> {
};
// REST Engine URL (Fallback)
// Note: Local Docker-based engine interception (localhost:5000) happens dynamically inside
// resolveEngineUrl.ts during plugin routing. These variables act as global fallbacks.
// Note: Local engine interception (via NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL) happens dynamically
// inside resolveEngineUrl.ts during plugin routing. These variables act as global fallbacks.
const envDataEngine = process.env.NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL;
if (envDataEngine) {
(globalThis as Record<string, unknown>).__WWV_ENGINE_URL__ = envDataEngine;
} else {
// ALWAYS default to the cloud engine unless explicitly told otherwise via env var
(globalThis as Record<string, unknown>).__WWV_ENGINE_URL__ = 'https://dataengine.worldwideview.dev';
(globalThis as Record<string, unknown>).__WWV_ENGINE_URL__ = 'https://dataenginev2.worldwideview.dev';
}
// WebSocket Engine URL
const fallbackWs = envDataEngine ? `${envDataEngine.replace(/^http/, "ws")}/stream` : 'wss://dataengine.worldwideview.dev/stream';
const fallbackWs = envDataEngine ? `${envDataEngine.replace(/^http/, "ws")}/stream` : 'wss://dataenginev2.worldwideview.dev/stream';
(globalThis as Record<string, unknown>).__WWV_WS_ENGINE_URL__ = fallbackWs;
console.log("[HostGlobals] React and SDK injected for dynamic plugins");
@@ -123,7 +123,7 @@ describe("DeclarativePlugin", () => {
getCurrentTime: () => new Date(),
env: {},
edition: "local",
getEngineUrl: () => "http://localhost:5001",
getEngineUrl: () => "http://test-engine/",
});
const entities = await plugin.fetch({ start: new Date(), end: new Date() });
+5 -1
View File
@@ -12,7 +12,11 @@ import type { FilterValue } from "@/core/plugins/PluginTypes";
import { hasLocalSource, resolveLocalSnapshot, getLocalSourceIds } from "./localSources";
export function getEngineUrl(): string {
return process.env.WWV_DATA_ENGINE_URL ?? "http://localhost:5001";
// WWV_DATA_ENGINE_URL = production (docker-compose, server-side only)
// NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL = local dev override
return process.env.WWV_DATA_ENGINE_URL
?? process.env.NEXT_PUBLIC_WWV_LOCAL_ENGINE_URL
?? "http://localhost:5000";
}
function normalizeEntity(raw: unknown): GeoEntity | null {