Compare commits

..
Author SHA1 Message Date
Silvertakana 060eedaaea Merge branch 'main' into refactor/high-quality-standards 2026-05-18 11:07:33 +12:00
Antigravity AI 4ecb9f97e8 fix(eslint): resolve react-hook immutability and cascading render violations 2026-05-17 16:19:20 +12:00
Silvertakana fe4d4ea240 Merge branch 'main' into refactor/high-quality-standards 2026-05-16 18:02:11 +12:00
Antigravity AI 323d25e482 refactor(core): harden typescript and fix linting violations
This commit addresses the remaining any types and linting errors across the core engine.
2026-05-16 18:00:35 +12:00
Antigravity AI e901e62695 Merge remote-tracking branch 'origin/main' into refactor/high-quality-standards
# Conflicts:
#	package.json
#	src/components/layout/AppShell.tsx
2026-05-16 15:25:17 +12:00
Antigravity AI 74478205d4 fix(layout): restore bottom panel positioning and transition styling
This commit corrects the missing bottom panel issue by resolving CSS aggregation errors and fixing transition logic. The version is bumped to 2.15.5.
2026-05-16 15:19:33 +12:00
Antigravity AI e9f3736a1b fix: restore BottomPanelManager in AppShell and fix vitest config 2026-05-16 15:12:33 +12:00
Silvertakana 01c3e3594a Merge branch 'main' into refactor/high-quality-standards 2026-05-16 13:02:55 +12:00
Antigravity AI 9822882779 chore: resolve lockfile conflict 2026-05-16 12:10:40 +12:00
Antigravity AI 6e22d38933 Merge remote-tracking branch 'origin/main' into refactor/high-quality-standards
# Conflicts:
#	package.json
#	src/components/panels/GraphicsSettings.tsx
#	src/core/globe/useImageryManager.ts
2026-05-16 12:10:04 +12:00
Antigravity AI b1505df706 refactor(core): decouple PluginManager and fix rendering invariants
- refactor(core): Replace Zustand mutations in PluginManager with DataBus events (Patch)
- refactor(sdk): Add layerLoadingChanged, pluginError, pluginUnregistered to DataBusEvents (Patch)
- refactor(ui): Subscribe to new DataBus events in DataBusSubscriber (Patch)
- fix(plugins): Remove size from BaseAviationPlugin to fix model rendering clipping (Patch)
- fix(plugins): Migrate BaseIncidentPlugin from size to iconScale to fix billboard clipping (Patch)
2026-05-16 12:06:49 +12:00
Antigravity AI d2c29aca00 fix(types): resolve PluginManager type errors 2026-05-15 22:32:14 +12:00
Antigravity AI 01892c051c refactor(plugins): decouple GeoJSON plugin and implement data bus lifecycle
- feat(sdk): [Minor] Added dynamicPluginCreate, dynamicPluginRemove, and pluginUnregistered to DataBusEvents.

- feat(core): [Minor] Implemented unregisterPlugin in PluginManager.ts for automated IndexedDB caching cleanup and polling teardown.

- feat(core): [Minor] Added removeLayer to layersSlice.ts to support safe removal of plugin states.

- refactor(plugins): [Patch] Refactored useGeoJsonImport.ts and ImportedLayerList.tsx to decouple from direct manager imports, utilizing DataBus for lifecycle events.

- refactor(core): [Patch] Added pluginUnregistered listener to DataBusSubscriber.tsx to handle state and cache cleanup synchronously via event.
2026-05-15 22:10:27 +12:00
Antigravity AI 9aaa143988 fix(ci): Stabilize github actions and resolve test failures
- fix(tests): update WsClient mock to use standard function for Vitest constructor compatibility

- fix(db): correct PrismaClient import path to use generated output directory

- fix(e2e): add predev database boot step to playwright CI workflow

- chore: sync pnpm-lock.yaml after merge conflict resolution
2026-05-15 22:09:38 +12:00
SilvertakanaandCopilot Autofix powered by AI 2447f1d500 Potential fix for pull request finding 'CodeQL / Incomplete URL substring sanitization'
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
2026-05-15 22:08:51 +12:00
SilvertakanaandCopilot Autofix powered by AI ef19fd75c9 Potential fix for pull request finding 'CodeQL / Incomplete URL substring sanitization'
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
2026-05-15 22:08:51 +12:00
SilvertakanaandCopilot Autofix powered by AI 643028c6a3 Potential fix for pull request finding 'CodeQL / Incomplete URL substring sanitization'
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
2026-05-15 22:08:51 +12:00
Antigravity AI 3afdbf92bc chore(merge): resolve conflicts, fix mockWs error, and apply refactor standards 2026-05-15 22:08:34 +12:00
29 changed files with 850 additions and 1719 deletions

No files matched your search

-17
View File
@@ -23,23 +23,6 @@ When creating primitive objects:
- **Points** (`PointPrimitive`): Can use `size`, `outlineWidth`, and `outlineColor`.
- **Billboards** (`BillboardGraphics` for SVG/Icons): Must **NOT** use `size`, `outlineWidth`, or `outlineColor`. You must use `iconScale` to resize them. Mixing point properties on billboards causes severe shader clipping.
## Sizing Conventions
| Entity type | Knob | Default | Typical band | Source |
|-------------|--------------|------------------------------------|------------------|--------|
| `point` | `size` | `8` desktop / `12` mobile | 5–12 | `src/core/globe/primitiveOps.ts` (`defaultPointSize`) |
| `billboard` | `iconScale` | `0.7` (`DEFAULT_BILLBOARD_SCALE`) | 0.6–0.9 | `src/core/globe/primitiveOps.ts` (`DEFAULT_BILLBOARD_SCALE`) |
| `model` | `modelScale` | `1.0` + `modelMinPixelSize` | varies per asset | `src/core/globe/ModelManager.ts`, `src/core/globe/hooks/useModelRendering.ts` |
> [!IMPORTANT]
> **Cross-plugin parity rule.** If your plugin renders alongside maritime / aviation / military-aviation on the globe, **leave `iconScale` unset** (or pick a value inside 0.6–0.9). A value below 0.5 will look visibly broken next to peer plugins. A value above 1.0 will dominate the globe.
> [!CAUTION]
> **Silent-ignore footgun.** `size` is a `PointPrimitive` property. If you set `size` on a `billboard` entity it is **silently dropped** — Cesium does not error and the billboard simply renders at `DEFAULT_BILLBOARD_SCALE`. When converting a point plugin to a billboard plugin, replace `size: N` with `iconScale: ~N/16` (the canvas base is `getBaseSize() = 48px` desktop) — do not delete it and do not translate it literally as `iconScale: N/10`. This footgun has shipped at least once (see commit history on `local-plugins/wwv-plugin-satellite`).
> [!NOTE]
> **Backdrop stack.** `createSvgIconUrl` (in the SDK) already wraps the icon in a 44×44 SVG with a dark backdrop circle. `src/core/globe/iconUpscaler.ts` then redraws onto a 48px canvas with **another** backdrop circle (`DEFAULT_BG = "rgba(15, 23, 42, 0.55)"`). Pass `background: false` to `createSvgIconUrl` when you want only the host's circle. Don't add a third backdrop in your own SVG.
## Performance Culling
> [!TIP]
-57
View File
@@ -29,60 +29,3 @@ In production, the `wwv-data-engine-v2` does NOT mount the local file system. In
## 5. Namespace Separation Rule
To prevent collisions and `404` or `ERR_MODULE_NOT_FOUND` errors, seeders **MUST NOT** exist simultaneously in both the community (`wwv-seeders-community`) and private (`wwv-seeders-private`) repositories. Namespace overlaps will cause module resolution failures when the V2 engine attempts to load them. Private seeders have priority.
## 6. Plugin ID Contract — Single Source of Truth
> **See ADR-0002** (`docs/architecture/decisions/adr-0002-seeder-exported-name-as-canonical-plugin-id.md`) for full rationale and alternatives considered.
**Rule:** Every seeder MUST export a `name` field that exactly matches the corresponding frontend plugin's `id` field (kebab-case).
```typescript
// ✅ Correct — seeder src/index.ts
export default {
name: "gps-jamming", // MUST equal the frontend plugin id
cron: "0 0 * * *",
fn: seedGpsJam,
};
// ❌ Wrong — do not use folder names, camelCase, or abbreviations
export default {
name: "gpsjam", // mismatch — frontend plugin is "gps-jamming"
...
};
```
**How the engine uses it:** `seeder-loader.ts` reads each seeder's exported `name` as the canonical plugin ID. This ID is used for:
- The `/manifest` endpoint's `plugins` array (what the frontend checks for local routing)
- WebSocket data messages (`pluginId` field)
- Redis keys (`data:<name>:live`)
- Scheduler logs
**Folder names are organizational only.** The engine warns at startup if `toKebabCase(folderName) !== seeder.name`, but this is cosmetic — the seeder's exported `name` always wins. Folder renames are a future cleanup, not a functional requirement.
**Frontend side:** `resolveEngineUrl(pluginId)` checks `localEngineHasPlugin(pluginId)` against the manifest. If the names match, the plugin routes to `ws://localhost:5000/stream`. No alias maps or translation layers are needed.
## 7. WebSocket Payload Format Contract
When a seeder calls `setLiveSnapshot(pluginId, payload, ttl)`, the engine broadcasts:
```json
{ "type": "data", "pluginId": "my-plugin", "payload": <whatever you passed> }
```
**`WsClient` payload handling rules (in order):**
1. Plugin has `mapWebsocketPayload(payload, existingEntities)` → called with raw payload → must return `GeoEntity[]`
2. No handler + payload **is** a flat `GeoEntity[]` array → used directly (timestamp normalized)
3. No handler + payload is **any other object** → **silently dropped** with a console warning
This means:
| Seeder sends | Frontend needs | Notes |
|---|---|---|
| `[{id, latitude, longitude, ...}]` | Nothing (WsClient handles) | ✅ Simplest for basic point data |
| `{ items: [{...}] }` | `mapWebsocketPayload` | Standard engine snapshot format |
| `{ satellites: [{...}] }` | `mapWebsocketPayload` | Named-collection format |
**Recommendation:** If the seeder and frontend plugin are developed together, use a **flat `GeoEntity[]` array** — no `mapWebsocketPayload` needed. Use named objects (e.g. `{ satellites: [...] }`) only when the seeder data has a domain-specific shape worth preserving; in that case you **must** implement `mapWebsocketPayload` on the frontend plugin.
> [!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.
-12
View File
@@ -16,18 +16,6 @@ Plugins from the marketplace use the `bundle` format and are imported at runtime
- `pluginManager.loadFromManifest()` validates and registers these plugins.
- Ensure any schema changes to the marketplace tables follow the `database-migrations.md` rule.
## 4. Fresh-Install Seeding
Fresh installs (no rows in `InstalledPlugin`) auto-seed a starter set so the globe isn't empty on day one. The source of truth is the **signed verified registry** (`marketplace.worldwideview.dev/api/registry`, loaded by `registryClient.getVerifiedPluginIds()`).
- **No hard-coded plugin lists.** Publishing a plugin to the verified registry is what makes it part of the fresh-install starter set.
- **Idempotent**: a `defaults_seeded` row in the `Setting` table prevents re-runs. If the registry is unreachable on first attempt, the guard is NOT set — the next request retries.
- **Existing instances** with `defaults_seeded=true` are untouched. To pull in newly-verified plugins, users install via the marketplace UI.
- **Demo edition** uses an independent path (`NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS` env var, handled in `AppShell.tsx` and `useMarketplaceSync.ts`) — not this seeder.
> [!CAUTION]
> Do not reintroduce a static `DEFAULT_PLUGIN_IDS` constant or any other hard-coded plugin list. That drifted from npm reality, caused 404s for unpublished IDs, and conflated "verified" with "auto-installed."
## Current Implementation State
-80
View File
@@ -17,59 +17,6 @@ A valid plugin class MUST provide:
3. `renderEntity(GeoEntity)` to determine visual style.
4. `getPollingInterval()` (defaults fallback securely to standard store config).
## Plugin Data Delivery Types
Plugins receive entity data in one of three modes. Choose the right mode before writing code — mixing them causes silent data loss.
| Mode | `getPollingInterval()` | `fetch()` | `mapWebsocketPayload()` | When to use |
|---|---|---|---|---|
| **REST-only** | `> 0` (ms) | Returns `GeoEntity[]` | Not needed | Static or slow-changing data (< every 30s). No seeder required. |
| **WebSocket-only** | `0` | Return `[]` immediately | **Required** if seeder sends object payload | Live-streaming data from a seeder (satellites, AIS, flights) |
| **Hybrid** | `> 0` | Returns initial snapshot | **Required** if seeder sends object payload | Needs both immediate data on load AND live updates |
### WebSocket-Only Pattern (most live-data plugins)
```typescript
getPollingInterval(): number {
return 0; // WS-only — do NOT call REST on enable
}
async fetch(_timeRange: TimeRange): Promise<GeoEntity[]> {
return []; // Initial data arrives via mapWebsocketPayload within seconds
}
mapWebsocketPayload(payload: any, _existingEntities: GeoEntity[]): GeoEntity[] {
// Transform raw engine payload → GeoEntity[]
// payload shape depends on what the seeder calls setLiveSnapshot() with
const items = payload?.items ?? (Array.isArray(payload) ? payload : []);
return items.map((item: any): GeoEntity => ({
id: `my-plugin-${item.id}`,
pluginId: "my-plugin",
latitude: item.lat,
longitude: item.lon,
altitude: item.alt ?? 0,
timestamp: new Date(),
label: item.name,
properties: item,
}));
}
```
> [!WARNING]
> If `getPollingInterval()` returns `0` but the seeder sends an object payload, you **MUST** implement `mapWebsocketPayload`. Without it, `WsClient` drops the data silently. See `data-engine-architecture.md §7` for the exact rule.
### `mapWebsocketPayload` Signature
```typescript
mapWebsocketPayload(payload: any, existingEntities: GeoEntity[]): GeoEntity[]
```
- `payload` — raw value from `setLiveSnapshot()` in the seeder (whatever shape the seeder stores)
- `existingEntities` — current entities in the store for this plugin (use for incremental updates)
- Must return a **complete replacement** `GeoEntity[]` (not a diff)
---
## Plugin Architectures (Manifest Formats)
Plugins are defined via `PluginManifest` and operate on an **All-Bundle** architecture.
@@ -105,33 +52,6 @@ All plugins MUST define their identity and compatibility via a `"worldwideview"`
}
```
### `peerDependencies` Rule for npm-Published Plugins
Plugins published to npm **MUST** declare the following as `peerDependencies`, not `dependencies`:
```json
{
"peerDependencies": {
"@worldwideview/wwv-plugin-sdk": "*",
"react": ">=19",
"lucide-react": "*"
}
}
```
Also peer (never bundle): `react-dom`, `cesium`, `resium`, `zustand`.
Bundling these causes multiple React instances in the host app, breaking hooks (`Invalid hook call` at runtime).
### File Extension Rule
- Files containing **JSX** (any `<Component />` syntax, `return (<div>...)`) → must use `.tsx`
- Files with no JSX (pure TypeScript, even importing React types) → use `.ts`
This is enforced by the TypeScript compiler. A `.ts` file with JSX will fail to build.
---
## The Registration Pipeline
> [!NOTE]
+1 -23
View File
@@ -26,29 +26,7 @@ When an AI agent or developer is executing CLI commands via tools in this projec
- **Rule**: NEVER use the `&&` operator to chain commands in PowerShell. It will result in parser errors.
- **Resolution**: Use sequential execution, run commands separately, or use PowerShell-safe chaining like `; if ($?) { }`.
## 5. UTF-8 BOM in `package.json` Crashing Node Scripts
If `pnpm dev` (or any workspace script) dies with `SyntaxError: Unexpected token '', "{ ..." is not valid JSON`, the offending file has a UTF-8 BOM (`EF BB BF`) at byte 0.
- **Root Cause**: Windows PowerShell 5.1 `Set-Content -Encoding UTF8` and Notepad's "Save as UTF-8" both emit a BOM. Node's `fs.readFileSync(p, 'utf-8')` does NOT strip it, so `JSON.parse` rejects the leading ``. pnpm/npm strip BOMs silently, which is why this only blows up in custom workspace scripts.
- **Diagnosis** (PowerShell):
```powershell
Get-ChildItem local-plugins -Directory | ForEach-Object {
$p = Join-Path $_.FullName 'package.json'
if (Test-Path $p) {
$b = [System.IO.File]::ReadAllBytes($p) | Select-Object -First 3
if ($b[0] -eq 0xEF -and $b[1] -eq 0xBB -and $b[2] -eq 0xBF) { $_.Name }
}
}
```
- **Fix at the seam (preferred)**: In any script that parses externally-authored JSON, strip the BOM before parsing. See `readJsonFile()` in [`scripts/sync-local-plugins.mjs`](../../scripts/sync-local-plugins.mjs) as the canonical helper:
```js
let text = fs.readFileSync(filePath, "utf-8");
if (text.charCodeAt(0) === 0xFEFF) text = text.slice(1);
return JSON.parse(text);
```
- **Clean existing files** (one-time): rewrite each file without its first 3 bytes via `[System.IO.File]::WriteAllBytes($p, $bytes[3..($bytes.Length - 1)])`.
- **Prevention**: When authoring files via PowerShell, use `Out-File -Encoding utf8NoBOM` (PS 7+) or `[System.IO.File]::WriteAllText($p, $text, [System.Text.UTF8Encoding]::new($false))` (any PS). Never edit `package.json` in Notepad.
## 6. Next.js vs. Undici Fetch Type Mismatches
## 5. Next.js vs. Undici Fetch Type Mismatches
When implementing SSRF protections (e.g., DNS IP Pinning via custom `Dispatcher`), you will likely use `undici.Agent`.
- **Root Cause**: Passing global Next.js `RequestInit` options directly into `undici.fetch` will throw strict TypeScript errors because the `BodyInit` and `RequestCache` signatures differ, and `dns.lookup` returns a generic `number` instead of exactly `4 | 6` for IP families.
- **Resolution**: Strip out Next.js specific keys, explicitly cast `body` as `any`, and explicitly type `resolvedFamily: number` when interfacing between Next.js request streams and the `undici` library.
@@ -38,7 +38,7 @@ Moves a WorldWideView plugin from the old `packages/` monorepo location (or the
> ```
> Example: `node scripts/migrate-plugin.mjs gps-jamming`
>
> The script will automatically copy the frontend plugin, inject peerDependencies, refactor `index.tsx` routing, and fix the backend seeder's build settings and `SEEDERS_DIR` paths. (Fresh-install seeding no longer involves a hard-coded list — once published to npm with a valid `worldwideview` block, the plugin is registered via the signed verified registry.)
> The script will automatically copy the frontend plugin, inject peerDependencies, refactor `index.tsx` routing, fix the backend seeder's build settings and `SEEDERS_DIR` paths, and register the plugin in `defaultPlugins.ts`.
> **You still need to run `pnpm install` and verify the builds manually as described below.**
> [!IMPORTANT]
@@ -29,15 +29,20 @@ A WorldWideView plugin is a self-contained data source that renders geospatial e
## Architecture Decision
```
Does it need live external API data?
├── NO → Static GeoJSON plugin (wwvStaticCompiler in vite.config.ts)
│ No seeder needed. Place data in data/data.json.
└── YES → Does it update more often than every 30s?
├── NO → Cron Seeder (engine, registerSeeder with cron string)
│ getPollingInterval() = 0, mapWebsocketPayload() required
└── YES → Init Seeder (engine, registerSeeder with init function)
getPollingInterval() = 0, mapWebsocketPayload() required
```dot
digraph plugin_type {
rankdir=TB;
node [shape=diamond];
"Does it need live\nexternal API data?" -> "Is polling\nfrequency > 30s?" [label="yes"];
"Does it need live\nexternal API data?" -> "Static GeoJSON\n(wwvStaticCompiler)" [label="no"];
"Is polling\nfrequency > 30s?" -> "Cron Seeder\n(engine)" [label="yes"];
"Is polling\nfrequency > 30s?" -> "Init Seeder\n(engine)" [label="no"];
"Static GeoJSON\n(wwvStaticCompiler)" [shape=box];
"Cron Seeder\n(engine)" [shape=box];
"Init Seeder\n(engine)" [shape=box];
}
```
---
@@ -141,7 +146,7 @@ export default class WildfiresPlugin implements WorldPlugin {
| `getLayerConfig()` | Layer appearance (color, clustering, max entities) |
| `renderEntity(entity)` | Per-entity Cesium rendering options |
**Optional (but `mapWebsocketPayload` is REQUIRED for WS-only plugins with object payloads):**
**Optional:**
| Method | Purpose |
|---|---|
@@ -153,7 +158,7 @@ export default class WildfiresPlugin implements WorldPlugin {
| `getDetailComponent()` | Custom detail panel for selected entity |
| `getSettingsComponent()` | Plugin settings UI |
| `getGlobeComponent()` | React component injected into globe view |
| `mapWebsocketPayload(payload, existing)` | **Required if seeder payload is an object** (not a flat array). Transforms raw engine payload → `GeoEntity[]`. Without it, `WsClient` drops object payloads silently. |
| `mapWebsocketPayload(payload, existing)` | Transform raw WS data into `GeoEntity[]` |
| `requiresConfiguration(settings)` | Return `true` if plugin needs setup first |
### 1.3 Package Metadata
@@ -513,30 +518,14 @@ export default class IssPlugin implements WorldPlugin {
destroy(): void {}
async fetch(_timeRange: TimeRange): Promise<GeoEntity[]> {
return []; // WS-only — data arrives via mapWebsocketPayload
async fetch(timeRange: TimeRange): Promise<GeoEntity[]> {
return []; // WS-only plugin
}
getPollingInterval(): number {
return 0; // WS-only
}
// REQUIRED: seeder sends { source, fetchedAt, items: [...], totalCount } (an object).
// Without this, WsClient drops the payload silently — the globe stays empty.
mapWebsocketPayload(payload: any, _existingEntities: GeoEntity[]): GeoEntity[] {
const items: any[] = payload?.items ?? (Array.isArray(payload) ? payload : []);
return items.map((item: any): GeoEntity => ({
id: `iss-${item.id}`,
pluginId: "iss",
latitude: item.lat,
longitude: item.lon,
altitude: item.alt ?? 0,
timestamp: new Date(),
label: "International Space Station",
properties: { speed: item.speed },
}));
}
getLayerConfig(): LayerConfig {
return {
color: "#ffffff",
@@ -655,9 +644,7 @@ Categories are **lowercase**: `"aviation"` not `"Aviation"`, `"natural-disaster"
- [ ] **Engine:** Seeder file in `wwv-seeders/src/seeders/<name>.ts` (or private repo)
- [ ] **Engine:** `registerSeeder({ name })` matches frontend plugin `id`
- [ ] **Engine:** Calls `setLiveSnapshot()` with correct plugin ID key
- [ ] **Engine:** Seeder payload is either a flat `GeoEntity[]` array OR plugin implements `mapWebsocketPayload` (any other object is silently dropped by WsClient)
- [ ] **Frontend (WS-only):** `getPollingInterval()` returns `0` and `fetch()` returns `[]`
- [ ] **Frontend (WS-only):** `mapWebsocketPayload(payload, existingEntities)` implemented if seeder sends an object
- [ ] **Engine:** Data shape is an object with `items` array (or plugin implements `mapWebsocketPayload`)
- [ ] **Engine:** SQLite table created in `db.ts` if historical data needed
- [ ] **Verification:** `GET localhost:5000/manifest` includes the plugin ID
- [ ] **Verification:** `GET localhost:5000/health` shows seeder last-run timestamp
-1
View File
@@ -1 +0,0 @@
.agents
+1
View File
@@ -0,0 +1 @@
.agents
-6
View File
@@ -4,11 +4,5 @@ install_deps = "pnpm install"
[[pre-start]]
copy_env = """powershell -Command "if (Test-Path '../worldwideview/.env') { Copy-Item '../worldwideview/.env' '.env' -Force }""""
[[pre-start]]
copy_local_plugins = """powershell -Command "if (Test-Path '../worldwideview/local-plugins') { robocopy '../worldwideview/local-plugins' 'local-plugins' /E /XD node_modules dist .next coverage /XF '*.log' /NFL /NDL /NJH /NJS | Out-Null }""""
[[pre-start]]
copy_local_seeders = """powershell -Command "if (Test-Path '../worldwideview/local-seeders') { robocopy '../worldwideview/local-seeders' 'local-seeders' /E /XD .pnpm-store node_modules /NFL /NDL /NJH /NJS | Out-Null }""""
[[pre-remove]]
docker_clean = "docker compose down -v"
-5
View File
@@ -41,11 +41,6 @@ jobs:
pnpm run predev
- name: Run Playwright tests
env:
# Prevent Firefox from loading the AT-SPI/MSAA accessibility bridge on
# Linux CI — without this, Firefox hangs for ~20 min waiting for a bus
# that doesn't exist on ubuntu-latest runners.
NO_AT_BRIDGE: ${{ matrix.browser == 'firefox' && '1' || '0' }}
run: pnpm test:e2e --project=${{ matrix.browser }}
- uses: actions/upload-artifact@v4
+5 -3
View File
@@ -22,6 +22,10 @@ node_modules/
/.agents/context
/.agents/research/
# claude code IDE config
/.claude/
/.cline/
# performance
/performance/
@@ -60,8 +64,7 @@ yarn-error.log*
.pnpm-debug.log*
# env files (can opt-in for committing if needed)
.env
.env.local
.env*
# vercel
.vercel
@@ -93,7 +96,6 @@ packages/wwv-data-engine/
# IDE workspace files
*.code-workspace
*.vscode
# Build outputs and generated assets
/public/cesium/
-1
View File
@@ -1 +0,0 @@
AGENTS.md
-2
View File
@@ -63,8 +63,6 @@ services:
cd /app && node dist/server.js"
ports:
- "5000:5000"
volumes:
- ./local-seeders:/app/seeders
environment:
- PORT=5000
- REDIS_URL=redis://wwv-redis:6379
@@ -1,158 +0,0 @@
# ADR-0002: Source-of-truth for plugin identity and registration
## Status
Accepted
## Date
2026-05-20
## Context
Two related problems in the plugin system surfaced in the same period, and both have the same root cause: canonical plugin information was being derived in middleware translation layers (folder names, hard-coded lists) rather than at its proper source. Each problem is fixed by pushing the canonical truth back to its rightful owner and removing the static translation in the middle. Documenting them together makes the shared principle explicit and discourages future regressions of the same shape.
### Problem 1 — Engine seeder ID derived from folder name
The WorldWideView local data engine discovers seeders by scanning the filesystem under `/app/seeders`. Historically, the engine assigned each seeder an ID equal to its **folder name** (e.g., the folder `gpsjam/` became plugin ID `"gpsjam"`).
The frontend, however, identifies plugins by a separate **`id` field** declared in each plugin class (e.g., `"gps-jamming"`). The engine's `/manifest` endpoint listed available plugins using folder-derived IDs, and the frontend's `localEngineHasPlugin(pluginId)` performed an exact string match against that list.
This created a silent failure mode: six seeders had folder names that did not match their corresponding frontend plugin IDs:
| Folder name | Frontend plugin `id` |
|---|---|
| `gpsjam/` | `gps-jamming` |
| `sanctions/` | `international-sanctions` |
| `wildfires/` | `wildfire` |
| `civilUnrest/` | `civil-unrest` |
| `conflictEvents/` | `conflict-events` |
| `cyberAttacks/` | `cyber-attacks` |
When `localEngineHasPlugin('gps-jamming')` returned `false` (because the manifest listed `"gpsjam"`), the frontend silently fell through to the production cloud engine, bypassing the local engine entirely. The bug was invisible — no error, just incorrect routing.
A short-term patch introduced `SEEDER_ID_ALIASES` in `src/core/data/engineManifest.ts` — a frontend translation map from folder names to plugin IDs. This was explicitly a band-aid: it duplicated knowledge in a consumer rather than fixing the contract at the source, and would go stale as new seeders were added.
The engine's TypeScript source (`seeder-loader.ts`) also had a `toKebabCase()` helper intended to normalize camelCase folder names (e.g., `civilUnrest` → `civil-unrest`), but its compiled `dist/` was stale (the production image had not been rebuilt to include it), and `toKebabCase` alone cannot resolve abbreviation mismatches like `gpsjam` → `gps-jamming`.
### Problem 2 — Fresh-install plugin set hard-coded
The marketplace auto-seeder ([src/lib/marketplace/seedDefaultPlugins.ts](../../../src/lib/marketplace/seedDefaultPlugins.ts)) writes a starter set of plugins to the database on first boot so the globe isn't empty on day one. The list of plugins to seed lived in a hard-coded constant `DEFAULT_PLUGIN_IDS` ([src/lib/marketplace/defaultPlugins.ts](../../../src/lib/marketplace/defaultPlugins.ts)).
Two failure modes followed from the static list:
1. **Drift**: ten plugins were published to npm under `@worldwideview/*` and verified — surveillance-satellites, military-bases, embassies, seaports, lighthouses, spaceports, iranwarlive, undersea-cables, mineral-mines, nuclear-facilities — but never added to `DEFAULT_PLUGIN_IDS`. Fresh installs missed them silently.
2. **Phantom 404s**: two entries in the list (`fortiguard`, `nz-traffic-cameras`) were dev-only sandboxes in `local-plugins/`, never published to npm. Every fresh boot hit `https://marketplace.worldwideview.dev/api/plugins/fortiguard` → 404, logged a warning, and continued. The branch `fix/diagnose-plugins-404` was opened to diagnose those.
A separate, signed verified-plugins registry already existed at `marketplace.worldwideview.dev/api/registry`, loaded by [registryClient.ts](../../../src/lib/marketplace/registryClient.ts) with Ed25519 verification. It was used for trust-stamping installed plugins but not for selecting which plugins to seed. That registry is the authoritative list of plugins that have been reviewed and verified — exactly the list a starter set should come from.
### Shared shape
Both problems wrap the same anti-pattern: a consumer (frontend, seeder) maintains a static translation/list derived from the producer's actual identity (seeder export, npm publication). The translation drifts. The fix in both cases is the same: stop translating in the consumer; let the producer declare the truth and consume it directly.
## Decisions
### Decision 1 — The seeder's exported `name` field is the canonical plugin ID
The engine reads each seeder's `dist/index.mjs` default export's `name` property and uses it as the plugin ID everywhere:
- `/manifest` endpoint `plugins` array
- WebSocket welcome message plugin list
- WebSocket data message `pluginId` field
- Redis key (`data:<name>:live`)
- Scheduler logs
The folder name is used only as a filesystem fallback if the seeder exports no `name`. The engine logs a warning at startup whenever the kebab-cased folder name differs from the seeder's exported `name`, making drift visible without blocking startup.
**Contract:** Every seeder MUST export a `name` field that exactly equals the corresponding frontend plugin's `id` field (kebab-case). This is a two-place contract: declare the same ID string in the seeder export and in the frontend plugin class.
Implementation: `seeder-loader.ts` was updated to set `id = seederConfig.name || toKebabCase(folderName)` instead of `id = toKebabCase(folderName)`. The frontend `SEEDER_ID_ALIASES` map was removed entirely. No translation layer exists between the engine's manifest and the frontend's plugin lookup.
### Decision 2 — The signed verified registry is the source-of-truth for fresh-install auto-seeding
The marketplace auto-seeder iterates the set returned by `getVerifiedPluginIds()` (the signed registry) instead of a hard-coded `DEFAULT_PLUGIN_IDS` constant. Publishing a plugin to the verified registry automatically makes it part of the fresh-install starter set on subsequent boots, with no code change.
The static `DEFAULT_PLUGIN_IDS` list is deleted. There is no fallback list in code — if the registry is unreachable on first attempt, the seeder defers without marking-seeded so the next request retries (the 5-min in-memory cache in `registryClient.ts` bounds the request rate during outages).
Trust stamping is collapsed: every plugin landed by the seeder is `verified` by definition, so the per-plugin `verified.has(pluginId)` check inside the seeder is dropped — `manifest.trust = "verified"` is set directly.
**Contract:** A plugin is part of the fresh-install starter set iff it appears in the signed verified-plugins registry. There is no other list to maintain.
## Shared principle
> **Canonical plugin truth lives at the source. Reject static translation/lookup layers in the middle.**
This is the architectural rule both decisions encode. Concrete corollaries for future contributions:
- Don't introduce a static map in a consumer to compensate for a producer that mis-labels itself. Fix the producer.
- Don't introduce a static list in code to enumerate what a registry or filesystem already enumerates. Read from the registry/filesystem.
- A translation layer that "just needs an entry added each time we publish a plugin" is a foot-gun — it will silently drift the moment someone forgets.
## Alternatives Considered
### For Decision 1
#### Folder renames (rejected as primary fix)
Rename the six mismatched folders to match their frontend plugin IDs (e.g., `gpsjam/` → `gps-jamming/`). This would make the folder name the canonical ID.
- **Rejected as primary fix** because Windows Docker Desktop holds NTFS volume mount locks on running containers, making renames impossible without a full Docker Desktop shutdown. More importantly, it makes the canonical ID fragile — any accidental folder rename breaks routing silently.
- Folder renames remain a cosmetic cleanup option, now that the seeder export is the actual source of truth.
#### Frontend alias map (`SEEDER_ID_ALIASES`)
Maintain a static mapping in `engineManifest.ts` that translates engine-reported IDs to frontend plugin IDs.
- **Rejected** because it puts translation responsibility on the consumer rather than the producer. Every new seeder with a naming mismatch requires a manual alias entry. The map goes stale silently — no warning if an alias is wrong or missing.
#### `toKebabCase()` normalization only
Apply `toKebabCase()` to folder names in the engine and rely on the convention that folder names encode the plugin ID in camelCase.
- **Rejected** because `toKebabCase` cannot resolve abbreviation mismatches (`gpsjam` → still `gpsjam`, not `gps-jamming`) or singular/plural differences (`wildfires` → still `wildfires`, not `wildfire`). It only handles camelCase-to-kebab conversion.
#### Strict validation with engine startup failure
Refuse to load any seeder whose folder name doesn't match its exported `name`, blocking startup until inconsistencies are resolved.
- **Rejected** as too aggressive for a local dev environment. A warning is sufficient — startup continues, mismatches are visible, and the system keeps working.
### For Decision 2
#### Add the missing 10 IDs to `DEFAULT_PLUGIN_IDS` (rejected)
Extend the static list to include the newly-published plugins.
- **Rejected** because it ships a fix that resolves the immediate symptom while preserving the underlying drift mechanism. The list would go stale again the next time a plugin is published.
#### Hybrid: registry as default + static fallback list
Read from the registry; fall back to a hard-coded list if the registry is empty/unreachable.
- **Rejected** because it reintroduces the static list as a permanent shadow source-of-truth. Fallback lists go stale silently. The chosen "defer seeding on empty registry" behavior is safer — fresh installs retry on the next request rather than locking in a stale set.
#### Delete auto-seeding entirely (rejected)
Drop the seeder and let users install everything from the marketplace UI starting from an empty globe.
- **Rejected** because fresh installs should have something to look at on day one. The user explicitly stated this requirement: "we want the user to have something to get started with."
## Consequences
### Easier
**Decision 1 — engine seeder identity**
- Self-documenting identity. Reading any seeder's `src/index.ts` immediately tells you its plugin ID. No external registry to consult.
- Filesystem layout is irrelevant. Folders can be named for readability or organized in subdirectories without affecting routing.
- No translation layers. The frontend receives the correct ID directly from the manifest; `localEngineHasPlugin()` works with a direct string comparison.
- Drift is visible. The engine warns on startup when folder names diverge from exported names, catching mistakes during development rather than silently at runtime.
- Adding a new seeder requires only: (1) export `name: '<plugin-id>'` matching the frontend plugin's `id`, (2) no registration step, no alias map entry.
**Decision 2 — marketplace seeding**
- Publishing a plugin to the verified registry is sufficient to add it to the starter set. No code change, no PR to add an ID to a constant.
- Phantom 404s are gone. The seeder only queries IDs that exist in the verified registry, which by construction reflects what's actually published.
- Trust semantics align. "Verified" and "auto-seeded on fresh install" are now the same condition, not two near-overlapping lists that can drift.
- Registry outages no longer brick fresh installs. The deferral semantics ensure the seeder retries instead of marking-seeded with zero rows.
### Harder
**Decision 1 — engine seeder identity**
- Seeder author bears responsibility. If a seeder exports the wrong `name`, routing fails silently (same failure mode as before, but now localized to the seeder rather than the folder). The startup warning mitigates this.
- Contract validation is advisory, not enforced. There is no build-time check that the seeder's `name` matches an actual frontend plugin `id`. A validation script (`scripts/validate-seeder-ids.mjs`) is the recommended mitigation.
- Engine image must be kept up to date. The fix lives in `dist/seeder-loader.js` inside the Docker image. If the published `ghcr.io/silvertakana/wwv-data-engine:latest` image is behind the local source, the behavior reverts to folder-name-based IDs. Local changes require `docker cp` injection or an image rebuild until the fix is published.
**Decision 2 — marketplace seeding**
- The verified registry must be kept accurate. A newly-published plugin doesn't auto-seed until it's added to the registry and the registry is re-signed. Operational responsibility shifts from "remember to add the ID to a code constant" to "remember to add the ID to the registry" — a similar discipline, but now at the right layer (the marketplace, not the consumer).
- Existing instances are not back-filled. Users whose `Setting` table already has `defaults_seeded=true` will not automatically receive newly-verified plugins; they must install via the marketplace UI. This is by design — re-seeding could reinstall plugins a user explicitly uninstalled.
- Dev-only sandboxes (`local-plugins/<name>/`) no longer "tag along" via the default list. `fortiguard` and `nz-traffic-cameras` only reach users once published to npm and added to the verified registry. The local-plugins folder discovery in `/api/marketplace/load` still surfaces them in dev (`NODE_ENV=development` or `WWV_PLUGIN_DEV=true`).
+13 -13
View File
@@ -1,6 +1,6 @@
{
"name": "worldwideview",
"version": "2.16.1",
"version": "2.15.14",
"private": true,
"type": "module",
"packageManager": "[email protected]",
@@ -31,8 +31,8 @@
"@prisma/adapter-pg": "^7.8.0",
"@prisma/client": "^7.8.0",
"@prisma/client-runtime-utils": "7.8.0",
"@sentry/nextjs": "^10.53.1",
"@supabase/supabase-js": "^2.106.0",
"@sentry/nextjs": "^10.52.0",
"@supabase/supabase-js": "^2.105.4",
"@types/pg": "^8.20.0",
"@vercel/analytics": "^1.6.1",
"@worldwideview/wwv-plugin-sdk": "workspace:*",
@@ -42,20 +42,20 @@
"hls.js": "^1.6.16",
"insecam-api": "^0.0.3",
"jose": "^6.2.3",
"lucide-react": "^1.16.0",
"lucide-react": "^1.14.0",
"next": "16.2.6",
"next-auth": "^5.0.0-beta.30",
"openid-client": "^6.8.4",
"pg": "^8.21.0",
"pg": "^8.20.0",
"prisma": "^7.8.0",
"react": "19.2.6",
"react-dom": "19.2.6",
"react-player": "^3.4.0",
"resium": "1.21.1",
"satellite.js": "^7.0.1",
"resium": "1.21.0",
"satellite.js": "^7.0.0",
"stripe": "^22.1.1",
"tslib": "^2.8.1",
"undici": "^8.3.0",
"undici": "^8.2.0",
"ws": "^8.20.1",
"zod": "^4.4.3",
"zustand": "^5.0.13"
@@ -74,9 +74,9 @@
"@types/react": "^19",
"@types/react-dom": "^19",
"@types/ws": "^8.18.1",
"@typescript-eslint/eslint-plugin": "^8.59.4",
"@typescript-eslint/parser": "^8.59.4",
"@vitejs/plugin-react": "^6.0.2",
"@typescript-eslint/eslint-plugin": "^8.59.3",
"@typescript-eslint/parser": "^8.59.3",
"@vitejs/plugin-react": "^5.1.4",
"@vitest/coverage-v8": "4.1.6",
"concurrently": "^9.2.1",
"copy-webpack-plugin": "^14.0.0",
@@ -92,9 +92,9 @@
"jsdom": "^28.1.0",
"rollup-plugin-external-globals": "^0.13.0",
"tree-kill": "^1.2.2",
"tsx": "^4.22.2",
"tsx": "^4.21.0",
"typescript": "^5",
"vite": "^8.0.13",
"vite": "^8.0.12",
"vitest": "^4.1.6"
},
"pnpm": {
+2 -2
View File
@@ -13,11 +13,11 @@
"clean": "rm -rf dist"
},
"dependencies": {
"commander": "^14.0.3",
"commander": "^12.1.0",
"prompts": "^2.4.2"
},
"devDependencies": {
"@types/node": "^25.9.1",
"@types/node": "^20.0.0",
"@types/prompts": "^2.4.9",
"typescript": "^5.0.0"
}
+2 -8
View File
@@ -41,15 +41,9 @@ export default defineConfig({
},
{
name: 'firefox',
use: {
use: {
...devices['Desktop Firefox'],
storageState: 'playwright/.auth/user.json',
launchOptions: {
firefoxUserPrefs: {
// Disable MSAA/AT-SPI accessibility layer — causes hangs on Linux CI
'accessibility.force_disabled': 1,
},
},
storageState: 'playwright/.auth/user.json'
},
},
{
+657 -905
View File
File diff suppressed because it is too large. Load diff
+23 -219
View File
@@ -7,7 +7,6 @@
*/
import fs from "fs";
import os from "os";
import path from "path";
import { build } from "vite";
import { fileURLToPath } from "url";
@@ -27,72 +26,9 @@ const EXTERNAL_GLOBALS = {
"resium": "globalThis.__WWV_HOST__.Resium",
};
/**
* Synthetic host-module exports for `@/` imports that plugins use to access
* the host application's runtime objects (store, plugin manager, components).
*
* When a plugin sub-component does `import { useStore } from "@/core/state/store"`,
* the tsconfig `@/*` alias (inherited from the main app root tsconfig) would normally
* resolve that to the actual `src/core/state/store.ts` file — pulling the entire Zustand
* store (and its transitive deps like `src/core/edition.ts`) into the bundle.
* This plugin intercepts those imports at the resolveId stage, before Vite touches
* the filesystem, and substitutes a synthetic module that reads from the host globals
* injected at runtime by `hostGlobals.ts`.
*/
const HOST_MODULE_SYNTHETICS = {
"@/core/state/store": `export const useStore = globalThis.__WWV_HOST__.useStore;`,
"@/core/plugins/PluginManager": `export const pluginManager = globalThis.__WWV_HOST__.pluginManager;`,
"@/components/video/CameraStream": `export const CameraStream = globalThis.__WWV_HOST__.CameraStream;`,
"zustand": `
const zustand = globalThis.__WWV_HOST__.zustand || {};
export default zustand;
export const { create, createStore } = zustand;
`,
};
/**
* @function wwvHostRedirectPlugin
* @description Vite plugin that intercepts host-app module imports (`@/core/...`,
* `@/components/...`) in local plugin builds and redirects them to the runtime
* host globals instead of bundling the full app source tree.
*
* @returns {import('vite').Plugin}
*/
function wwvHostRedirectPlugin() {
return {
name: "wwv-host-redirect",
enforce: "pre",
resolveId(id) {
if (id in HOST_MODULE_SYNTHETICS) return `\0${id}`;
return null;
},
load(id) {
if (!id.startsWith("\0")) return null;
const originalId = id.slice(1);
return HOST_MODULE_SYNTHETICS[originalId] ?? null;
},
};
}
/**
* @function readJsonFile
* @description Reads a UTF-8 JSON file, tolerating a leading BOM (U+FEFF).
* Node's `fs.readFileSync(p, 'utf-8')` preserves the BOM byte, which `JSON.parse`
* then rejects with "Unexpected token". Scaffolders and editors on Windows
* occasionally emit BOMs into `package.json`; pnpm/npm strip them silently,
* so we match that behavior here to avoid breaking dev on otherwise-valid files.
* @param {string} filePath
* @returns {any}
*/
function readJsonFile(filePath) {
let text = fs.readFileSync(filePath, "utf-8");
if (text.charCodeAt(0) === 0xFEFF) text = text.slice(1);
return JSON.parse(text);
}
/**
* @function discoverLocalPlugins
* @description Finds all directories in `local-plugins/` that contain a valid
* @description Finds all directories in `local-plugins/` that contain a valid
* `package.json` with a `worldwideview` manifest block.
* @returns {Array<{dir: string, manifest: any, pluginDir: string}>}
*/
@@ -104,141 +40,43 @@ export function discoverLocalPlugins() {
if (dir.startsWith(".")) return false;
const pkgPath = path.join(LOCAL_PLUGINS_DIR, dir, "package.json");
if (!fs.existsSync(pkgPath)) return false;
const pkg = readJsonFile(pkgPath);
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
return !!pkg.worldwideview;
})
.map(dir => {
const pkgPath = path.join(LOCAL_PLUGINS_DIR, dir, "package.json");
const pkg = readJsonFile(pkgPath);
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
const manifest = pkg.worldwideview;
manifest.version = pkg.version;
manifest.name = pkg.name;
manifest.description = pkg.description;
return { dir, manifest, pkg, pluginDir: path.join(LOCAL_PLUGINS_DIR, dir) };
return { dir, manifest, pluginDir: path.join(LOCAL_PLUGINS_DIR, dir) };
});
}
/**
* @function resolvePluginEntry
* @description Resolves the TypeScript source entry file for a plugin.
*
* Resolution order:
* 1. `worldwideview.dev_entry` — explicit override in the manifest block
* 2. `pkg.types` — if it points to a .ts/.tsx source file (not a .d.ts declaration)
* 3. `pkg.source` — explicit source field (less common, but valid)
* 4. Heuristic fallback: src/index.ts → src/index.tsx → index.ts → index.tsx
*
* @param {string} pluginDir - Absolute path to the plugin directory.
* @param {any} manifest - The parsed `worldwideview` manifest block.
* @param {any} pkg - The full parsed package.json object.
* @returns {string|null} Absolute path to the entry file, or null if not found.
*/
function resolvePluginEntry(pluginDir, manifest, pkg) {
const candidates = [];
if (manifest.dev_entry) {
candidates.push(path.join(pluginDir, manifest.dev_entry));
}
// pkg.types points to the TS source in all WWV plugins (e.g. "src/index.ts")
if (pkg.types && !pkg.types.endsWith(".d.ts")) {
candidates.push(path.join(pluginDir, pkg.types));
}
if (pkg.source) {
candidates.push(path.join(pluginDir, pkg.source));
}
// Heuristic fallbacks
for (const rel of ["src/index.ts", "src/index.tsx", "index.ts", "index.tsx"]) {
candidates.push(path.join(pluginDir, rel));
}
return candidates.find(f => fs.existsSync(f)) ?? null;
}
const SKIP_DIRS = new Set(["dist", "node_modules", ".git", ".turbo", ".vite"]);
/**
* @function latestSourceMtime
* @description Walks a plugin directory and returns the newest mtime (ms) across
* source files. Used to decide whether a cached `dist/frontend.mjs` is still valid.
* Skips build/output dirs so this is fast even on cold disks.
* @param {string} rootDir
* @returns {number} newest mtime in ms, or 0 if no files found
*/
function latestSourceMtime(rootDir) {
let newest = 0;
/** @param {string} dir */
function walk(dir) {
let entries;
try {
entries = fs.readdirSync(dir, { withFileTypes: true });
} catch {
return;
}
for (const entry of entries) {
if (entry.name.startsWith(".") && entry.name !== ".env") continue;
if (SKIP_DIRS.has(entry.name)) continue;
const full = path.join(dir, entry.name);
if (entry.isDirectory()) {
walk(full);
} else if (entry.isFile()) {
const m = fs.statSync(full).mtimeMs;
if (m > newest) newest = m;
}
}
}
walk(rootDir);
return newest;
}
/**
* @function isBuildFresh
* @description Returns true if the plugin's existing `dist/frontend.mjs` is newer
* than every source file under its directory — meaning Vite would produce a
* byte-identical bundle and the build can be skipped.
* @param {string} pluginDir
* @returns {boolean}
*/
function isBuildFresh(pluginDir) {
const distFile = path.join(pluginDir, "dist", "frontend.mjs");
if (!fs.existsSync(distFile)) return false;
const distMtime = fs.statSync(distFile).mtimeMs;
const sourceMtime = latestSourceMtime(pluginDir);
return distMtime >= sourceMtime;
}
/**
* @function buildPlugin
* @description Invokes the Vite build engine to compile a plugin's source
* @description Invokes the Vite build engine to compile a plugin's source
* into a single ES module, externalizing shared host dependencies.
*
* Returns `"fresh"` if an up-to-date `dist/frontend.mjs` already exists (no build run),
* `true` if Vite produced a new bundle, or `false` on failure.
*/
export async function buildPlugin({ dir, manifest, pkg, pluginDir }) {
if (isBuildFresh(pluginDir)) {
return "fresh";
}
export async function buildPlugin({ dir, manifest, pluginDir }) {
const devEntry = manifest.dev_entry || "index.ts";
let entryFile = path.join(pluginDir, devEntry);
const entryFile = resolvePluginEntry(pluginDir, manifest, pkg ?? {});
if (!entryFile) {
console.warn(`[sync] ⚠ No entry file found for ${dir}, skipping`);
return false;
// Fallback: check for .tsx
if (!fs.existsSync(entryFile)) {
const tsxEntry = devEntry.replace(".ts", ".tsx");
entryFile = path.join(pluginDir, tsxEntry);
if (!fs.existsSync(entryFile)) {
console.warn(`[sync] ⚠ No entry file found for ${dir}, skipping`);
return false;
}
}
try {
await build({
root: pluginDir,
// Disable auto-loading the plugin's own vite.config.ts — the local
// plugins' node_modules may be symlinked to a different repo's SDK
// build (worktree scenario), which breaks config loading. The sync
// script provides all necessary config inline.
configFile: false,
logLevel: "warn",
plugins: [wwvHostRedirectPlugin()],
build: {
lib: {
entry: entryFile,
@@ -276,7 +114,7 @@ export async function buildPlugin({ dir, manifest, pkg, pluginDir }) {
}
}
export function syncToPublic({ dir, manifest, pluginDir }, { quiet = false } = {}) {
export function syncToPublic({ dir, manifest, pluginDir }) {
const publicName = manifest.id || dir.replace("wwv-plugin-", "");
const targetDir = path.join(OUTPUT_DIR, publicName);
const distFile = path.join(pluginDir, "dist", "frontend.mjs");
@@ -313,7 +151,7 @@ export function syncToPublic({ dir, manifest, pluginDir }, { quiet = false } = {
JSON.stringify(pluginJson, null, 2)
);
if (!quiet) console.log(`[sync] ✅ ${publicName} → public/plugins-local/${publicName}/`);
console.log(`[sync] ✅ ${publicName} → public/plugins-local/${publicName}/`);
}
// Clean stale plugins from public/plugins-local/ that no longer exist in local-plugins/
@@ -328,32 +166,6 @@ function cleanStale(activeIds) {
}
}
/**
* @function runWithConcurrency
* @description Runs an async worker over `items` with a fixed concurrency cap.
* Vite builds are CPU-bound; running all ~30 in parallel thrashes the scheduler
* and balloons RSS. A cap around half the logical cores keeps wall-clock low
* without starving the rest of the dev environment (Next.js, the data engine).
* @template T, R
* @param {T[]} items
* @param {number} concurrency
* @param {(item: T) => Promise<R>} worker
* @returns {Promise<R[]>}
*/
async function runWithConcurrency(items, concurrency, worker) {
const results = new Array(items.length);
let cursor = 0;
const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
while (true) {
const i = cursor++;
if (i >= items.length) return;
results[i] = await worker(items[i]);
}
});
await Promise.all(workers);
return results;
}
export async function syncAll() {
const plugins = discoverLocalPlugins();
@@ -363,20 +175,12 @@ export async function syncAll() {
return;
}
const concurrency = Math.max(2, Math.min(plugins.length, Math.ceil(os.cpus().length / 2)));
console.log(`[sync] Found ${plugins.length} local plugin(s); building with concurrency=${concurrency}`);
const started = Date.now();
console.log(`[sync] Found ${plugins.length} local plugin(s): ${plugins.map(p => p.dir).join(", ")}`);
let freshCount = 0;
let builtCount = 0;
await runWithConcurrency(plugins, concurrency, async (plugin) => {
const result = await buildPlugin(plugin);
if (result === "fresh") freshCount++;
else if (result) builtCount++;
if (result) syncToPublic(plugin, { quiet: result === "fresh" });
});
console.log(`[sync] Done in ${((Date.now() - started) / 1000).toFixed(1)}s (${builtCount} built, ${freshCount} cached)`);
for (const plugin of plugins) {
const ok = await buildPlugin(plugin);
if (ok) syncToPublic(plugin);
}
const activeIds = plugins.map(p => p.manifest.id || p.dir.replace("wwv-plugin-", ""));
cleanStale(activeIds);
+10 -36
View File
@@ -15,66 +15,40 @@ if (!fs.existsSync(LOCAL_PLUGINS_DIR)) {
let debounceTimeout = null;
let isSyncing = false;
let pendingSync = false;
/** Files changed since last sync completed — collected during the debounce window */
const pendingChanges = new Set();
function handleFileChange(eventType, filename) {
if (!filename) return;
if (
filename.includes("dist") ||
filename.includes("node_modules") ||
if (filename && (
filename.includes("dist") ||
filename.includes("node_modules") ||
filename.endsWith(".map") ||
filename.includes(".git")
) return; // ignore build artifacts and git internals
pendingChanges.add(filename);
)) return; // ignore build artifacts and git internals
if (debounceTimeout) {
clearTimeout(debounceTimeout);
}
debounceTimeout = setTimeout(async () => {
if (isSyncing) {
pendingSync = true;
return;
}
await runSync();
await runSync(filename);
}, 500);
}
/**
* Pulls plugin slugs out of changed file paths so we can name what triggered the rebuild.
* fs.watch on `local-plugins/` emits paths like `aviation/src/index.ts` (POSIX or Windows).
*/
function summarizeChangedPlugins(files) {
const slugs = new Set();
for (const f of files) {
const head = f.split(/[\\/]/)[0];
if (head) slugs.add(head);
}
return [...slugs];
}
async function runSync() {
async function runSync(filename) {
isSyncing = true;
const changed = summarizeChangedPlugins(pendingChanges);
pendingChanges.clear();
const label = changed.length === 0
? "pending changes"
: changed.length <= 3
? changed.join(", ")
: `${changed.slice(0, 3).join(", ")} (+${changed.length - 3} more)`;
console.log(`\n[watch] 🔄 Change detected in: ${label}`);
console.log(`\n[watch] Change detected in local plugins (file: ${filename}). Syncing...`);
try {
await syncAll();
console.log(`[watch] ✨ Hot-reload ready`);
} catch (err) {
console.error(`[watch] Sync failed:`, err);
} finally {
isSyncing = false;
if (pendingSync) {
pendingSync = false;
await runSync();
await runSync("pending changes");
}
}
}
+4 -16
View File
@@ -129,27 +129,15 @@ export function AppShell() {
console.log("[AppShell] Platform Ready. Waiting for globe tiles...");
};
// Guard so boot only starts once regardless of which trigger fires first.
let bootStarted = false;
const startBootOnce = (reason: string) => {
if (bootStarted) return;
bootStarted = true;
console.log(`[AppShell] Starting boot sequence (${reason}).`);
// Start boot sequence when globe tiles are loaded
const unsubGlobe = dataBus.on("globeReady", () => {
console.log("[AppShell] Globe ready — starting boot sequence.");
boot.startBoot();
};
// Primary trigger: globe signals it is ready.
const unsubGlobe = dataBus.on("globeReady", () => startBootOnce("globeReady"));
// Safety fallback: if the globe never initialises (e.g. WebGL unavailable
// in headless CI environments), force the boot sequence after 20 s so the
// app still reaches the "ready" state and tests are not left hanging.
const safetyTimer = setTimeout(() => startBootOnce("safety-timeout"), 20_000);
});
startPlatform();
return () => {
clearTimeout(safetyTimer);
unsubGlobe();
boot.cleanup();
pluginManager.destroy();
+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).toContain("localhost:5001/stream");
});
it("should fall back to plugin's custom streamUrl if not local", () => {
+1 -3
View File
@@ -36,8 +36,6 @@ describe("WsClient", () => {
beforeEach(() => {
vi.useFakeTimers();
vi.clearAllMocks();
// Pin Math.random to 0 so jitter is deterministic (delay = base only)
vi.spyOn(Math, "random").mockReturnValue(0);
// Mock WebSocket global
mockWs = {
@@ -87,7 +85,7 @@ describe("WsClient", () => {
);
});
it("should attempt to reconnect after base delay if the connection is closed while subscriptions exist", () => {
it("should attempt to reconnect after 5s if the connection is closed while subscriptions exist", () => {
wsClient.subscribe("plugin-a", "ws://engine-1/stream");
mockWs.onclose();
+8 -43
View File
@@ -9,23 +9,11 @@ interface EngineConnection {
subscriptions: Set<string>;
/** Grace period timer — closes the connection if no plugins remain subscribed */
cleanupTimer: NodeJS.Timeout | null;
/** Backoff attempt counter — resets after a stable connection (>5s open) */
reconnectAttempts: number;
/** Timer that resets the backoff counter once a connection has been stable */
stableConnectionTimer: NodeJS.Timeout | null;
}
const RECONNECT_BASE_MS = 5000;
const RECONNECT_MAX_MS = 60000; // Cap at 1 minute
const RECONNECT_JITTER_MS = 4000;
const STABLE_CONNECTION_MS = 5000; // Reset backoff after 5s of stable connection
const RECONNECT_DELAY_MS = 5000;
const CLEANUP_GRACE_MS = 30000;
/** Normalizes underscore-based pluginIds to kebab-case (e.g. `my_plugin` → `my-plugin`). */
function normalizePluginId(id: string): string {
return id.replace(/_/g, "-");
}
class WebSocketClient {
private engines = new Map<string, EngineConnection>();
@@ -37,8 +25,6 @@ class WebSocketClient {
reconnectTimer: null,
subscriptions: new Set(),
cleanupTimer: null,
reconnectAttempts: 0,
stableConnectionTimer: null,
};
this.engines.set(engineUrl, engine);
}
@@ -57,12 +43,6 @@ class WebSocketClient {
engine.ws.onopen = () => {
console.debug(`[WSClient] 🟢 Connected to ${engineUrl}. WS Handshake took ${(performance.now() - wsStart).toFixed(2)}ms`);
// Only reset backoff if the connection stays open for a non-trivial time —
// an immediate close (e.g. server-side rejection) shouldn't be treated as success.
if (engine.stableConnectionTimer) clearTimeout(engine.stableConnectionTimer);
engine.stableConnectionTimer = setTimeout(() => {
engine.reconnectAttempts = 0;
}, STABLE_CONNECTION_MS);
// Resubscribe to all active plugins on this engine
for (const pluginId of engine.subscriptions) {
this.send(engine, { action: "subscribe", pluginId });
@@ -94,39 +74,25 @@ class WebSocketClient {
};
engine.ws.onclose = () => {
console.warn(`[WSClient] Disconnected from ${engineUrl}. Reconnecting in 5s...`);
engine.ws = null;
if (engine.stableConnectionTimer) {
clearTimeout(engine.stableConnectionTimer);
engine.stableConnectionTimer = null;
}
if (engine.reconnectTimer) clearTimeout(engine.reconnectTimer);
// Only reconnect if there are still active subscriptions
if (engine.subscriptions.size > 0) {
// Exponential backoff with jitter to prevent thundering herd on engine restart.
// 5s -> 10s -> 20s -> 40s -> 60s (cap), plus ±4s of jitter so simultaneous
// sessions don't all reconnect at the same instant.
const expDelay = Math.min(
RECONNECT_BASE_MS * Math.pow(2, engine.reconnectAttempts),
RECONNECT_MAX_MS
);
const delay = expDelay + Math.random() * RECONNECT_JITTER_MS;
engine.reconnectAttempts++;
console.warn(`[WSClient] Disconnected from ${engineUrl}. Reconnecting in ${Math.round(delay / 1000)}s (attempt ${engine.reconnectAttempts})...`);
engine.reconnectTimer = setTimeout(() => this.connectEngine(engineUrl), delay);
engine.reconnectTimer = setTimeout(() => this.connectEngine(engineUrl), RECONNECT_DELAY_MS);
}
};
}
private handleDataMessage(data: WsStreamPayload) {
const pluginId = normalizePluginId(data.pluginId!);
const plugin = pluginManager.getPlugin(pluginId)?.plugin;
const plugin = pluginManager.getPlugin(data.pluginId!)?.plugin;
let finalEntities = data.payload as GeoEntity[];
const existingEntities = useStore.getState().entitiesByPlugin[pluginId] || [];
const existingEntities = useStore.getState().entitiesByPlugin[data.pluginId!] || [];
if (plugin && typeof (plugin as any).mapWebsocketPayload === "function") {
finalEntities = (plugin as any).mapWebsocketPayload(data.payload, existingEntities);
} else if (!Array.isArray(data.payload)) {
console.warn(`[WsClient] Payload for ${pluginId} is an object but no mapWebsocketPayload exists. Ignoring.`);
console.warn(`[WsClient] Payload for ${data.pluginId} is an object but no mapWebsocketPayload exists. Ignoring.`);
return;
} else {
finalEntities = finalEntities.map((e) => ({
@@ -135,10 +101,10 @@ class WebSocketClient {
}));
}
console.debug(`[WSClient] 🔄 Dispatching ${finalEntities.length} entities for ${pluginId} to DataBus`);
console.debug(`[WSClient] 🔄 Dispatching ${finalEntities.length} entities for ${data.pluginId} to DataBus`);
dataBus.emit("dataUpdated", {
pluginId,
pluginId: data.pluginId!,
entities: finalEntities,
});
}
@@ -177,7 +143,6 @@ class WebSocketClient {
if (engine.subscriptions.size === 0) {
console.log(`[WSClient] No subscriptions remain for ${engineUrl}. Closing connection.`);
if (engine.reconnectTimer) clearTimeout(engine.reconnectTimer);
if (engine.stableConnectionTimer) clearTimeout(engine.stableConnectionTimer);
engine.ws?.close();
this.engines.delete(engineUrl);
}
+25 -12
View File
@@ -8,24 +8,37 @@ 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".
* Priority:
* 1. `NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL` env var — if the operator
* pointed plugins at a specific engine URL (most common in
* self-host setups), use that. We strip any trailing `/stream`
* since the var is sometimes set to the WebSocket URL.
* 2. `localhost:5001` — matches the port wwv-data-engine's
* docker-compose.yaml binds. The previous default of 5000 was
* always wrong: the engine has listened on 5001 since the v2
* refactor. Port 5000 is also famously hijacked on macOS by the
* AirPlay Receiver, which would return 403 to any GET regardless
* of whether an engine was running, so it produced misleading
* "no local engine" results on every macOS dev machine.
*/
function getLocalEngineBase() {
if (typeof window === "undefined") return "http://localhost:5000";
return `${window.location.protocol}//${window.location.hostname}:5000`;
const envUrl = process.env.NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL;
if (envUrl) {
// Strip a trailing `/stream` if present (the var is sometimes
// set to the WebSocket URL); also normalize ws[s]:// to http[s]://.
return envUrl
.replace(/\/stream\/?$/, "")
.replace(/^ws:\/\//, "http://")
.replace(/^wss:\/\//, "https://")
.replace(/\/+$/, "");
}
if (typeof window === "undefined") return "http://localhost:5001";
return `${window.location.protocol}//${window.location.hostname}:5001`;
}
/**
* Fetch the list of available seeders from a local engine.
* Returns null if no local engine is detected (timeout after 500ms).
*
* The engine guarantees manifest IDs are already in kebab-case (the seeder's
* exported `name` field is the canonical plugin ID). No client-side translation
* is needed — what the engine reports is what the frontend uses.
* Returns null if no local engine is detected (timeout after 2s).
*/
export async function fetchLocalEngineManifest(): Promise<string[] | null> {
if (manifestFetched) return localManifest;
+5 -2
View File
@@ -20,8 +20,11 @@ function toWsStreamUrl(url: string): string {
const DEFAULT_ENGINE_URL = toWsStreamUrl(RAW_ENGINE_URL);
function getLocalWsUrl() {
if (typeof window === "undefined") return "ws://localhost:5000/stream";
return `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.hostname}:5000/stream`;
if (process.env.NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL) {
return DEFAULT_ENGINE_URL;
}
if (typeof window === "undefined") return "ws://localhost:5001/stream";
return `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.hostname}:5001/stream`;
}
/**
* Resolves the WebSocket engine URL for a given plugin.
+31
View File
@@ -0,0 +1,31 @@
/**
* Marketplace plugins automatically installed on fresh instances.
*
* These provide a rich out-of-the-box experience — the globe looks alive
* from the very first load. Users can uninstall any of these afterwards.
*
* All core plugins are now installed via marketplace defaults.
*/
export const DEFAULT_PLUGIN_IDS = [
"aviation",
"maritime",
"military-aviation",
"wildfire",
"camera",
"borders",
"osm-search",
"earthquakes",
"satellite",
"daynight",
"conflict-zones",
"volcanoes",
"airports",
"international-sanctions",
"gps-jamming",
"fortiguard",
"nz-traffic-cameras",
"air-defense",
"civil-unrest",
"conflict-events",
"cyber-attacks",
] as const;
+25 -36
View File
@@ -4,6 +4,7 @@ import {
} from "vitest";
import { seedDefaultPlugins } from "./seedDefaultPlugins";
import { DEFAULT_PLUGIN_IDS } from "./defaultPlugins";
// ---------------------------------------------------------------------------
// Mocks — must be declared before importing the module under test
@@ -49,9 +50,6 @@ vi.stubGlobal("fetch", mockFetch);
// Helpers
// ---------------------------------------------------------------------------
/** Fake verified registry payload used by most tests. */
const FAKE_VERIFIED_IDS = ["aviation", "maritime", "surveillance-satellites"];
function fakeManifest(id: string) {
return {
id,
@@ -74,11 +72,10 @@ describe("seedDefaultPlugins", () => {
mockIsDemo = false;
delete process.env.WWV_SKIP_DEFAULT_PLUGINS;
// Defaults: not seeded, no existing plugins, manifests valid,
// verified registry returns the fake set.
// Defaults: not seeded, no existing plugins, manifests valid
mockFindFirst.mockResolvedValue(null);
mockCount.mockResolvedValue(0);
mockGetVerifiedPluginIds.mockResolvedValue(new Set(FAKE_VERIFIED_IDS));
mockGetVerifiedPluginIds.mockResolvedValue(new Set(DEFAULT_PLUGIN_IDS));
mockValidateManifest.mockReturnValue({ valid: true, errors: [] });
mockUpsertPlugin.mockResolvedValue({});
mockCreate.mockResolvedValue({});
@@ -93,11 +90,11 @@ describe("seedDefaultPlugins", () => {
}));
});
it("seeds every plugin in the verified registry on a fresh install", async () => {
it("seeds all default plugins on a fresh install", async () => {
await seedDefaultPlugins();
expect(mockUpsertPlugin).toHaveBeenCalledTimes(FAKE_VERIFIED_IDS.length);
for (const id of FAKE_VERIFIED_IDS) {
expect(mockUpsertPlugin).toHaveBeenCalledTimes(DEFAULT_PLUGIN_IDS.length);
for (const id of DEFAULT_PLUGIN_IDS) {
expect(mockUpsertPlugin).toHaveBeenCalledWith(
id,
"1.0.0",
@@ -120,7 +117,6 @@ describe("seedDefaultPlugins", () => {
expect(mockUpsertPlugin).not.toHaveBeenCalled();
expect(mockFetch).not.toHaveBeenCalled();
expect(mockGetVerifiedPluginIds).not.toHaveBeenCalled();
});
it("marks seeded without installing when plugins already exist", async () => {
@@ -137,28 +133,14 @@ describe("seedDefaultPlugins", () => {
);
});
it("does not markSeeded when the verified registry is empty", async () => {
// Simulates registry outage / signature failure / no cache
mockGetVerifiedPluginIds.mockResolvedValue(new Set<string>());
await seedDefaultPlugins();
expect(mockUpsertPlugin).not.toHaveBeenCalled();
expect(mockFetch).not.toHaveBeenCalled();
// Critical: guard row is NOT written so the next request retries
expect(mockCreate).not.toHaveBeenCalled();
expect(mockUpdateMany).not.toHaveBeenCalled();
});
it("handles marketplace manifest fetch failure gracefully", async () => {
it("handles marketplace API failure gracefully", async () => {
mockFetch.mockRejectedValue(new Error("Network error"));
await seedDefaultPlugins();
// No upserts (every manifest fetch failed), but guard row IS written
// — we got a non-empty verified set, so seeding completed (with zero
// successes); next request shouldn't retry the whole flow.
// Should NOT throw
expect(mockUpsertPlugin).not.toHaveBeenCalled();
// Guard row still written (fail-safe)
expect(mockCreate).toHaveBeenCalled();
});
@@ -169,7 +151,6 @@ describe("seedDefaultPlugins", () => {
expect(mockUpsertPlugin).not.toHaveBeenCalled();
expect(mockFetch).not.toHaveBeenCalled();
expect(mockGetVerifiedPluginIds).not.toHaveBeenCalled();
// Guard row written so it doesn't re-check
expect(mockCreate).toHaveBeenCalled();
});
@@ -181,7 +162,6 @@ describe("seedDefaultPlugins", () => {
expect(mockUpsertPlugin).not.toHaveBeenCalled();
expect(mockFetch).not.toHaveBeenCalled();
expect(mockGetVerifiedPluginIds).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
});
@@ -197,16 +177,25 @@ describe("seedDefaultPlugins", () => {
await seedDefaultPlugins();
// One fewer than total (the first was skipped)
expect(mockUpsertPlugin).toHaveBeenCalledTimes(FAKE_VERIFIED_IDS.length - 1);
expect(mockUpsertPlugin).toHaveBeenCalledTimes(DEFAULT_PLUGIN_IDS.length - 1);
});
it("stamps every seeded plugin as verified", async () => {
it("stamps trust from the verified registry", async () => {
const firstId = DEFAULT_PLUGIN_IDS[0];
// Only the first plugin is verified
mockGetVerifiedPluginIds.mockResolvedValue(new Set([firstId]));
await seedDefaultPlugins();
expect(mockUpsertPlugin).toHaveBeenCalledTimes(FAKE_VERIFIED_IDS.length);
for (const call of mockUpsertPlugin.mock.calls) {
const manifest = JSON.parse(call[2]);
expect(manifest.trust).toBe("verified");
}
// Check the first call has "verified"
const firstCall = mockUpsertPlugin.mock.calls[0];
expect(firstCall[0]).toBe(firstId);
const firstManifest = JSON.parse(firstCall[2]);
expect(firstManifest.trust).toBe("verified");
// Check a non-verified one
const secondCall = mockUpsertPlugin.mock.calls[1];
const secondManifest = JSON.parse(secondCall[2]);
expect(secondManifest.trust).toBe("unverified");
});
});
+17 -26
View File
@@ -1,6 +1,8 @@
/* eslint-disable no-console */
import { isDemo } from "@/core/edition";
import { validateManifest } from "@/core/plugins/validateManifest";
import { prisma } from "../db";
import { DEFAULT_PLUGIN_IDS } from "./defaultPlugins";
import { upsertPlugin } from "./repository";
import { getVerifiedPluginIds } from "./registryClient";
@@ -8,20 +10,16 @@ const MARKETPLACE_URL = process.env.NEXT_PUBLIC_MARKETPLACE_URL
|| "https://marketplace.worldwideview.dev";
/**
* Seed verified marketplace plugins on a fresh install.
* Seed default marketplace plugins on a fresh install.
*
* The signed registry (`getVerifiedPluginIds`) is the single source of truth
* for which plugins land in a brand-new instance — there is no hard-coded
* default list. Publish a plugin to the verified registry and it auto-seeds
* on subsequent fresh installs.
* Runs once per instance lifecycle — an idempotent guard
* (`defaults_seeded` in the Setting table) prevents re-runs.
*
* Runs at most once per instance lifecycle: an idempotent guard
* (`defaults_seeded` in the Setting table) prevents re-runs. If the registry
* is empty or unreachable on first attempt, the guard is NOT set — the next
* request retries.
* Like the "sample data" that ships with a new app: the seeder
* writes records to the database on first boot, then never runs again.
*
* Errors are logged but never thrown — a failed seed must never block the
* application from starting.
* Errors are logged but never thrown — a failed seed must never
* block the application from starting.
*/
export async function seedDefaultPlugins(): Promise<void> {
try {
@@ -47,29 +45,22 @@ export async function seedDefaultPlugins(): Promise<void> {
return;
}
const verified = await getVerifiedPluginIds();
if (verified.size === 0) {
// Registry unreachable / signature failed / empty — defer so the
// next request retries instead of locking in an empty fresh install.
console.warn(
"[DefaultPlugins] Verified registry returned empty — deferring seed, will retry next request",
);
return;
}
console.log(
`[DefaultPlugins] Fresh install detected — seeding ${verified.size} verified plugins…`,
`[DefaultPlugins] Fresh install detected — seeding ${DEFAULT_PLUGIN_IDS.length} default plugins…`,
);
const verified = await getVerifiedPluginIds();
let installed = 0;
for (const pluginId of verified) {
for (const pluginId of DEFAULT_PLUGIN_IDS) {
try {
const manifest = await fetchManifest(pluginId);
if (!manifest) continue;
// Every plugin in the verified set is by definition verified.
manifest.trust = "verified";
// Server-side trust stamping
manifest.trust = verified.has(pluginId)
? "verified"
: "unverified";
// Reconstruct CDN entry for npm-distributed plugins
if (manifest.npmPackage) {
@@ -102,7 +93,7 @@ export async function seedDefaultPlugins(): Promise<void> {
await markSeeded();
console.log(
`[DefaultPlugins] Seeded ${installed}/${verified.size} plugins`,
`[DefaultPlugins] Seeded ${installed}/${DEFAULT_PLUGIN_IDS.length} plugins`,
);
} catch (err) {
console.error("[DefaultPlugins] Seeder failed:", err);