Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
461944271b | ||
|
|
0b64459cfe | ||
|
|
e917caf7f1 | ||
|
|
6730aaff13 | ||
|
|
7c1fce98bd | ||
|
|
30bee799e1 | ||
|
|
031a073cf9 | ||
|
|
43d6a057ba | ||
|
|
9c03edb65c | ||
|
|
9f1f39203e | ||
|
|
9b459206d6 | ||
|
|
cd44a41c5d | ||
|
|
82cc79fa45 | ||
|
|
fdc722de51 | ||
|
|
be692fadaa | ||
|
|
eb12866d03 | ||
|
|
c279b7c3d1 | ||
|
|
b6d14dd720 | ||
|
|
72f485f405 | ||
|
|
8f82310e3d | ||
|
|
3fe9edf6f3 | ||
|
|
0156ead243 | ||
|
|
7bd6b32121 | ||
|
|
bc10b09788 | ||
|
|
45c41fd2a0 | ||
|
|
78fb1dc484 | ||
|
|
5fb36069ac | ||
|
|
c4207bd6e1 | ||
|
|
9ae8e58380 | ||
|
|
91e09ff53a | ||
|
|
138ea6c721 | ||
|
|
dc10e8ad5c | ||
|
|
84f694f93b | ||
|
|
fa60f845c1 | ||
|
|
6e3a8ab625 | ||
|
|
739bffa05b | ||
|
|
9888f11a4b | ||
|
|
7354b414e7 | ||
|
|
196380c0af | ||
|
|
06e919639d | ||
|
|
f948f2aaab | ||
|
|
a5125dba7b | ||
|
|
21a6c618c8 |
No files matched your search
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,118 @@
|
||||
# Persistent Custom OSM Tags Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Allow users to persistently save custom OSM tags to local storage so they remain available across sessions, and track their usage via Umami analytics.
|
||||
|
||||
**Architecture:** We will use `useState` and `useEffect` in the `OSMSidebar` component to sync `customTags` to the browser's `localStorage`. When the user enters a custom tag, we'll store it, render it with a small delete button (so the list doesn't get cluttered over time), and fire an event to `window.umami.track`.
|
||||
|
||||
**Tech Stack:** React Hooks, `localStorage`, Umami Analytics
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Add Custom Tag State and Persistence
|
||||
|
||||
**Files:**
|
||||
- Modify: `c:\dev\worldwideview-plugins\packages\wwv-plugin-osm-search\src\components\OSMSidebar.tsx`
|
||||
|
||||
- [ ] **Step 1: Add customTags state and persistence effects**
|
||||
|
||||
In `OSMSidebar.tsx`, below the existing `const [activeTags, setActiveTags] = useState<string[]>([]);` line, add:
|
||||
|
||||
```tsx
|
||||
const [customTags, setCustomTags] = useState<string[]>([]);
|
||||
|
||||
React.useEffect(() => {
|
||||
try {
|
||||
const saved = localStorage.getItem("wwv_osm_custom_tags");
|
||||
if (saved) setCustomTags(JSON.parse(saved));
|
||||
} catch {}
|
||||
}, []);
|
||||
|
||||
React.useEffect(() => {
|
||||
localStorage.setItem("wwv_osm_custom_tags", JSON.stringify(customTags));
|
||||
}, [customTags]);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Include customTags in the rendered list**
|
||||
|
||||
Replace `const customTagMatch = searchText.includes("=") ? [searchText.trim()] : [];` and `const renderedTags = ...` with:
|
||||
|
||||
```tsx
|
||||
const renderedTags = Array.from(new Set([...filteredCommon, ...dynamicTags, ...customTags]));
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Update Enter key handler to save tags and track**
|
||||
|
||||
Inside the `input`'s `onKeyDown` handler:
|
||||
|
||||
```tsx
|
||||
onKeyDown={e => {
|
||||
if (e.key === "Enter" && searchText.includes("=")) {
|
||||
const tag = searchText.trim();
|
||||
if (!activeTags.includes(tag)) {
|
||||
setActiveTags(prev => [...prev, tag]);
|
||||
}
|
||||
if (!customTags.includes(tag)) {
|
||||
setCustomTags(prev => [...prev, tag]);
|
||||
try {
|
||||
(window as any).umami?.track("osm-search-custom-tag", { tag });
|
||||
} catch {}
|
||||
}
|
||||
setSearchText("");
|
||||
}
|
||||
}}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Add a delete button to custom tags**
|
||||
|
||||
Inside the `.map(tag => {` block, update the `button` contents to include a delete span if it's a custom tag:
|
||||
|
||||
```tsx
|
||||
<button
|
||||
key={tag}
|
||||
style={{
|
||||
background: isActive ? "var(--accent-blue)" : "rgba(255,255,255,0.05)",
|
||||
color: isActive ? "#fff" : "var(--text-secondary)",
|
||||
padding: "4px 10px",
|
||||
borderRadius: "14px",
|
||||
border: `1px solid ${isActive ? "transparent" : "rgba(255,255,255,0.1)"}`,
|
||||
fontSize: "11px",
|
||||
cursor: "pointer",
|
||||
transition: "all 0.2s",
|
||||
display: "flex",
|
||||
alignItems: "center",
|
||||
gap: "4px"
|
||||
}}
|
||||
onClick={() => setActiveTags(prev => prev.includes(tag) ? prev.filter(t=>t!==tag) : [...prev, tag])}
|
||||
>
|
||||
{tag.replace("=", ": ")}
|
||||
{customTags.includes(tag) && (
|
||||
<span
|
||||
onClick={(e) => {
|
||||
e.stopPropagation();
|
||||
setCustomTags(prev => prev.filter(t => t !== tag));
|
||||
setActiveTags(prev => prev.filter(t => t !== tag));
|
||||
}}
|
||||
style={{
|
||||
marginLeft: "2px",
|
||||
padding: "0 4px",
|
||||
borderRadius: "50%",
|
||||
background: "rgba(255,255,255,0.15)",
|
||||
display: "flex",
|
||||
justifyContent: "center",
|
||||
alignItems: "center"
|
||||
}}
|
||||
>
|
||||
×
|
||||
</span>
|
||||
)}
|
||||
</button>
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Commit changes**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-plugin-osm-search/src/components/OSMSidebar.tsx
|
||||
git commit -m "feat(osm-search): persist custom tags and track via umami"
|
||||
```
|
||||
@@ -0,0 +1,132 @@
|
||||
# Robust Plugin Linking Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Ensure that when developers link local plugins using `wwv-cli link`, the main engine's database is automatically updated to prioritize the local code instead of accidentally loading the published version from the cloud CDN.
|
||||
|
||||
**Architecture:** We will implement a dedicated development API route in the main app (`/api/plugins/dev-link`) that allows the `wwv-cli` to safely push local plugin manifests directly into the `InstalledPlugin` database table without requiring Marketplace authentication. The CLI will be updated to make this request immediately after copying the bundle.
|
||||
|
||||
**Tech Stack:** Next.js API Routes, Prisma, Node.js `fetch`
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Create the Dev-Link API Route
|
||||
|
||||
**Files:**
|
||||
- Create: `c:\dev\worldwideview\src\app\api\plugins\dev-link\route.ts`
|
||||
|
||||
- [ ] **Step 1: Write the API Route**
|
||||
|
||||
```typescript
|
||||
import { NextResponse } from "next/server";
|
||||
import { upsertPlugin } from "@/lib/marketplace/repository";
|
||||
import { validateManifest } from "@/core/plugins/validateManifest";
|
||||
import { isPluginInstallEnabled } from "@/core/edition";
|
||||
|
||||
export async function POST(request: Request) {
|
||||
// 1. Security Check: Only allow in development mode or local editions
|
||||
if (process.env.NODE_ENV !== "development" && !isPluginInstallEnabled) {
|
||||
return NextResponse.json({ error: "Dev-link is only available in development environments" }, { status: 403 });
|
||||
}
|
||||
|
||||
try {
|
||||
const body = await request.json();
|
||||
const { manifest } = body;
|
||||
|
||||
if (!manifest || !manifest.id) {
|
||||
return NextResponse.json({ error: "Invalid payload. 'manifest' with an 'id' is required." }, { status: 400 });
|
||||
}
|
||||
|
||||
// 2. Validate the manifest
|
||||
const validation = validateManifest(manifest);
|
||||
if (!validation.valid) {
|
||||
console.error(`[Dev-Link] Invalid manifest for ${manifest.id}:`, validation.errors);
|
||||
return NextResponse.json({ error: "Invalid manifest", details: validation.errors }, { status: 400 });
|
||||
}
|
||||
|
||||
// 3. Upsert into database
|
||||
const config = JSON.stringify(manifest);
|
||||
const record = await upsertPlugin(manifest.id, manifest.version || "1.0.0", config);
|
||||
|
||||
console.log(`[Dev-Link] Successfully synced local plugin config for: ${manifest.id}`);
|
||||
|
||||
return NextResponse.json({ success: true, pluginId: record.pluginId });
|
||||
} catch (err) {
|
||||
console.error("[Dev-Link] Server Error:", err);
|
||||
return NextResponse.json({ error: "Internal server error" }, { status: 500 });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit API Route**
|
||||
|
||||
```bash
|
||||
git add src/app/api/plugins/dev-link/route.ts
|
||||
git commit -m "feat(api): add dev-link route to sync local plugin manifests"
|
||||
```
|
||||
|
||||
### Task 2: Update the CLI Link Command
|
||||
|
||||
**Files:**
|
||||
- Modify: `c:\dev\worldwideview-plugins\packages\wwv-cli\src\commands\link.ts`
|
||||
|
||||
- [ ] **Step 1: Add the sync request to linkCommand**
|
||||
|
||||
Find the `linkCommand` function. Below the `fs.writeFileSync` that writes `plugin.json` (around line 67), add a network request to sync the database.
|
||||
|
||||
```typescript
|
||||
fs.writeFileSync(path.join(finalDestDir, 'plugin.json'), JSON.stringify(manifest, null, 2));
|
||||
console.log(green(`✅ Proxy manifest injected to WWV instance: ${pluginId}`));
|
||||
|
||||
// --- NEW CODE: Sync with database ---
|
||||
fetch('http://localhost:3000/api/plugins/dev-link', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ manifest })
|
||||
})
|
||||
.then(res => res.json())
|
||||
.then(data => {
|
||||
if (data.success) {
|
||||
console.log(green(`✅ Database successfully synced to point to local files.`));
|
||||
} else {
|
||||
console.log(red(`⚠️ Warning: Database sync failed: ${data.error}`));
|
||||
}
|
||||
})
|
||||
.catch(err => {
|
||||
console.log(red(`⚠️ Warning: Could not reach dev server to sync DB. Is localhost:3000 running?`));
|
||||
});
|
||||
// --- END NEW CODE ---
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Rebuild the CLI**
|
||||
|
||||
```bash
|
||||
cd packages/wwv-cli
|
||||
pnpm build
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Commit CLI Update**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli/src/commands/link.ts
|
||||
git commit -m "feat(cli): auto-sync local plugin manifests with engine database during link"
|
||||
```
|
||||
|
||||
### Task 3: Test the Integration
|
||||
|
||||
- [ ] **Step 1: Run the Sync Command**
|
||||
|
||||
Run the updated sync command in the plugins repo to verify it pushes the manifest properly to the API.
|
||||
|
||||
```bash
|
||||
cd c:\dev\worldwideview-plugins
|
||||
pnpm run sync:all
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify Output**
|
||||
|
||||
Expected output in the plugins terminal should include:
|
||||
`[wwv-plugin-osm-search] ✅ Database successfully synced to point to local files.`
|
||||
|
||||
Expected output in the main WorldWideView terminal should include:
|
||||
`[Dev-Link] Successfully synced local plugin config for: osm-search`
|
||||
@@ -0,0 +1,105 @@
|
||||
# Phase 1: Database Adapter Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Modify Prisma schema and client initialization to support both SQLite (local/demo) and PostgreSQL (cloud).
|
||||
|
||||
**Architecture:** We use a pre-generation script to swap the Prisma provider based on `NEXT_PUBLIC_WWV_EDITION`. Abstract `src/lib/db.ts` to inject the correct adapter (better-sqlite3 vs pg) based on the edition.
|
||||
|
||||
**Tech Stack:** Prisma, PostgreSQL, SQLite.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Create Schema Swap Script
|
||||
|
||||
**Files:**
|
||||
- Create: `scripts/prepare-schema.mjs`
|
||||
- Modify: `package.json`
|
||||
|
||||
- [ ] **Step 1: Create a schema swap script**
|
||||
|
||||
```javascript
|
||||
// scripts/prepare-schema.mjs
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
|
||||
const schemaPath = path.join(process.cwd(), 'prisma', 'schema.prisma');
|
||||
let schema = fs.readFileSync(schemaPath, 'utf-8');
|
||||
|
||||
if (process.env.NEXT_PUBLIC_WWV_EDITION === 'cloud') {
|
||||
schema = schema.replace(/provider\s*=\s*"sqlite"/, 'provider = "postgresql"');
|
||||
console.log("Swapped Prisma provider to PostgreSQL for cloud edition.");
|
||||
} else {
|
||||
// Revert back to sqlite just in case it was swapped
|
||||
schema = schema.replace(/provider\s*=\s*"postgresql"/, 'provider = "sqlite"');
|
||||
}
|
||||
|
||||
fs.writeFileSync(schemaPath, schema);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update package.json scripts**
|
||||
|
||||
Modify `package.json` to run the prepare script before prisma generate:
|
||||
```json
|
||||
"pregenerate": "node scripts/prepare-schema.mjs",
|
||||
"generate": "prisma generate"
|
||||
```
|
||||
|
||||
### Task 2: Create DB Adapter Factory
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/lib/db.ts`
|
||||
- Create: `src/core/adapters/db.ts`
|
||||
|
||||
- [ ] **Step 1: Create the adapter factory**
|
||||
|
||||
```typescript
|
||||
// src/core/adapters/db.ts
|
||||
import { isCloud } from "@/core/edition";
|
||||
import { PrismaClient } from "../../generated/prisma/client";
|
||||
|
||||
export function createPrismaClient(): PrismaClient {
|
||||
if (isCloud) {
|
||||
// Cloud uses native pg driver or connection pool via standard url
|
||||
return new PrismaClient({
|
||||
datasources: {
|
||||
db: {
|
||||
url: process.env.DATABASE_URL,
|
||||
},
|
||||
},
|
||||
});
|
||||
} else {
|
||||
// Local uses better-sqlite3 adapter (already set up)
|
||||
const { PrismaBetterSqlite3 } = require("@prisma/adapter-better-sqlite3");
|
||||
const adapter = new PrismaBetterSqlite3({
|
||||
url: process.env.DATABASE_URL || "file:./data/wwv.db",
|
||||
});
|
||||
return new PrismaClient({ adapter });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Refactor `src/lib/db.ts`**
|
||||
|
||||
```typescript
|
||||
// src/lib/db.ts
|
||||
import { PrismaClient } from "../generated/prisma/client";
|
||||
import { createPrismaClient } from "@/core/adapters/db";
|
||||
|
||||
const globalForPrisma = globalThis as unknown as {
|
||||
prisma: PrismaClient | undefined;
|
||||
};
|
||||
|
||||
export const prisma = globalForPrisma.prisma ?? createPrismaClient();
|
||||
|
||||
if (process.env.NODE_ENV !== "production") {
|
||||
globalForPrisma.prisma = prisma;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add package.json scripts/ src/lib/ src/core/adapters/
|
||||
git commit -m "feat: multi-provider database adapter for cloud"
|
||||
```
|
||||
@@ -0,0 +1,152 @@
|
||||
# Phase 2: Tenant System Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Implement single-container multi-tenancy using PostgreSQL Row-Level Security (RLS) and Next.js middleware to resolve subdomains.
|
||||
|
||||
**Architecture:** Middleware extracts the subdomain (e.g., `acme.app.worldwideview.dev`) and sets an `x-tenant-id` header. Prisma extension wraps all queries to `SET LOCAL app.tenant_id = '...'` to enforce RLS in PostgreSQL.
|
||||
|
||||
**Tech Stack:** Next.js Middleware, Prisma Client Extensions, PostgreSQL RLS.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Database Schema Tenant Column
|
||||
|
||||
**Files:**
|
||||
- Modify: `prisma/schema.prisma`
|
||||
|
||||
- [ ] **Step 1: Add tenant columns to models**
|
||||
|
||||
Add `tenantId String?` to all relevant models (`InstalledPlugin`, `Favorite`, `Setting`).
|
||||
For local SQLite, `tenantId` is ignored (null). For cloud, it's enforced via RLS.
|
||||
|
||||
```prisma
|
||||
model InstalledPlugin {
|
||||
id String @id @default(uuid())
|
||||
tenantId String? // NULL for local, UUID for cloud
|
||||
pluginId String
|
||||
version String
|
||||
config String @default("{}")
|
||||
enabled Boolean @default(true)
|
||||
installedAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
|
||||
@@unique([tenantId, pluginId]) // Replaces @@unique([pluginId])
|
||||
@@map("installed_plugins")
|
||||
}
|
||||
|
||||
model Setting {
|
||||
id String @id @default(uuid())
|
||||
tenantId String?
|
||||
key String
|
||||
value String
|
||||
|
||||
@@unique([tenantId, key])
|
||||
@@map("settings")
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update primary keys if needed**
|
||||
|
||||
Ensure `Setting` uses `id` as `@id` instead of `key` since `key` is no longer globally unique (it's unique per tenant).
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add prisma/schema.prisma
|
||||
git commit -m "feat: add tenantId columns to schema"
|
||||
```
|
||||
|
||||
### Task 2: Subdomain Middleware
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/middleware.ts` (or create if doesn't exist)
|
||||
|
||||
- [ ] **Step 1: Create Next.js middleware**
|
||||
|
||||
```typescript
|
||||
// src/middleware.ts
|
||||
import { NextResponse } from "next/server";
|
||||
import type { NextRequest } from "next/server";
|
||||
|
||||
export function middleware(req: NextRequest) {
|
||||
const hostname = req.headers.get("host") || "";
|
||||
|
||||
// Extract subdomain if on cloud
|
||||
if (process.env.NEXT_PUBLIC_WWV_EDITION === "cloud") {
|
||||
const isApp = hostname.includes(".app.worldwideview.dev");
|
||||
if (isApp) {
|
||||
const subdomain = hostname.replace(".app.worldwideview.dev", "");
|
||||
if (subdomain && subdomain !== "app") {
|
||||
const res = NextResponse.next();
|
||||
res.headers.set("x-tenant-subdomain", subdomain);
|
||||
return res;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return NextResponse.next();
|
||||
}
|
||||
|
||||
export const config = {
|
||||
matcher: ["/((?!api/auth|_next/static|_next/image|favicon.ico).*)"],
|
||||
};
|
||||
```
|
||||
|
||||
### Task 3: Prisma RLS Extension
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/core/adapters/db.ts`
|
||||
|
||||
- [ ] **Step 1: Wrap Prisma with RLS extension for Cloud**
|
||||
|
||||
Modify `createPrismaClient` to wrap the client if in cloud mode:
|
||||
|
||||
```typescript
|
||||
// src/core/adapters/db.ts
|
||||
import { isCloud } from "@/core/edition";
|
||||
import { PrismaClient } from "../../generated/prisma/client";
|
||||
import { headers } from "next/headers";
|
||||
|
||||
export function createPrismaClient() {
|
||||
if (isCloud) {
|
||||
const client = new PrismaClient({
|
||||
datasources: { db: { url: process.env.DATABASE_URL } },
|
||||
});
|
||||
|
||||
// Use Prisma Client Extension to inject RLS
|
||||
return client.$extends({
|
||||
query: {
|
||||
$allModels: {
|
||||
async $allOperations({ args, query }) {
|
||||
const headersList = await headers();
|
||||
const tenantSubdomain = headersList.get("x-tenant-subdomain");
|
||||
|
||||
if (tenantSubdomain) {
|
||||
const [, result] = await client.$transaction([
|
||||
client.$executeRaw`SELECT set_config('app.tenant_id', ${tenantSubdomain}, TRUE)`,
|
||||
query(args),
|
||||
]);
|
||||
return result;
|
||||
}
|
||||
return query(args);
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
} else {
|
||||
const { PrismaBetterSqlite3 } = require("@prisma/adapter-better-sqlite3");
|
||||
const adapter = new PrismaBetterSqlite3({
|
||||
url: process.env.DATABASE_URL || "file:./data/wwv.db",
|
||||
});
|
||||
return new PrismaClient({ adapter });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add src/middleware.ts src/core/adapters/db.ts
|
||||
git commit -m "feat: multi-tenant middleware and RLS prisma extension"
|
||||
```
|
||||
@@ -0,0 +1,117 @@
|
||||
# Phase 3: Auth Upgrade Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Integrate Supabase Auth for the cloud edition while maintaining the existing Credentials provider for the local edition.
|
||||
|
||||
**Architecture:** Use the NextAuth adapter pattern. Modify `src/lib/auth.ts` to dynamically include the Supabase provider and Supabase Adapter if `isCloud` is true.
|
||||
|
||||
**Tech Stack:** NextAuth v5, Supabase Auth.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Supabase Adapter Integration
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/lib/auth.ts`
|
||||
- Modify: `package.json`
|
||||
|
||||
- [ ] **Step 1: Install Supabase NextAuth Adapter**
|
||||
|
||||
Run: `pnpm add @auth/supabase-adapter`
|
||||
|
||||
- [ ] **Step 2: Update `src/lib/auth.ts` to branch providers**
|
||||
|
||||
```typescript
|
||||
// src/lib/auth.ts
|
||||
import NextAuth from "next-auth";
|
||||
import Credentials from "next-auth/providers/credentials";
|
||||
import { compareSync } from "bcryptjs";
|
||||
import { timingSafeEqual } from "crypto";
|
||||
import { prisma } from "@/lib/db";
|
||||
import { isDemo, isCloud, getDemoAdminSecret, DEMO_ADMIN_ROLE } from "@/core/edition";
|
||||
import { authConfig } from "@/lib/auth.config";
|
||||
import { SupabaseAdapter } from "@auth/supabase-adapter";
|
||||
|
||||
// Extract local credentials logic to a helper
|
||||
const localCredentialsProvider = Credentials({
|
||||
credentials: {
|
||||
email: { label: "Email", type: "email" },
|
||||
password: { label: "Password", type: "password" },
|
||||
},
|
||||
async authorize(credentials) {
|
||||
// ... existing credentials logic ...
|
||||
return null;
|
||||
}
|
||||
});
|
||||
|
||||
export const { handlers, auth, signIn, signOut } = NextAuth({
|
||||
...authConfig,
|
||||
session: { strategy: "jwt" },
|
||||
adapter: isCloud ? SupabaseAdapter({
|
||||
url: process.env.NEXT_PUBLIC_SUPABASE_URL!,
|
||||
secret: process.env.SUPABASE_SERVICE_ROLE_KEY!,
|
||||
}) : undefined,
|
||||
providers: isCloud
|
||||
? [] // If using standard GoTrue via custom logic, or add providers here if using NextAuth OAuth
|
||||
: [localCredentialsProvider],
|
||||
callbacks: {
|
||||
...authConfig.callbacks,
|
||||
// ... existing callbacks ...
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Task 2: Login Form Cloud Adaptation
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/app/login/page.tsx`
|
||||
- Modify: `src/app/login/actions.ts`
|
||||
|
||||
- [ ] **Step 1: Update Login Form for Cloud Mode**
|
||||
|
||||
```typescript
|
||||
// src/app/login/actions.ts
|
||||
import { signIn } from "@/lib/auth";
|
||||
import { isCloud } from "@/core/edition";
|
||||
import { createClient } from "@supabase/supabase-js";
|
||||
|
||||
export async function loginAction(formData: FormData) {
|
||||
const email = formData.get("email") as string;
|
||||
const password = formData.get("password") as string;
|
||||
|
||||
if (isCloud) {
|
||||
// Use Supabase GoTrue
|
||||
const supabase = createClient(
|
||||
process.env.NEXT_PUBLIC_SUPABASE_URL!,
|
||||
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
|
||||
);
|
||||
const { data, error } = await supabase.auth.signInWithPassword({
|
||||
email,
|
||||
password,
|
||||
});
|
||||
|
||||
if (error) return { success: false, error: error.message };
|
||||
return { success: true };
|
||||
} else {
|
||||
// Use NextAuth Credentials
|
||||
try {
|
||||
await signIn("credentials", {
|
||||
email,
|
||||
password,
|
||||
redirect: false,
|
||||
});
|
||||
return { success: true };
|
||||
} catch (error: any) {
|
||||
return { success: false, error: "Invalid credentials" };
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add package.json pnpm-lock.yaml src/lib/auth.ts src/app/login/actions.ts
|
||||
git commit -m "feat: supabase auth adapter for cloud edition"
|
||||
```
|
||||
@@ -0,0 +1,99 @@
|
||||
# Phase 4: License Keys & Tiers Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Implement RSA-signed JWT license keys to gate Pro and Enterprise features on both Local and Cloud editions.
|
||||
|
||||
**Architecture:** A hardcoded public key verifies the JWT. The JWT payload dictates the tier (`free`, `pro`, `enterprise`) and expiration. The `uiSlice` state provides easy access to the active tier.
|
||||
|
||||
**Tech Stack:** `jose` for JWT verification.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: License Verification Module
|
||||
|
||||
**Files:**
|
||||
- Create: `src/core/license/verifyLicense.ts`
|
||||
- Create: `src/core/license/tiers.ts`
|
||||
|
||||
- [ ] **Step 1: Create Tier Definitions**
|
||||
|
||||
```typescript
|
||||
// src/core/license/tiers.ts
|
||||
export type LicenseTier = "free" | "pro" | "team" | "enterprise";
|
||||
|
||||
export interface TierFeatures {
|
||||
maxUsers: number;
|
||||
storageQuotaBytes: number;
|
||||
historyEnabled: boolean;
|
||||
snapshotCapture: boolean;
|
||||
customDomains: boolean;
|
||||
}
|
||||
|
||||
export const TIER_FEATURES: Record<LicenseTier, TierFeatures> = {
|
||||
free: { maxUsers: 3, storageQuotaBytes: 500 * 1024 * 1024, historyEnabled: false, snapshotCapture: false, customDomains: false },
|
||||
pro: { maxUsers: 20, storageQuotaBytes: 5 * 1024 * 1024 * 1024, historyEnabled: true, snapshotCapture: true, customDomains: false },
|
||||
team: { maxUsers: -1, storageQuotaBytes: -1, historyEnabled: true, snapshotCapture: true, customDomains: false },
|
||||
enterprise: { maxUsers: -1, storageQuotaBytes: -1, historyEnabled: true, snapshotCapture: true, customDomains: true },
|
||||
};
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Create JWT Verification**
|
||||
|
||||
```typescript
|
||||
// src/core/license/verifyLicense.ts
|
||||
import * as jose from "jose";
|
||||
|
||||
// Public key is safe to hardcode/ship to client
|
||||
const PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
|
||||
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu... (generate real one)
|
||||
-----END PUBLIC KEY-----`;
|
||||
|
||||
export interface LicensePayload {
|
||||
tier: "pro" | "team" | "enterprise";
|
||||
exp: number;
|
||||
org: string;
|
||||
}
|
||||
|
||||
export async function verifyLicenseKey(token: string): Promise<LicensePayload | null> {
|
||||
try {
|
||||
const publicKey = await jose.importSPKI(PUBLIC_KEY_PEM, "RS256");
|
||||
const { payload } = await jose.jwtVerify(token, publicKey);
|
||||
return payload as unknown as LicensePayload;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Task 2: State Integration
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/core/state/configSlice.ts`
|
||||
- Modify: `src/components/panels/SettingsPanel.tsx`
|
||||
|
||||
- [ ] **Step 1: Add license to configSlice**
|
||||
|
||||
```typescript
|
||||
// src/core/state/configSlice.ts
|
||||
// Add to DataConfig:
|
||||
export interface DataConfig {
|
||||
// ... existing ...
|
||||
licenseKey: string | null;
|
||||
activeTier: "free" | "pro" | "team" | "enterprise";
|
||||
}
|
||||
|
||||
// Add to initial state:
|
||||
// licenseKey: null, activeTier: "free"
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Add License input UI**
|
||||
|
||||
Add a text input in `SettingsPanel` for users to paste their license key, dispatching an action to verify and save it to the DB and Zustand store.
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add src/core/license/ src/core/state/configSlice.ts src/components/panels/
|
||||
git commit -m "feat: rsa jwt license key verification"
|
||||
```
|
||||
@@ -0,0 +1,76 @@
|
||||
# Phase 5: Cloud Deployment Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Create the Docker Compose configuration and routing layer necessary to run the multi-tenant cloud application.
|
||||
|
||||
**Architecture:** Use Traefik or nginx to route wildcard subdomains to the Next.js container. Provide environment variable overrides.
|
||||
|
||||
**Tech Stack:** Docker Compose, Traefik.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Docker Compose Setup
|
||||
|
||||
**Files:**
|
||||
- Create: `deploy/cloud/docker-compose.yml`
|
||||
- Create: `deploy/cloud/.env.example`
|
||||
|
||||
- [ ] **Step 1: Create compose file**
|
||||
|
||||
```yaml
|
||||
# deploy/cloud/docker-compose.yml
|
||||
services:
|
||||
wwv-cloud:
|
||||
image: ghcr.io/silvertakana/worldwideview:latest
|
||||
restart: always
|
||||
environment:
|
||||
NEXT_PUBLIC_WWV_EDITION: cloud
|
||||
DATABASE_URL: ${SUPABASE_PG_URL}
|
||||
NEXT_PUBLIC_SUPABASE_URL: ${SUPABASE_URL}
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY: ${SUPABASE_ANON_KEY}
|
||||
SUPABASE_SERVICE_ROLE_KEY: ${SUPABASE_SERVICE_ROLE_KEY}
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.wwv.rule=HostRegexp(`{user:[a-z0-9-]+}.app.worldwideview.dev`) || Host(`app.worldwideview.dev`)"
|
||||
- "traefik.http.routers.wwv.entrypoints=websecure"
|
||||
- "traefik.http.routers.wwv.tls.certresolver=letsencrypt"
|
||||
|
||||
traefik:
|
||||
image: traefik:v3.0
|
||||
command:
|
||||
- "--api.insecure=true"
|
||||
- "--providers.docker=true"
|
||||
- "--entrypoints.web.address=:80"
|
||||
- "--entrypoints.websecure.address=:443"
|
||||
- "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
|
||||
- "--certificatesresolvers.letsencrypt.acme.email=${ACME_EMAIL}"
|
||||
- "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- "/var/run/docker.sock:/var/run/docker.sock:ro"
|
||||
- "letsencrypt:/letsencrypt"
|
||||
|
||||
volumes:
|
||||
letsencrypt:
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Create example env file**
|
||||
|
||||
```env
|
||||
# deploy/cloud/.env.example
|
||||
SUPABASE_PG_URL=postgresql://postgres:[email protected]:5432/postgres
|
||||
SUPABASE_URL=https://xyz.supabase.co
|
||||
SUPABASE_ANON_KEY=eyJ...
|
||||
SUPABASE_SERVICE_ROLE_KEY=eyJ...
|
||||
ACME_EMAIL=[email protected]
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add deploy/
|
||||
git commit -m "chore: add cloud deployment compose configuration"
|
||||
```
|
||||
@@ -0,0 +1,77 @@
|
||||
# Phase 6: Stripe Billing Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Implement Stripe subscriptions for the cloud edition, generating license keys upon payment.
|
||||
|
||||
**Architecture:** Use Stripe Checkout Sessions for upgrades. Use Stripe Webhooks to listen for `checkout.session.completed` and `customer.subscription.updated` to update the user's tier in the database and generate their JWT license key.
|
||||
|
||||
**Tech Stack:** Stripe Node SDK, Next.js API Routes.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Stripe Integration
|
||||
|
||||
**Files:**
|
||||
- Modify: `package.json`
|
||||
- Create: `src/lib/stripe/client.ts`
|
||||
- Create: `src/app/api/billing/webhook/route.ts`
|
||||
- Create: `src/app/api/billing/checkout/route.ts`
|
||||
|
||||
- [ ] **Step 1: Install SDK**
|
||||
|
||||
Run: `pnpm add stripe`
|
||||
|
||||
- [ ] **Step 2: Create Stripe Client**
|
||||
|
||||
```typescript
|
||||
// src/lib/stripe/client.ts
|
||||
import Stripe from "stripe";
|
||||
|
||||
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
|
||||
apiVersion: "2024-04-10",
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Create Checkout Route**
|
||||
|
||||
```typescript
|
||||
// src/app/api/billing/checkout/route.ts
|
||||
import { stripe } from "@/lib/stripe/client";
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth } from "@/lib/auth";
|
||||
|
||||
export async function POST(req: Request) {
|
||||
const session = await auth();
|
||||
if (!session?.user) return new NextResponse("Unauthorized", { status: 401 });
|
||||
|
||||
const { priceId } = await req.json();
|
||||
|
||||
const checkoutSession = await stripe.checkout.sessions.create({
|
||||
mode: "subscription",
|
||||
payment_method_types: ["card"],
|
||||
line_items: [{ price: priceId, quantity: 1 }],
|
||||
success_url: `${process.env.NEXT_PUBLIC_APP_URL}/settings?success=true`,
|
||||
cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/settings?canceled=true`,
|
||||
client_reference_id: session.user.id,
|
||||
});
|
||||
|
||||
return NextResponse.json({ url: checkoutSession.url });
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Create Webhook Handler**
|
||||
|
||||
```typescript
|
||||
// src/app/api/billing/webhook/route.ts
|
||||
import { stripe } from "@/lib/stripe/client";
|
||||
import { NextResponse } from "next/server";
|
||||
// ... basic webhook payload verification and logging ...
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add package.json pnpm-lock.yaml src/lib/stripe/ src/app/api/billing/
|
||||
git commit -m "feat: stripe checkout and webhook integration"
|
||||
```
|
||||
@@ -0,0 +1,51 @@
|
||||
# Cloud Hosting & Plans — Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Transform WorldWideView from a local-only SQLite app into a multi-tenant cloud platform with `[user].app.worldwideview.dev` subdomains, PostgreSQL RLS isolation, Supabase Auth, cryptographic license keys, and Stripe billing.
|
||||
|
||||
**Architecture:** Single Docker container serves all tenants. nginx wildcard routes `*.app.worldwideview.dev` → Next.js. Middleware reads subdomain → sets `tenant_id` → PostgreSQL RLS scopes all queries. Same codebase, three editions (`local`/`cloud`/`demo`), adapter pattern for DB/auth/storage/tenant.
|
||||
|
||||
**Tech Stack:** Next.js 16, Prisma (multi-provider), PostgreSQL + RLS, Supabase Auth, Supabase Storage, RSA-signed JWTs (license keys), Stripe Checkout + Webhooks, nginx wildcard SSL.
|
||||
|
||||
---
|
||||
|
||||
## Current State Summary
|
||||
|
||||
| Component | Status |
|
||||
|---|---|
|
||||
| Edition system (`edition.ts`) | ✅ `local`/`cloud`/`demo` flags exist |
|
||||
| Auth (`src/lib/auth.ts`) | ✅ Credentials provider (bcrypt + SQLite) |
|
||||
| Database (`src/lib/db.ts`) | ⚠️ Hardcoded to `better-sqlite3` adapter |
|
||||
| Prisma schema | ⚠️ `provider = "sqlite"` only |
|
||||
| Tenant isolation | ❌ Not implemented |
|
||||
| Cloud auth (Supabase) | ❌ Not implemented |
|
||||
| License keys | ❌ Not implemented |
|
||||
| Storage adapter | ❌ Not implemented |
|
||||
| Stripe billing | ❌ Not implemented |
|
||||
| Cloud deployment repo | ❌ Not created |
|
||||
|
||||
---
|
||||
|
||||
## Phase Breakdown
|
||||
|
||||
Each phase is a self-contained deliverable. Phases 1–3 are foundational. Phases 4–6 add monetization.
|
||||
|
||||
| Phase | File | What It Builds | Depends On |
|
||||
|---|---|---|---|
|
||||
| 1 | [01-database-adapter.md](./01-database-adapter.md) | Prisma multi-provider (SQLite + PostgreSQL) | Nothing |
|
||||
| 2 | [02-tenant-system.md](./02-tenant-system.md) | RLS isolation, middleware, tenant context | Phase 1 |
|
||||
| 3 | [03-auth-upgrade.md](./03-auth-upgrade.md) | Supabase Auth provider for cloud edition | Phase 1 |
|
||||
| 4 | [04-license-keys.md](./04-license-keys.md) | RSA-signed JWT license keys, tier gating | Phase 1 |
|
||||
| 5 | [05-cloud-deployment.md](./05-cloud-deployment.md) | `worldwideview-cloud` repo, nginx, Docker Compose | Phases 1–3 |
|
||||
| 6 | [06-stripe-billing.md](./06-stripe-billing.md) | Stripe Checkout, webhooks, subscription management | Phases 3–4 |
|
||||
|
||||
---
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
1. **Adapter pattern** — Three thin files (`src/core/adapters/db.ts`, `auth.ts`, `storage.ts`, `tenant.ts`) branch on `edition`. Everything else is edition-unaware.
|
||||
2. **Prisma multi-provider** — Use a build-time script to swap the provider in `schema.prisma` before generating the client if building for cloud. One schema, two providers.
|
||||
3. **RLS over application-level filtering** — PostgreSQL physically refuses cross-tenant data. Even bugs can't leak.
|
||||
4. **License keys are RSA JWTs** — Marketplace signs with private key; app verifies with hardcoded public key. No phone-home required.
|
||||
5. **Stripe is the only payment processor** — Checkout Sessions for signup, Webhooks for lifecycle events.
|
||||
@@ -0,0 +1,533 @@
|
||||
# WorldWideView CLI Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Build `@worldwideview/cli`, a standalone CLI tool that scaffolds, hot-reloads, and packages WWV plugins using the Chrome Extension model, completely decoupled from the main monorepo build pipeline.
|
||||
|
||||
**Architecture:** A Node.js CLI built with `commander`. It uses `vite` programmatically to serve and build plugins. For dev mode, it attaches a `ws` WebSocket server to the Vite dev server to broadcast hot-reload events to the running WWV web app, and communicates with `/api/dev/load-unpacked` to inject the plugin. Publishing creates a `.wwvpkg` ZIP archive via `archiver`.
|
||||
|
||||
**Tech Stack:** Node.js, TypeScript, Commander, Vite, WebSocket (`ws`), Archiver, Vitest.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Initialize Package & CLI Entry Point
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-cli/package.json`
|
||||
- Create: `packages/wwv-cli/tsconfig.json`
|
||||
- Create: `packages/wwv-cli/bin/wwv.js`
|
||||
- Create: `packages/wwv-cli/src/index.ts`
|
||||
- Create: `packages/wwv-cli/tests/index.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/index.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { execSync } from "child_process";
|
||||
import path from "path";
|
||||
|
||||
describe("wwv cli", () => {
|
||||
it("should print help information", () => {
|
||||
const binPath = path.resolve(__dirname, "../bin/wwv.js");
|
||||
const output = execSync(`node ${binPath} --help`).toString();
|
||||
expect(output).toContain("Usage: wwv [options] [command]");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm test`
|
||||
Expected: FAIL (File not found or missing package.json setup)
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
```json
|
||||
// packages/wwv-cli/package.json
|
||||
{
|
||||
"name": "@worldwideview/cli",
|
||||
"version": "1.0.0",
|
||||
"bin": { "wwv": "./bin/wwv.js" },
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"test": "vitest run"
|
||||
},
|
||||
"dependencies": {
|
||||
"commander": "^11.1.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"typescript": "^5.0.0",
|
||||
"vitest": "^1.0.0",
|
||||
"@types/node": "^20.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// packages/wwv-cli/tsconfig.json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "CommonJS",
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true
|
||||
},
|
||||
"include": ["src/**/*"]
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
// packages/wwv-cli/bin/wwv.js
|
||||
#!/usr/bin/env node
|
||||
require('../dist/index.js');
|
||||
```
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/index.ts
|
||||
import { Command } from "commander";
|
||||
|
||||
const program = new Command();
|
||||
|
||||
program
|
||||
.name("wwv")
|
||||
.description("WorldWideView Plugin CLI")
|
||||
.version("1.0.0");
|
||||
|
||||
program.parse();
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm install && pnpm run build && pnpm test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli
|
||||
git commit -m "feat(wwv-cli): initialize cli package and entry point"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Implement `wwv create` (Scaffolding)
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-cli/src/commands/create.ts`
|
||||
- Create: `packages/wwv-cli/tests/create.test.ts`
|
||||
- Modify: `packages/wwv-cli/src/index.ts:10-15`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/create.test.ts
|
||||
import { describe, it, expect, afterEach } from "vitest";
|
||||
import { createPlugin } from "../src/commands/create";
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
|
||||
describe("create command", () => {
|
||||
const testDir = path.join(__dirname, "test-plugin");
|
||||
|
||||
afterEach(() => {
|
||||
if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it("should scaffold a new plugin folder with manifest and index.ts", async () => {
|
||||
await createPlugin("test-plugin", __dirname);
|
||||
expect(fs.existsSync(path.join(testDir, "wwv-manifest.json"))).toBe(true);
|
||||
expect(fs.existsSync(path.join(testDir, "src", "index.ts"))).toBe(true);
|
||||
|
||||
const manifest = JSON.parse(fs.readFileSync(path.join(testDir, "wwv-manifest.json"), "utf-8"));
|
||||
expect(manifest.id).toBe("test-plugin");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm test tests/create.test.ts`
|
||||
Expected: FAIL ("createPlugin is not defined")
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/commands/create.ts
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
|
||||
export async function createPlugin(name: string, basePath: string = process.cwd()) {
|
||||
const targetDir = path.join(basePath, name);
|
||||
if (fs.existsSync(targetDir)) {
|
||||
throw new Error(`Directory ${name} already exists`);
|
||||
}
|
||||
|
||||
fs.mkdirSync(targetDir, { recursive: true });
|
||||
fs.mkdirSync(path.join(targetDir, "src"), { recursive: true });
|
||||
|
||||
const manifest = {
|
||||
manifest_version: 1,
|
||||
id: name,
|
||||
name: name,
|
||||
version: "1.0.0",
|
||||
description: "A WorldWideView plugin",
|
||||
type: "data-layer",
|
||||
category: "custom",
|
||||
icon: "Box",
|
||||
capabilities: ["data:own"],
|
||||
entry: "dist/frontend.mjs",
|
||||
dev_entry: "src/index.ts"
|
||||
};
|
||||
|
||||
fs.writeFileSync(
|
||||
path.join(targetDir, "wwv-manifest.json"),
|
||||
JSON.stringify(manifest, null, 2)
|
||||
);
|
||||
|
||||
const indexContent = `export default class MyPlugin {
|
||||
id = "${name}";
|
||||
name = "${name}";
|
||||
version = "1.0.0";
|
||||
category = "custom";
|
||||
icon = "Box";
|
||||
|
||||
async initialize(ctx) {
|
||||
console.log("Initialized", this.id);
|
||||
}
|
||||
|
||||
destroy() {}
|
||||
|
||||
async fetch(timeRange) {
|
||||
return [];
|
||||
}
|
||||
|
||||
getPollingInterval() {
|
||||
return 5000;
|
||||
}
|
||||
|
||||
getLayerConfig() {
|
||||
return { color: "#3b82f6", clusterEnabled: true, clusterDistance: 50 };
|
||||
}
|
||||
|
||||
renderEntity(entity) {
|
||||
return { type: "point", color: "#3b82f6", size: 6 };
|
||||
}
|
||||
}
|
||||
`;
|
||||
fs.writeFileSync(path.join(targetDir, "src", "index.ts"), indexContent);
|
||||
console.log(`Plugin ${name} scaffolded successfully in ./${name}`);
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Modify packages/wwv-cli/src/index.ts (add this before program.parse())
|
||||
import { createPlugin } from "./commands/create";
|
||||
|
||||
program
|
||||
.command("create <name>")
|
||||
.description("Scaffold a new WorldWideView plugin")
|
||||
.action(async (name) => {
|
||||
try {
|
||||
await createPlugin(name);
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm run build && pnpm test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli
|
||||
git commit -m "feat(wwv-cli): implement create command for scaffolding"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Implement `wwv dev` (Vite Server + WebSocket)
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-cli/src/commands/dev.ts`
|
||||
- Create: `packages/wwv-cli/tests/dev.test.ts`
|
||||
- Modify: `packages/wwv-cli/src/index.ts:25-30`
|
||||
- Modify: `packages/wwv-cli/package.json:13-15` (Add vite, ws)
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/dev.test.ts
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import { startDevServer } from "../src/commands/dev";
|
||||
|
||||
// Mock vite and ws
|
||||
vi.mock("vite", () => ({
|
||||
createServer: vi.fn().mockResolvedValue({
|
||||
listen: vi.fn(),
|
||||
httpServer: { on: vi.fn() },
|
||||
ws: { on: vi.fn() }
|
||||
})
|
||||
}));
|
||||
|
||||
describe("dev command", () => {
|
||||
it("should export startDevServer function", () => {
|
||||
expect(typeof startDevServer).toBe("function");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm test tests/dev.test.ts`
|
||||
Expected: FAIL ("startDevServer is not defined")
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
Add `vite` and `ws` to dependencies in `packages/wwv-cli/package.json` and run `pnpm install`:
|
||||
```json
|
||||
"dependencies": {
|
||||
"commander": "^11.1.0",
|
||||
"vite": "^5.0.0",
|
||||
"ws": "^8.16.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/ws": "^8.5.10"
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/commands/dev.ts
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
import { createServer } from "vite";
|
||||
import { WebSocketServer } from "ws";
|
||||
|
||||
export async function startDevServer(targetUrl: string = "http://localhost:3000") {
|
||||
const cwd = process.cwd();
|
||||
const manifestPath = path.join(cwd, "wwv-manifest.json");
|
||||
|
||||
if (!fs.existsSync(manifestPath)) {
|
||||
throw new Error("No wwv-manifest.json found in current directory");
|
||||
}
|
||||
|
||||
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
|
||||
const port = 24601;
|
||||
|
||||
// Start Vite Dev Server
|
||||
const vite = await createServer({
|
||||
root: cwd,
|
||||
server: { port, cors: true, hmr: false }, // We handle HMR via custom WS
|
||||
plugins: [{
|
||||
name: 'wwv-hmr',
|
||||
handleHotUpdate({ server }) {
|
||||
// When Vite detects file changes, broadcast to our custom WS
|
||||
wss.clients.forEach(client => {
|
||||
client.send(JSON.stringify({ type: "plugin:updated", pluginId: manifest.id }));
|
||||
});
|
||||
return []; // Prevent default Vite HMR
|
||||
}
|
||||
}]
|
||||
});
|
||||
|
||||
await vite.listen();
|
||||
|
||||
// Attach custom WebSocket server for WWV DevModeSubscriber
|
||||
const wss = new WebSocketServer({ server: vite.httpServer as any, path: "/__wwv_dev__" });
|
||||
|
||||
wss.on("connection", (ws) => {
|
||||
console.log(`[WWV CLI] Connected to WorldWideView instance`);
|
||||
ws.send(JSON.stringify({ type: "plugin:added", manifest }));
|
||||
});
|
||||
|
||||
// Notify WorldWideView via API
|
||||
try {
|
||||
const fetch = (await import('node-fetch')).default || globalThis.fetch;
|
||||
await fetch(`${targetUrl}/api/dev/load-unpacked`, {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({
|
||||
...manifest,
|
||||
entry: `http://localhost:${port}/${manifest.dev_entry || "src/index.ts"}`
|
||||
})
|
||||
});
|
||||
console.log(`[WWV CLI] Registered with WorldWideView at ${targetUrl}`);
|
||||
} catch (err: any) {
|
||||
console.error(`[WWV CLI] Failed to connect to ${targetUrl}: ${err.message}`);
|
||||
console.log(`Waiting for WorldWideView to connect via WebSocket...`);
|
||||
}
|
||||
|
||||
console.log(`\n🚀 Dev server running on http://localhost:${port}`);
|
||||
console.log(`Watching for file changes in ${cwd}...\n`);
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Modify packages/wwv-cli/src/index.ts (add this before program.parse())
|
||||
import { startDevServer } from "./commands/dev";
|
||||
|
||||
program
|
||||
.command("dev")
|
||||
.description("Start the plugin development server with hot-reload")
|
||||
.option("-t, --target <url>", "Target WorldWideView URL", "http://localhost:3000")
|
||||
.action(async (options) => {
|
||||
try {
|
||||
await startDevServer(options.target);
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm run build && pnpm test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli
|
||||
git commit -m "feat(wwv-cli): implement dev command with vite and websockets"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Implement `wwv publish` (.wwvpkg creation)
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-cli/src/commands/publish.ts`
|
||||
- Create: `packages/wwv-cli/tests/publish.test.ts`
|
||||
- Modify: `packages/wwv-cli/src/index.ts:40-45`
|
||||
- Modify: `packages/wwv-cli/package.json:16-17` (Add archiver)
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/publish.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { buildPackage } from "../src/commands/publish";
|
||||
|
||||
describe("publish command", () => {
|
||||
it("should export buildPackage function", () => {
|
||||
expect(typeof buildPackage).toBe("function");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm test tests/publish.test.ts`
|
||||
Expected: FAIL ("buildPackage is not defined")
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
Add `archiver` to dependencies in `packages/wwv-cli/package.json` and run `pnpm install`:
|
||||
```json
|
||||
"dependencies": {
|
||||
"archiver": "^7.0.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/archiver": "^6.0.2"
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/commands/publish.ts
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
import { build } from "vite";
|
||||
import archiver from "archiver";
|
||||
|
||||
export async function buildPackage() {
|
||||
const cwd = process.cwd();
|
||||
const manifestPath = path.join(cwd, "wwv-manifest.json");
|
||||
|
||||
if (!fs.existsSync(manifestPath)) {
|
||||
throw new Error("No wwv-manifest.json found in current directory");
|
||||
}
|
||||
|
||||
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
|
||||
|
||||
console.log(`[WWV CLI] Building production bundle...`);
|
||||
await build({
|
||||
root: cwd,
|
||||
build: {
|
||||
lib: {
|
||||
entry: path.resolve(cwd, manifest.dev_entry || "src/index.ts"),
|
||||
name: 'WWVPlugin',
|
||||
formats: ['es'],
|
||||
fileName: () => 'frontend.mjs'
|
||||
},
|
||||
outDir: 'dist',
|
||||
emptyOutDir: true
|
||||
}
|
||||
});
|
||||
|
||||
const pkgName = `${manifest.id}-${manifest.version}.wwvpkg`;
|
||||
const outputPath = path.join(cwd, pkgName);
|
||||
|
||||
console.log(`[WWV CLI] Creating archive ${pkgName}...`);
|
||||
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
const output = fs.createWriteStream(outputPath);
|
||||
const archive = archiver("zip", { zlib: { level: 9 } });
|
||||
|
||||
output.on("close", () => resolve());
|
||||
archive.on("error", (err) => reject(err));
|
||||
|
||||
archive.pipe(output);
|
||||
|
||||
archive.file(manifestPath, { name: "wwv-manifest.json" });
|
||||
archive.directory(path.join(cwd, "dist"), "dist");
|
||||
|
||||
if (fs.existsSync(path.join(cwd, "data"))) {
|
||||
archive.directory(path.join(cwd, "data"), "data");
|
||||
}
|
||||
|
||||
archive.finalize();
|
||||
});
|
||||
|
||||
console.log(`\n🎉 Success! Package created at ${outputPath}`);
|
||||
console.log(`You can now upload this file to the WorldWideView Marketplace.`);
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Modify packages/wwv-cli/src/index.ts (add this before program.parse())
|
||||
import { buildPackage } from "./commands/publish";
|
||||
|
||||
program
|
||||
.command("publish")
|
||||
.description("Build and package the plugin into a .wwvpkg file")
|
||||
.action(async () => {
|
||||
try {
|
||||
await buildPackage();
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd packages/wwv-cli && pnpm run build && pnpm test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli
|
||||
git commit -m "feat(wwv-cli): implement publish command for wwvpkg creation"
|
||||
```
|
||||
@@ -0,0 +1,323 @@
|
||||
# Split CLI Publish into Package and Publish Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Split the CLI publish command into `package` (for local .wwvpkg zip creation) and `publish` (for NPM distribution and marketplace registry updates).
|
||||
|
||||
**Architecture:**
|
||||
The current `publish` command creates a `.wwvpkg` file. We will rename this functionality to the `package` command. Then, we will create a true `publish` command that handles building the plugin, automatically generating a valid `package.json` from the `wwv-manifest.json`, running `npm publish` via a child process, and finally notifying the marketplace of the new release.
|
||||
|
||||
**Tech Stack:** TypeScript, Vite, Node.js `child_process`, Node.js `fs`.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Rename current publish to package
|
||||
|
||||
We will rename the file and its internal function from `buildPackage` to `packagePlugin`.
|
||||
|
||||
**Files:**
|
||||
- Modify: `packages/wwv-cli/src/commands/publish.ts` -> rename to `packages/wwv-cli/src/commands/package.ts`
|
||||
- Modify: `packages/wwv-cli/tests/publish.test.ts` -> rename to `packages/wwv-cli/tests/package.test.ts`
|
||||
|
||||
- [ ] **Step 1: Rename the command file and update function name**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/commands/package.ts
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
import { build } from "vite";
|
||||
import archiver from "archiver";
|
||||
|
||||
export async function packagePlugin() {
|
||||
const cwd = process.cwd();
|
||||
const manifestPath = path.join(cwd, "wwv-manifest.json");
|
||||
|
||||
if (!fs.existsSync(manifestPath)) {
|
||||
throw new Error("No wwv-manifest.json found in current directory");
|
||||
}
|
||||
|
||||
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
|
||||
|
||||
console.log(`[WWV CLI] Building production bundle...`);
|
||||
await build({
|
||||
root: cwd,
|
||||
build: {
|
||||
lib: {
|
||||
entry: path.resolve(cwd, manifest.dev_entry || "src/index.ts"),
|
||||
name: 'WWVPlugin',
|
||||
formats: ['es'],
|
||||
fileName: () => 'frontend.mjs'
|
||||
},
|
||||
outDir: 'dist',
|
||||
emptyOutDir: true
|
||||
}
|
||||
});
|
||||
|
||||
const pkgName = `${manifest.id}-${manifest.version}.wwvpkg`;
|
||||
const outputPath = path.join(cwd, pkgName);
|
||||
|
||||
console.log(`[WWV CLI] Creating archive ${pkgName}...`);
|
||||
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
const output = fs.createWriteStream(outputPath);
|
||||
const archive = archiver("zip", { zlib: { level: 9 } });
|
||||
|
||||
output.on("close", () => resolve());
|
||||
archive.on("error", (err) => reject(err));
|
||||
|
||||
archive.pipe(output);
|
||||
|
||||
archive.file(manifestPath, { name: "wwv-manifest.json" });
|
||||
archive.directory(path.join(cwd, "dist"), "dist");
|
||||
|
||||
if (fs.existsSync(path.join(cwd, "data"))) {
|
||||
archive.directory(path.join(cwd, "data"), "data");
|
||||
}
|
||||
|
||||
archive.finalize();
|
||||
});
|
||||
|
||||
console.log(`\n🎉 Success! Package created at ${outputPath}`);
|
||||
console.log(`You can use this file to sideload the plugin into your WWV instance.`);
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Rename and update the test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/package.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { packagePlugin } from "../src/commands/package";
|
||||
|
||||
describe("package command", () => {
|
||||
it("should export packagePlugin function", () => {
|
||||
expect(typeof packagePlugin).toBe("function");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Remove old files**
|
||||
|
||||
Run: `git rm packages/wwv-cli/src/commands/publish.ts packages/wwv-cli/tests/publish.test.ts`
|
||||
Expected: Files deleted.
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli/src/commands/package.ts packages/wwv-cli/tests/package.test.ts
|
||||
git commit -m "refactor(wwv-cli): rename publish to package for wwvpkg creation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Implement true NPM Publish command
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-cli/src/commands/publish.ts`
|
||||
- Create: `packages/wwv-cli/tests/publish.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/tests/publish.test.ts
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import { publishToNpm } from "../src/commands/publish";
|
||||
|
||||
vi.mock("child_process", () => ({
|
||||
execSync: vi.fn()
|
||||
}));
|
||||
vi.mock("vite", () => ({
|
||||
build: vi.fn().mockResolvedValue({})
|
||||
}));
|
||||
|
||||
describe("publish command", () => {
|
||||
it("should export publishToNpm function", () => {
|
||||
expect(typeof publishToNpm).toBe("function");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `pnpm test tests/publish.test.ts` inside `packages/wwv-cli`
|
||||
Expected: FAIL because `publishToNpm` does not exist.
|
||||
|
||||
- [ ] **Step 3: Write the publish implementation**
|
||||
|
||||
```typescript
|
||||
// packages/wwv-cli/src/commands/publish.ts
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
import { build } from "vite";
|
||||
import { execSync } from "child_process";
|
||||
|
||||
export async function publishToNpm() {
|
||||
const cwd = process.cwd();
|
||||
const manifestPath = path.join(cwd, "wwv-manifest.json");
|
||||
|
||||
if (!fs.existsSync(manifestPath)) {
|
||||
throw new Error("No wwv-manifest.json found in current directory");
|
||||
}
|
||||
|
||||
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
|
||||
|
||||
console.log(`[WWV CLI] Compiling bundle for NPM...`);
|
||||
await build({
|
||||
root: cwd,
|
||||
build: {
|
||||
lib: {
|
||||
entry: path.resolve(cwd, manifest.dev_entry || "src/index.ts"),
|
||||
name: 'WWVPlugin',
|
||||
formats: ['es'],
|
||||
fileName: () => 'frontend.mjs'
|
||||
},
|
||||
outDir: 'dist',
|
||||
emptyOutDir: true
|
||||
}
|
||||
});
|
||||
|
||||
console.log(`[WWV CLI] Generating package.json...`);
|
||||
// Create a temporary package.json required for NPM publish
|
||||
const packageJsonPath = path.join(cwd, "package.json");
|
||||
const packageJson = {
|
||||
name: manifest.id, // e.g. @username/my-plugin
|
||||
version: manifest.version,
|
||||
description: manifest.description,
|
||||
main: "dist/frontend.mjs",
|
||||
type: "module",
|
||||
files: ["dist", "wwv-manifest.json", "data"],
|
||||
keywords: ["worldwideview", "plugin", manifest.category],
|
||||
author: manifest.author || ""
|
||||
};
|
||||
|
||||
fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
|
||||
|
||||
console.log(`[WWV CLI] Publishing to NPM...`);
|
||||
try {
|
||||
execSync(`npm publish --access public`, { stdio: "inherit", cwd });
|
||||
} catch (err) {
|
||||
console.error(`[WWV CLI] NPM publish failed. Please ensure you are logged in via 'npm login'.`);
|
||||
throw err;
|
||||
} finally {
|
||||
// Clean up the generated package.json so it doesn't clutter the dev's repo
|
||||
fs.unlinkSync(packageJsonPath);
|
||||
}
|
||||
|
||||
console.log(`[WWV CLI] Notifying WorldWideView Marketplace...`);
|
||||
try {
|
||||
const targetUrl = process.env.WWV_MARKETPLACE_URL || "https://marketplace.worldwideview.dev";
|
||||
await fetch(`${targetUrl}/api/webhooks/npm-publish`, {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ pluginId: manifest.id, version: manifest.version })
|
||||
});
|
||||
console.log(`[WWV CLI] Marketplace notified.`);
|
||||
} catch (err: any) {
|
||||
console.warn(`[WWV CLI] Could not notify marketplace: ${err.message}. It will be indexed on the next sweep.`);
|
||||
}
|
||||
|
||||
console.log(`\n🚀 Success! Version ${manifest.version} published globally to NPM.`);
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `pnpm test tests/publish.test.ts` inside `packages/wwv-cli`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli/src/commands/publish.ts packages/wwv-cli/tests/publish.test.ts
|
||||
git commit -m "feat(wwv-cli): implement npm publish and marketplace webhook ping"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Update CLI Entry Point
|
||||
|
||||
**Files:**
|
||||
- Modify: `packages/wwv-cli/src/index.ts:36-50`
|
||||
|
||||
- [ ] **Step 1: Write the updated entry point logic**
|
||||
|
||||
Replace the existing `publish` command logic with both `package` and `publish`:
|
||||
|
||||
```typescript
|
||||
// Edit packages/wwv-cli/src/index.ts
|
||||
import { Command } from "commander";
|
||||
import { createPlugin } from "./commands/create";
|
||||
import { startDevServer } from "./commands/dev";
|
||||
import { packagePlugin } from "./commands/package";
|
||||
import { publishToNpm } from "./commands/publish";
|
||||
|
||||
const program = new Command();
|
||||
|
||||
program
|
||||
.name("wwv")
|
||||
.description("WorldWideView Plugin CLI")
|
||||
.version("1.0.0");
|
||||
|
||||
program
|
||||
.command("create <name>")
|
||||
.description("Scaffold a new WorldWideView plugin")
|
||||
.action(async (name) => {
|
||||
try {
|
||||
await createPlugin(name);
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
program
|
||||
.command("dev")
|
||||
.description("Start the plugin development server with hot-reload")
|
||||
.option("-t, --target <url>", "Target WorldWideView URL", "http://localhost:3000")
|
||||
.action(async (options) => {
|
||||
try {
|
||||
await startDevServer(options.target);
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
program
|
||||
.command("package")
|
||||
.description("Build and package the plugin into a .wwvpkg file for sideloading")
|
||||
.action(async () => {
|
||||
try {
|
||||
await packagePlugin();
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
program
|
||||
.command("publish")
|
||||
.description("Publish the plugin to NPM and notify the WWV Marketplace")
|
||||
.action(async () => {
|
||||
try {
|
||||
await publishToNpm();
|
||||
} catch (err: any) {
|
||||
console.error("Error:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
|
||||
program.parse();
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Build to verify no TypeScript errors**
|
||||
|
||||
Run: `pnpm run build` inside `packages/wwv-cli`
|
||||
Expected: Clean build.
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add packages/wwv-cli/src/index.ts
|
||||
git commit -m "feat(wwv-cli): register package and npm publish commands"
|
||||
```
|
||||
@@ -0,0 +1,53 @@
|
||||
# Prisma 7 Setup Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Finalize the Prisma 7 adapter architecture by removing legacy `url` parameters from the schema, syncing the local database, and validating the end-to-end connection.
|
||||
|
||||
**Architecture:** Prisma 7 strictly separates connection logic from the schema. The schema only defines the provider (`postgresql`), while connection strings for CLI commands like `db push` are handled by `prisma.config.ts`, and runtime connections are handled by the explicit `@prisma/adapter-pg` driver instance passed to the `PrismaClient` constructor.
|
||||
|
||||
**Tech Stack:** Prisma 7, PostgreSQL, Next.js, Node.js
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Update Prisma Schema
|
||||
|
||||
**Files:**
|
||||
- Modify: `prisma/schema.prisma:5-8`
|
||||
|
||||
- [ ] **Step 1: Remove the legacy `url` property from the datasource block**
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
}
|
||||
```
|
||||
|
||||
### Task 2: Push Schema to Local Database
|
||||
|
||||
- [ ] **Step 1: Execute Prisma db push to create the tables in the newly running Docker Postgres container**
|
||||
|
||||
Run: `npx dotenv-cli -e .env.local -- npx prisma db push`
|
||||
Expected: PASS with "Your database is now in sync with your schema."
|
||||
|
||||
### Task 3: Generate Prisma Client
|
||||
|
||||
- [ ] **Step 1: Regenerate the Prisma Client types to ensure they match the schema**
|
||||
|
||||
Run: `npx dotenv-cli -e .env.local -- npx prisma generate`
|
||||
Expected: PASS with "Generated Prisma Client"
|
||||
|
||||
### Task 4: Verify End-to-End Connection
|
||||
|
||||
- [ ] **Step 1: Run the user management script to prove the `adapter-pg` runtime can connect and query the new tables**
|
||||
|
||||
Run: `npx tsx --env-file=.env.local scripts/manage-users.ts list`
|
||||
Expected: PASS with no errors (it should just exit silently if there are no users, rather than throwing a `P2021 TableDoesNotExist` or `P1001` error).
|
||||
|
||||
### Task 5: Restart the Development Server
|
||||
|
||||
- [ ] **Step 1: Restart the Next.js dev server**
|
||||
Because the server has been running while we were debugging the `PrismaClientInitializationError`, Webpack may have cached the broken client. We need to kill the current `pnpm run dev` and start it fresh so we can test the API routes in the browser.
|
||||
|
||||
Run: Terminate the current `pnpm run dev` terminal, then run: `pnpm run dev`
|
||||
Expected: Next.js starts successfully without any Prisma instantiation crashes.
|
||||
@@ -0,0 +1,618 @@
|
||||
# Unify Database Adapter (PostgreSQL-Only) Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.
|
||||
|
||||
**Goal:** Replace the dual SQLite/PostgreSQL database system with a single PostgreSQL adapter, using Prisma's built-in `prisma dev` for zero-install local development.
|
||||
|
||||
**Architecture:** The app currently has two database paths — `@prisma/adapter-better-sqlite3` for local and `@prisma/adapter-pg` for cloud — which causes constant migration conflicts and config drift. We unify to `@prisma/adapter-pg` everywhere. Local developers use `npx prisma dev` (PGLite-backed local Postgres managed by Prisma CLI) or their own Postgres instance. Production connects to Supabase via the same adapter and connection string swap.
|
||||
|
||||
**Tech Stack:** Prisma 7, `@prisma/adapter-pg`, `pg`, PostgreSQL, Next.js 16
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
| Action | File | Responsibility |
|
||||
|---|---|---|
|
||||
| Modify | `prisma/schema.prisma` | Change provider to `postgresql` |
|
||||
| **Rewrite** | `src/lib/db.ts` | Single PostgreSQL adapter factory |
|
||||
| Delete | `src/core/adapters/db.ts` | Remove cloud-branch adapter factory (merge into `db.ts`) |
|
||||
| Modify | `package.json` | Remove `better-sqlite3` + adapter deps, add `pg` |
|
||||
| Modify | `next.config.ts` | Remove `better-sqlite3` from `serverExternalPackages` |
|
||||
| Modify | `docker-entrypoint.sh` | Update comments, remove SQLite references |
|
||||
| Modify | `Dockerfile` | Remove SQLite build step, update env defaults |
|
||||
| Modify | `local-dev.ps1` | Add `prisma dev` startup guidance |
|
||||
| Modify | `.env` | Change default `DATABASE_URL` to local PostgreSQL |
|
||||
| Modify | `prisma.config.ts` | No changes needed (already reads `DATABASE_URL`) |
|
||||
| Modify | `scripts/cleanup-plugins.ts` | Use shared `db.ts` instead of hardcoded SQLite |
|
||||
| Modify | `scripts/manage-users.ts` | Use shared `db.ts` instead of hardcoded SQLite |
|
||||
| Keep | `scripts/migrate-aviation-history.ts` | This is a one-off Supabase-to-SQLite migration tool. Leave as-is but mark deprecated |
|
||||
| **Delete** | `prisma/migrations/` | Remove old SQLite migrations (will regenerate for PostgreSQL) |
|
||||
| **Create** | `prisma/migrations/` | Fresh PostgreSQL init migration |
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Update Prisma Schema Provider
|
||||
|
||||
**Files:**
|
||||
- Modify: `prisma/schema.prisma:1-6`
|
||||
|
||||
- [x] **Step 1: Change the datasource provider from SQLite to PostgreSQL**
|
||||
|
||||
Open `prisma/schema.prisma` and replace the datasource block:
|
||||
|
||||
```prisma
|
||||
// Prisma schema — PostgreSQL for all environments.
|
||||
// Local dev: use `npx prisma dev` for a zero-install local PGLite instance.
|
||||
// Cloud/Production: set DATABASE_URL to your Supabase/Postgres connection string.
|
||||
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
}
|
||||
```
|
||||
|
||||
Leave the `generator` block and all models unchanged.
|
||||
|
||||
- [x] **Step 2: Verify the schema is valid**
|
||||
|
||||
Run:
|
||||
```powershell
|
||||
npx prisma validate
|
||||
```
|
||||
|
||||
Expected: `The schema at prisma/schema.prisma is valid.`
|
||||
|
||||
- [x] **Step 3: Commit**
|
||||
|
||||
```powershell
|
||||
git add prisma/schema.prisma
|
||||
git commit -m "refactor(db): switch schema provider from sqlite to postgresql"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Remove SQLite Dependencies
|
||||
|
||||
**Files:**
|
||||
- Modify: `package.json:22-80`
|
||||
- Modify: `next.config.ts:5`
|
||||
|
||||
- [x] **Step 1: Remove better-sqlite3 packages from package.json**
|
||||
|
||||
In `package.json`, remove these lines from `dependencies`:
|
||||
```diff
|
||||
- "@prisma/adapter-better-sqlite3": "^7.5.0",
|
||||
```
|
||||
|
||||
Remove from `pnpm.onlyBuiltDependencies`:
|
||||
```diff
|
||||
- "better-sqlite3",
|
||||
```
|
||||
|
||||
Ensure `@prisma/adapter-pg` and `pg` remain (they're already present):
|
||||
```json
|
||||
"@prisma/adapter-pg": "^7.8.0",
|
||||
"pg": "^8.20.0",
|
||||
```
|
||||
|
||||
- [x] **Step 2: Update serverExternalPackages in next.config.ts**
|
||||
|
||||
In `next.config.ts` line 5, replace:
|
||||
```typescript
|
||||
serverExternalPackages: ["better-sqlite3", "@prisma/adapter-better-sqlite3", "@prisma/client", "prisma"],
|
||||
```
|
||||
|
||||
With:
|
||||
```typescript
|
||||
serverExternalPackages: ["@prisma/client", "prisma", "pg"],
|
||||
```
|
||||
|
||||
- [x] **Step 3: Install to update lockfile**
|
||||
|
||||
Run:
|
||||
```powershell
|
||||
pnpm install
|
||||
```
|
||||
|
||||
Expected: Clean install with no `better-sqlite3` compilation step.
|
||||
|
||||
- [x] **Step 4: Commit**
|
||||
|
||||
```powershell
|
||||
git add package.json next.config.ts pnpm-lock.yaml
|
||||
git commit -m "refactor(db): remove better-sqlite3 dependencies"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Rewrite the Database Adapter Factory
|
||||
|
||||
**Files:**
|
||||
- Rewrite: `src/lib/db.ts`
|
||||
|
||||
- [x] **Step 1: Replace db.ts with a unified PostgreSQL adapter**
|
||||
|
||||
Replace the entire contents of `src/lib/db.ts` with:
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from "../generated/prisma";
|
||||
import { PrismaPg } from "@prisma/adapter-pg";
|
||||
import { Pool } from "pg";
|
||||
|
||||
/**
|
||||
* Prisma client singleton — PostgreSQL only.
|
||||
*
|
||||
* Local dev: Run `npx prisma dev` for a zero-install local Postgres.
|
||||
* Production: Set DATABASE_URL to your Supabase/Postgres connection string.
|
||||
*
|
||||
* Uses globalThis to survive Next.js HMR in development.
|
||||
*/
|
||||
|
||||
const globalForPrisma = globalThis as unknown as {
|
||||
prisma: PrismaClient | undefined;
|
||||
};
|
||||
|
||||
function createPrismaClient(): PrismaClient {
|
||||
const connectionString = process.env.DATABASE_URL;
|
||||
|
||||
if (!connectionString) {
|
||||
throw new Error(
|
||||
"[db] DATABASE_URL is not set. " +
|
||||
"Run `npx prisma dev` for local development, " +
|
||||
"or set DATABASE_URL to your PostgreSQL connection string."
|
||||
);
|
||||
}
|
||||
|
||||
const pool = new Pool({ connectionString });
|
||||
const adapter = new PrismaPg(pool);
|
||||
|
||||
return new PrismaClient({ adapter } as any);
|
||||
}
|
||||
|
||||
export const prisma = globalForPrisma.prisma ?? createPrismaClient();
|
||||
|
||||
if (process.env.NODE_ENV !== "production") {
|
||||
globalForPrisma.prisma = prisma;
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** The `feature/cloud-hosting-core` branch has a more complex version at `src/core/adapters/db.ts` with tenant isolation via `applyTenantIsolation()`. When merging that branch later, the tenant isolation extension should be layered on top of this unified base — it does NOT need a separate SQLite path.
|
||||
|
||||
- [x] **Step 2: Verify TypeScript compilation**
|
||||
|
||||
Run:
|
||||
```powershell
|
||||
npx tsc --noEmit --pretty 2>&1 | Select-String "db.ts"
|
||||
```
|
||||
|
||||
Expected: No errors related to `db.ts`.
|
||||
|
||||
- [x] **Step 3: Commit**
|
||||
|
||||
```powershell
|
||||
git add src/lib/db.ts
|
||||
git commit -m "refactor(db): unify adapter to postgresql-only via PrismaPg"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Update Utility Scripts
|
||||
|
||||
**Files:**
|
||||
- Modify: `scripts/cleanup-plugins.ts`
|
||||
- Modify: `scripts/manage-users.ts`
|
||||
|
||||
- [x] **Step 1: Rewrite cleanup-plugins.ts to use shared db**
|
||||
|
||||
Replace the entire contents of `scripts/cleanup-plugins.ts`:
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from "../src/generated/prisma/index.js";
|
||||
import { PrismaPg } from "@prisma/adapter-pg";
|
||||
import { Pool } from "pg";
|
||||
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
|
||||
const adapter = new PrismaPg(pool);
|
||||
const prisma = new PrismaClient({ adapter } as any);
|
||||
|
||||
async function main() {
|
||||
const plugins = await prisma.installedPlugin.findMany();
|
||||
console.log("Installed plugins:");
|
||||
plugins.forEach((p) => console.log(` ${p.pluginId} | config: ${p.config.substring(0, 60)}`));
|
||||
|
||||
const geojson = plugins.find((p) => p.pluginId === "geojson");
|
||||
if (geojson) {
|
||||
await prisma.installedPlugin.delete({ where: { id: geojson.id } });
|
||||
console.log("\nDeleted orphaned 'geojson' record.");
|
||||
} else {
|
||||
console.log("\nNo orphaned 'geojson' record found.");
|
||||
}
|
||||
|
||||
const remaining = await prisma.installedPlugin.findMany();
|
||||
console.log("\nRemaining plugins:");
|
||||
remaining.forEach((p) => console.log(` ${p.pluginId}`));
|
||||
|
||||
await prisma.$disconnect();
|
||||
}
|
||||
|
||||
main().catch(console.error);
|
||||
```
|
||||
|
||||
- [x] **Step 2: Rewrite manage-users.ts to use shared db**
|
||||
|
||||
Replace the entire contents of `scripts/manage-users.ts`:
|
||||
|
||||
```typescript
|
||||
import { PrismaClient } from "../src/generated/prisma/index.js";
|
||||
import { PrismaPg } from "@prisma/adapter-pg";
|
||||
import { Pool } from "pg";
|
||||
import { hashSync } from "bcryptjs";
|
||||
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
|
||||
const adapter = new PrismaPg(pool);
|
||||
const prisma = new PrismaClient({ adapter } as any);
|
||||
|
||||
async function main() {
|
||||
const action = process.argv[2];
|
||||
|
||||
if (action === "list") {
|
||||
const users = await prisma.user.findMany();
|
||||
if (users.length === 0) {
|
||||
console.log("No users found — visit /setup to create one.");
|
||||
} else {
|
||||
users.forEach((u) =>
|
||||
console.log(` ${u.email} | ${u.name} | ${u.role} | ${u.createdAt}`)
|
||||
);
|
||||
}
|
||||
} else if (action === "reset") {
|
||||
const email = process.argv[3];
|
||||
const newPass = process.argv[4];
|
||||
if (!email || !newPass) {
|
||||
console.log("Usage: tsx scripts/manage-users.ts reset <email> <password>");
|
||||
return;
|
||||
}
|
||||
const hashed = hashSync(newPass, 12);
|
||||
await prisma.user.update({
|
||||
where: { email },
|
||||
data: { hashedPassword: hashed },
|
||||
});
|
||||
console.log(`Password reset for ${email}`);
|
||||
} else if (action === "delete-all") {
|
||||
await prisma.user.deleteMany();
|
||||
console.log("All users deleted — visit /setup to create a new admin.");
|
||||
} else {
|
||||
console.log("Usage: tsx scripts/manage-users.ts <list|reset|delete-all>");
|
||||
}
|
||||
|
||||
await prisma.$disconnect();
|
||||
}
|
||||
|
||||
main().catch(console.error);
|
||||
```
|
||||
|
||||
- [x] **Step 3: Add deprecation notice to migrate-aviation-history.ts**
|
||||
|
||||
Add this comment at the top of `scripts/migrate-aviation-history.ts`:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* @deprecated This script uses better-sqlite3 directly to migrate data
|
||||
* from Supabase into the legacy data engine's SQLite database.
|
||||
* It is NOT part of the main application's database layer.
|
||||
* It will be removed once the data engine migration is complete.
|
||||
*/
|
||||
```
|
||||
|
||||
- [x] **Step 4: Commit**
|
||||
|
||||
```powershell
|
||||
git add scripts/cleanup-plugins.ts scripts/manage-users.ts scripts/migrate-aviation-history.ts
|
||||
git commit -m "refactor(scripts): update utility scripts to use postgresql adapter"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Create Fresh PostgreSQL Migration
|
||||
|
||||
**Files:**
|
||||
- Delete: `prisma/migrations/` (entire directory)
|
||||
- Create: `prisma/migrations/YYYYMMDD_init/migration.sql` (generated by Prisma)
|
||||
|
||||
- [x] **Step 1: Delete old SQLite migrations**
|
||||
|
||||
```powershell
|
||||
Remove-Item -Recurse -Force prisma/migrations
|
||||
```
|
||||
|
||||
- [x] **Step 2: Ensure a local PostgreSQL is available**
|
||||
|
||||
Either:
|
||||
- Run `npx prisma dev` in a separate terminal, OR
|
||||
- Use your existing local PostgreSQL at `127.0.0.1:5432`
|
||||
|
||||
Verify the connection string in `.env.local` points to a reachable PostgreSQL instance:
|
||||
```
|
||||
DATABASE_URL="postgresql://postgres:[email protected]:5432/postgres?schema=public"
|
||||
```
|
||||
|
||||
- [x] **Step 3: Reset and create initial migration**
|
||||
|
||||
```powershell
|
||||
npx prisma migrate reset --force
|
||||
npx prisma migrate dev --name init
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
Applying migration `YYYYMMDDHHMMSS_init`
|
||||
The following migration(s) have been created and applied...
|
||||
```
|
||||
|
||||
- [x] **Step 4: Verify migration_lock.toml says postgresql**
|
||||
|
||||
```powershell
|
||||
Get-Content prisma/migrations/migration_lock.toml
|
||||
```
|
||||
|
||||
Expected:
|
||||
```
|
||||
provider = "postgresql"
|
||||
```
|
||||
|
||||
- [x] **Step 5: Commit**
|
||||
|
||||
```powershell
|
||||
git add prisma/migrations
|
||||
git commit -m "feat(db): create initial postgresql migration"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Update Dockerfile and Entrypoint
|
||||
|
||||
**Files:**
|
||||
- Modify: `Dockerfile:11,36-38,49,54`
|
||||
- Modify: `docker-entrypoint.sh:3-5`
|
||||
|
||||
- [x] **Step 1: Update Dockerfile**
|
||||
|
||||
Make these changes to `Dockerfile`:
|
||||
|
||||
**Line 11** — Remove `python3 make g++` (no longer need to compile better-sqlite3 native bindings):
|
||||
```dockerfile
|
||||
RUN apk add --no-cache python3 make g++
|
||||
```
|
||||
Replace with:
|
||||
```dockerfile
|
||||
# python3/make/g++ no longer needed — removed better-sqlite3 native compilation
|
||||
```
|
||||
|
||||
**Lines 36-38** — Remove the conditional SQLite build step entirely:
|
||||
```dockerfile
|
||||
# Create an empty SQLite database with all tables applied ONLY IF NOT CLOUD
|
||||
# (For cloud, we'll run migrations against Postgres at runtime)
|
||||
RUN if [ "$NEXT_PUBLIC_WWV_EDITION" != "cloud" ]; then mkdir -p ./data && DATABASE_URL=file:./data/wwv.db npx prisma migrate deploy; fi
|
||||
```
|
||||
Replace with:
|
||||
```dockerfile
|
||||
# Database migrations run at container startup via docker-entrypoint.sh
|
||||
# DATABASE_URL must be set to a PostgreSQL connection string
|
||||
```
|
||||
|
||||
**Line 49** — Keep `prisma` global install (needed for `migrate deploy` at runtime).
|
||||
|
||||
**Line 54** — Remove the SQLite default DATABASE_URL:
|
||||
```dockerfile
|
||||
ENV DATABASE_URL=file:./data/wwv.db
|
||||
```
|
||||
Replace with:
|
||||
```dockerfile
|
||||
# DATABASE_URL must be provided via environment variable (no default)
|
||||
# Example: postgresql://user:pass@host:5432/dbname
|
||||
```
|
||||
|
||||
- [x] **Step 2: Update docker-entrypoint.sh comments**
|
||||
|
||||
Replace lines 2-5 of `docker-entrypoint.sh`:
|
||||
```bash
|
||||
# ─── Docker Entrypoint ───────────────────────────────────────
|
||||
# Ensures the SQLite database exists and is migrated before
|
||||
# starting the application. On first run with a fresh volume
|
||||
# the DB file won't exist yet, so we run prisma migrate deploy.
|
||||
```
|
||||
|
||||
With:
|
||||
```bash
|
||||
# ─── Docker Entrypoint ───────────────────────────────────────
|
||||
# Ensures the PostgreSQL database is migrated before starting
|
||||
# the application. DATABASE_URL must point to a PostgreSQL
|
||||
# instance (Supabase, self-hosted, etc).
|
||||
```
|
||||
|
||||
Remove `mkdir -p ./data` from line 9 (no longer creating a local SQLite file):
|
||||
```bash
|
||||
set -e
|
||||
|
||||
echo "[entrypoint] Running database migrations..."
|
||||
prisma migrate deploy
|
||||
echo "[entrypoint] Migrations complete."
|
||||
```
|
||||
|
||||
- [x] **Step 3: Commit**
|
||||
|
||||
```powershell
|
||||
git add Dockerfile docker-entrypoint.sh
|
||||
git commit -m "refactor(docker): remove sqlite from build and runtime"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 7: Update Environment Defaults and Dev Scripts
|
||||
|
||||
**Files:**
|
||||
- Modify: `.env:1`
|
||||
- Modify: `package.json:13` (predev script)
|
||||
- Modify: `local-dev.ps1`
|
||||
|
||||
- [x] **Step 1: Update .env default DATABASE_URL**
|
||||
|
||||
Replace line 1 of `.env`:
|
||||
```
|
||||
DATABASE_URL=file:./data/wwv.db
|
||||
```
|
||||
|
||||
With:
|
||||
```
|
||||
# PostgreSQL connection string.
|
||||
# For local dev: run `npx prisma dev` and use the URL it prints.
|
||||
# For production: set to your Supabase/Postgres connection string.
|
||||
# DATABASE_URL=postgresql://postgres:[email protected]:5432/worldwideview
|
||||
```
|
||||
|
||||
> **Important:** The default is now commented out. The `.env.local` file (or `npx prisma dev`) must provide the actual value. This forces contributors to explicitly set up their database rather than silently falling back to a potentially broken SQLite path.
|
||||
|
||||
- [x] **Step 2: Simplify the predev script**
|
||||
|
||||
In `package.json`, the `predev` script currently runs `npx prisma migrate deploy`. This will fail if no Postgres is running. Change it to only copy Cesium assets and generate the Prisma client:
|
||||
|
||||
```json
|
||||
"predev": "npx prisma generate && node scripts/copy-cesium.mjs",
|
||||
```
|
||||
|
||||
> **Rationale:** `prisma migrate deploy` should only run in production (Docker entrypoint) or explicitly by the developer. During local dev, `npx prisma dev` handles migrations automatically.
|
||||
|
||||
- [x] **Step 3: Update local-dev.ps1**
|
||||
|
||||
Replace the entire contents of `local-dev.ps1`:
|
||||
|
||||
```powershell
|
||||
Write-Host "[*] Setting up WorldWideView for Local Development..."
|
||||
|
||||
# Check for pnpm
|
||||
try {
|
||||
$null = Get-Command pnpm -ErrorAction Stop
|
||||
} catch {
|
||||
Write-Host "[Error] pnpm is not installed or not in PATH."
|
||||
Write-Host "Please install it first: https://pnpm.io/installation"
|
||||
exit 1
|
||||
}
|
||||
|
||||
Write-Host "[*] Installing dependencies..."
|
||||
pnpm install
|
||||
|
||||
Write-Host "[*] Running initial setup (generating secrets)..."
|
||||
pnpm run setup
|
||||
|
||||
Write-Host "[*] Generating Prisma client..."
|
||||
npx prisma generate
|
||||
|
||||
# Check for the sibling Data Engine repository
|
||||
if (-not (Test-Path "../wwv-data-engine")) {
|
||||
Write-Host ""
|
||||
Write-Host "=====================================================================" -ForegroundColor Yellow
|
||||
Write-Host "[!] NOTICE: Local Data Engine not found at ../wwv-data-engine" -ForegroundColor Yellow
|
||||
Write-Host ""
|
||||
Write-Host "Frontend-Only Mode: You are developing the frontend UI." -ForegroundColor Green
|
||||
Write-Host "WorldWideView will automatically stream data from the Cloud Engine." -ForegroundColor Green
|
||||
Write-Host ""
|
||||
Write-Host "Full-Stack Mode: If you want to develop backend data seeders, you" -ForegroundColor Cyan
|
||||
Write-Host "must clone the open-source data engine as a sibling directory:" -ForegroundColor Cyan
|
||||
Write-Host " cd ..; git clone https://github.com/silvertakana/wwv-data-engine"
|
||||
Write-Host " cd wwv-data-engine; pnpm install"
|
||||
Write-Host "=====================================================================" -ForegroundColor Yellow
|
||||
Write-Host ""
|
||||
}
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "=====================================================================" -ForegroundColor Cyan
|
||||
Write-Host "[!] DATABASE SETUP REQUIRED" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
Write-Host "WorldWideView uses PostgreSQL. Choose one option:" -ForegroundColor White
|
||||
Write-Host ""
|
||||
Write-Host " Option A (Easiest): Run Prisma's built-in local database:" -ForegroundColor Green
|
||||
Write-Host " npx prisma dev" -ForegroundColor Yellow
|
||||
Write-Host " (Copy the DATABASE_URL it prints into your .env.local file)" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
Write-Host " Option B: Use your own PostgreSQL or Supabase instance:" -ForegroundColor Green
|
||||
Write-Host " Set DATABASE_URL in .env.local to your connection string" -ForegroundColor Gray
|
||||
Write-Host "=====================================================================" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
|
||||
Write-Host "[*] Starting local Next.js frontend server..."
|
||||
Write-Host " (To run the data engine backends concurrently, run: pnpm dev:all)"
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
- [x] **Step 4: Commit**
|
||||
|
||||
```powershell
|
||||
git add .env package.json local-dev.ps1
|
||||
git commit -m "refactor(dev): update env defaults and dev scripts for postgresql"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 8: Run Tests and Validate
|
||||
|
||||
**Files:**
|
||||
- No file changes — validation only
|
||||
|
||||
- [x] **Step 1: Generate Prisma client**
|
||||
|
||||
```powershell
|
||||
npx prisma generate
|
||||
```
|
||||
|
||||
Expected: `Generated Prisma Client to ./src/generated/prisma`
|
||||
|
||||
- [x] **Step 2: Run the test suite**
|
||||
|
||||
```powershell
|
||||
pnpm test
|
||||
```
|
||||
|
||||
Expected: All tests pass. The repository tests mock `db.ts`, so the adapter change should be transparent to them.
|
||||
|
||||
- [x] **Step 3: Start the dev server**
|
||||
|
||||
Ensure your `.env.local` has a valid `DATABASE_URL` pointing to PostgreSQL, then:
|
||||
|
||||
```powershell
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
Expected: Server starts at `http://localhost:3000` without `P3005` or `P3018` errors.
|
||||
|
||||
- [x] **Step 4: Verify database operations work**
|
||||
|
||||
1. Navigate to `http://localhost:3000/setup` — create a test user
|
||||
2. Log in
|
||||
3. Open the Plugins panel — verify installed plugins load
|
||||
4. Star a favorite entity — verify it persists across reload
|
||||
|
||||
- [x] **Step 5: Final commit**
|
||||
|
||||
```powershell
|
||||
git add -A
|
||||
git commit -m "test(db): verify postgresql-only adapter works end-to-end"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Post-Implementation Notes
|
||||
|
||||
### For the `feature/cloud-hosting-core` merge
|
||||
|
||||
When merging the cloud-hosting-core branch back into main, the `src/core/adapters/db.ts` file with `applyTenantIsolation()` should be integrated into `src/lib/db.ts` as a wrapper around the single `PrismaPg` adapter. The conditional SQLite path in that file can be completely removed.
|
||||
|
||||
### For self-hosted Docker users
|
||||
|
||||
Add a note to the release changelog:
|
||||
|
||||
> **Breaking Change:** WorldWideView now requires a PostgreSQL database. SQLite is no longer supported.
|
||||
> Self-hosted users must provide a `DATABASE_URL` environment variable pointing to a PostgreSQL instance.
|
||||
> The easiest option is a free Supabase project, or run `docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=pass postgres:17-alpine` alongside your WWV container.
|
||||
|
||||
### For the migrate-aviation-history.ts script
|
||||
|
||||
This script uses `better-sqlite3` directly to talk to the data engine's separate SQLite database (not the platform database). It is unrelated to this migration and can remain as-is. If `better-sqlite3` is needed for this script, install it as a `devDependency` only, or move the script to the data engine repo where it belongs.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
trigger: glob
|
||||
description: Strict guidelines for rendering geospatial entities, handling 3D terrain clipping, and applying dynamic animation properties against Cesium's runtime engine.
|
||||
globs: "src/core/globe/**/*"
|
||||
---
|
||||
|
||||
# Cesium Rendering Rules
|
||||
|
||||
## Purpose
|
||||
Strict guidelines for rendering geospatial entities, handling 3D terrain clipping, and applying dynamic animation properties against Cesium's runtime engine.
|
||||
|
||||
## When to Apply
|
||||
Whenever writing code for plugins, visual layers, or modifying components like `EntityRenderer` or `GlobeView`.
|
||||
|
||||
## Critical Limitations
|
||||
|
||||
### `HeightReference.CLAMP_TO_GROUND` Warning
|
||||
> [!WARNING]
|
||||
> Do **not** apply `HeightReference.CLAMP_TO_GROUND` to label text rendering (`LabelGraphics`). Due to a known issue in Cesium 1.121+, clamping tens of thousands of dynamic labels blocks the UI thread continuously because Cesium recalculates the terrain intersection each frame.
|
||||
|
||||
### Primitive Restrictions
|
||||
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.
|
||||
|
||||
## Performance Culling
|
||||
|
||||
> [!TIP]
|
||||
> Do not rely solely on depth buffering (`disableDepthTestDistance`) when viewing the backside of the globe. Use CPU-side calculating (dot-product against the Earth's radius) to implement manual horizon culling. Render nothing if the scalar projection is behind the tangential threshold.
|
||||
|
||||
## LOD & Stacking
|
||||
1. Convert distant entities to `billboard` representations.
|
||||
2. If closely grouped, the `StackManager` should spiderify components circularly. Non-hub objects fade to 0.4 opacity when expanded to reduce visual clutter.
|
||||
3. Use the `useModelRendering` hook exclusively for transitioning high-importance entities (like aircraft or ships) into full 3D GLTF models on approach.
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
trigger: always_on
|
||||
---
|
||||
|
||||
# Context and Memory Synchronization
|
||||
|
||||
## 1. Purpose
|
||||
This specification ensures that any agent maintains persistent, accurate project context by pointing them directly to the Single Source of Truth for this repository.
|
||||
|
||||
## 2. Synchronization Target
|
||||
The agent MUST orient itself by immediately reading:
|
||||
1. `c:\dev\worldwideview\AGENTS.md` (The root index of all technical stack details)
|
||||
2. `c:\dev\worldwideview\.agents\context\01-platform-overview.md` (The high-level platform goals)
|
||||
|
||||
If deep technical rules are required for a specific domain (e.g., UI state, Map Rendering, Monorepo management), the agent MUST consult the relevant file in `c:\dev\worldwideview\.agents\rules\`.
|
||||
|
||||
## 3. Reflecting Changes
|
||||
If the architecture fundamentally changes (e.g., migrating off Zustand, or removing Cesium), the agent MUST proactively update the `AGENTS.md` and relevant files in `.agents/rules/` to reflect this new reality.
|
||||
|
||||
## 4. Goal
|
||||
A new chat instance MUST be able to reconstruct an accurate, comprehensive understanding of the project solely from reading the root `AGENTS.md` file and branching out to the specific rules as necessary. This prevents context bloat and ensures accuracy.
|
||||
@@ -4,8 +4,8 @@
|
||||
When making database schema changes, you must ensure that generated migrations are resilient against environmental discrepancies.
|
||||
|
||||
- **Review Generated SQL**: Always review the `.sql` files generated by `npx prisma migrate dev`.
|
||||
- **Add "IF EXISTS" clauses**: SQLite and Prisma can sometimes produce brittle drop statements (`DROP INDEX "my_index"`). To prevent migrations from crashing if a state desynchronization occurs (e.g., the index was already dropped or never created), manually edit the migration file to use `DROP INDEX IF EXISTS "my_index";` or `DROP TABLE IF EXISTS "table_name";`.
|
||||
- **Data Preservation**: When dropping columns or renaming, SQLite does not cleanly support it and requires table recreation. Carefully review the `INSERT INTO "new_table" SELECT ...` clauses to ensure data is correctly mapped.
|
||||
- **Add "IF EXISTS" clauses**: Prisma can sometimes produce brittle drop statements (`DROP INDEX "my_index"`). To prevent migrations from crashing if a state desynchronization occurs, manually edit the migration file to use `DROP INDEX IF EXISTS "my_index";` or `DROP TABLE IF EXISTS "table_name";`.
|
||||
- **Data Preservation**: When dropping columns or renaming, carefully review the migration to ensure data is correctly mapped. In PostgreSQL, ensure that cascaded drops don't accidentally remove required data.
|
||||
|
||||
## 2. Managing Failed Migrations
|
||||
If a migration fails in production:
|
||||
@@ -13,4 +13,4 @@ If a migration fails in production:
|
||||
- If you use `resolve --applied`, Prisma will permanently skip that migration in the future, leaving your database structurally out of sync with your Prisma Client.
|
||||
|
||||
## 3. Backups Before DDL
|
||||
Never perform direct DDL operations (ALTER, DROP, CREATE) on a production database (via Prisma or direct SQLite access) without first confirming an automated backup exists, or manually taking a backup of the `wwv.db` file.
|
||||
Never perform direct DDL operations (ALTER, DROP, CREATE) on a production database without first confirming an automated backup exists, or manually taking a `pg_dump` backup of the database.
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: Strict rules for operating within the pnpm monorepo workspace environment structure across frontend and backend services.
|
||||
globs: ""
|
||||
---
|
||||
|
||||
# Monorepo Workflow Guidelines
|
||||
|
||||
## Purpose
|
||||
Strict rules for operating within the `pnpm` monorepo workspace environment structure across frontend and backend services.
|
||||
|
||||
## Directory Isolation
|
||||
|
||||
- The Next.js frontend is located at root `.`.
|
||||
- Individual standalone plugins are located at `packages/wwv-plugin-[name]`.
|
||||
- For heavy plugin processing, microservice backends are located at `packages/wwv-plugin-[name]/backend`.
|
||||
|
||||
## Critical Workspace Rule
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Because plugins use internal workspace references, you MUST strictly use `"workspace:*"` instead of `"*"` in `package.json` dependencies (e.g. `"@worldwideview/wwv-plugin-sdk": "workspace:*"`). Using `"*"` can cause pnpm to eagerly resolve cached registry versions instead of strictly linking your local code, resulting in opaque TypeScript and compilation errors.
|
||||
> **Whenever you add a new plugin package or adjust the SDK, you MUST run `pnpm install` then `pnpm build` from the project ROOT directory to propagate TS types properly.**
|
||||
|
||||
## Start/Exec Flow
|
||||
|
||||
Running `pnpm start:backends` from the project root employs `concurrently` to spin up Fastify services attached to specific plugins containing `/backend` folders.
|
||||
|
||||
## Next.js Monorepo Exceptions
|
||||
|
||||
When modifying `next.config.ts`, if new UI components or plugins are added that require SSR/transpilation, ensure they are appended to the `transpilePackages: []` array, or they will throw Next-Router unresolved import errors on production build.
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
trigger: model_decision
|
||||
description: The standard operating procedure for instantiating, modifying, and registering a new data source plugin within the engine.
|
||||
---
|
||||
|
||||
# Plugin Architecture & Data Flow
|
||||
|
||||
## Purpose
|
||||
The standard operating procedure for instantiating, modifying, and registering a new data source plugin within the engine.
|
||||
|
||||
## The WorldPlugin Contract
|
||||
|
||||
All data ingest flows through `WorldPlugin` (defined entirely within `@worldwideview/wwv-plugin-sdk`).
|
||||
A valid plugin class MUST provide:
|
||||
1. `id` and `version` (The `version` MUST be dynamically imported via `import pkg from "../package.json"` to prevent duplicate tracking during CI/releases for built-in plugins).
|
||||
2. `fetch(timeRange)` method logic.
|
||||
3. `renderEntity(GeoEntity)` to determine visual style.
|
||||
4. `getPollingInterval()` (defaults fallback securely to standard store config).
|
||||
|
||||
## Plugin Architectures (Manifest Formats)
|
||||
|
||||
Plugins are defined via `PluginManifest` and operate on an **All-Bundle** architecture.
|
||||
All frontend extensions must eventually be compiled into a JS bundle that exports a `WorldPlugin`.
|
||||
|
||||
1. **`bundle` (Dynamic CDN Loaded / Internal)**: Plugins dynamically imported at runtime via ES module references (e.g., `unpkg.com` or local `/plugins/myplugin/frontend.mjs`). Handled by `loadPluginFromManifest` referencing `manifest.entry`.
|
||||
2. **`static` (Legacy)**: Now compiled via `wwvStaticCompiler` into a dynamic bundle. The raw `StaticDataPlugin` runtime class has been removed.
|
||||
3. **`declarative` (Legacy)**: Now compiled or wrapped into bundles.
|
||||
|
||||
No matter the source, the engine evaluates it by directly loading the `entry` file dynamically:
|
||||
`const module = await import(/* webpackIgnore: true */ entry);`
|
||||
|
||||
## Package Metadata (`package.json`)
|
||||
|
||||
All plugins MUST define their identity and compatibility via a `"worldwideview"` block in their `package.json`. This acts as the source-of-truth for generating the `PluginManifest` for the registry. If a plugin does not define `"type"`, validation functions will reject the manifest entirely or rely on legacy fallbacks.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@worldwideview/wwv-plugin-myplugin",
|
||||
"version": "1.0.0",
|
||||
"worldwideview": {
|
||||
"id": "myplugin", // REQUIRED: Must match the directory name & API routes.
|
||||
"type": "data-layer", // REQUIRED: "data-layer" or "extension"
|
||||
"format": "bundle", // REQUIRED: "bundle", "declarative", or "static"
|
||||
"category": "Aviation", // REQUIRED: Matches PluginCategory union in SDK
|
||||
"icon": "Plane", // RECOMMENDED: Lucide icon name
|
||||
"capabilities": [ // REQUIRED: What the plugin can do
|
||||
"data:own", // (e.g. injects its own data)
|
||||
"globe:overlay", // (e.g. renders 3D elements)
|
||||
"network:fetch"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## The Registration Pipeline
|
||||
|
||||
> [!NOTE]
|
||||
> All plugin interactions run through three singleton services:
|
||||
> `PluginRegistry` / `InstalledPluginsLoader` -> `PluginManager` -> `PollingManager` -> `DataBus`
|
||||
|
||||
### `InstalledPluginsLoader`
|
||||
Scans the PostgreSQL database at startup for dynamically installed marketplace manifests. Parses, validates (`validateManifest`), and registers valid plugins via `pluginManager.loadFromManifest`.
|
||||
|
||||
### `PluginManager`
|
||||
The orchestrator. Exposes `registerPlugin`, `enablePlugin`, `disablePlugin`. Never bypass the manager to push data manually to the cache. Supports dynamic loading via `loadFromManifest`.
|
||||
|
||||
### `PollingManager`
|
||||
Coordinates interval execution. Implements **exponential backoff**. When a plugin errors, it retries at increasing scales (e.g., 2s → 4s → 8s) automatically.
|
||||
|
||||
### `DataBus`
|
||||
The typed generic event bus separating React UI components from background execution.
|
||||
|
||||
```typescript
|
||||
// How data gets pushed onto the rendering surface securely:
|
||||
DataBus.getInstance().emit('dataUpdated', {
|
||||
pluginId: "mytracker",
|
||||
entities: newEntities
|
||||
});
|
||||
```
|
||||
|
||||
## When to Apply
|
||||
When writing `fetch` implementations for plugins, or tracing why an entity dropped off the map. Ensure missing data correctly triggers the cache fallback via the DataBus. Ensure all new external plugins use the `bundle` format and exist in the marketplace registry to avoid CDN 404 hydrating crashes.
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
trigger: glob
|
||||
description: Guidelines on managing the single source of truth across WorldWideView using Zustand, avoiding prop-drilling, and isolating UI rerenders.
|
||||
globs: "src/core/state/**/*, src/components/**/*"
|
||||
---
|
||||
|
||||
# Zustand State Management
|
||||
|
||||
## Purpose
|
||||
Guidelines on managing the single source of truth across WorldWideView using Zustand, avoiding prop-drilling, and isolating UI rerenders.
|
||||
|
||||
## Single Centralized State
|
||||
WorldWideView utilizes a monolithic Zustand store located at `src/core/state/store.ts`. It is broken down into exactly 9 semantic slices.
|
||||
|
||||
| Slice Name | Purpose | Example State |
|
||||
|---|---|---|
|
||||
| **Globe** | Cesium Viewer state | `cameraPosition`, `selectedEntity` |
|
||||
| **Layers** | Loaded map tiles/overlays | `activeTileSets` |
|
||||
| **Timeline** | Application current time | `currentTimeRange` |
|
||||
| **UI** | Global overlay states | `isFilterMenuOpen` |
|
||||
| **Filters** | Active visual filtration | `searchQuery`, `categoryFilter` |
|
||||
| **Data** | Entity registry | `entitiesByPlugin` |
|
||||
| **Config** | User preferences | `pollingIntervals`, `pluginSettings` |
|
||||
| **Favorites**| Pinned entities | `favoriteIds` |
|
||||
| **GeoJSON** | Local files loaded in | `localImports` |
|
||||
|
||||
## When to Apply
|
||||
When passing deep state across components, or when a plugin must push state configurations onto the screen.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Avoid Prop Drilling
|
||||
**Never** pass props further than two levels down. If a component deeper in the tree needs access to something (e.g., `cameraPosition`), it must `useStore(s => s.globe.cameraPosition)`.
|
||||
|
||||
### Selector Destructuring Avoidance
|
||||
> [!WARNING]
|
||||
> Do not destructure wide objects in selectors.
|
||||
> Right: `const isHUD = useStore(state => state.ui.hudVisible);`
|
||||
> Wrong: `const { hudVisible } = useStore(state => state.ui);`
|
||||
> The wrong approach rerenders the component any time *anything* in the `ui` slice changes.
|
||||
|
||||
### Config and Plugins
|
||||
If your plugin has user-configurable values (e.g., color settings, toggle states), its data MUST live inside `state.config.dataConfig.pluginSettings[pluginId]`. Do not spawn un-bound `useState` hooks for UI properties if they affect the global app state.
|
||||
@@ -1,4 +1,13 @@
|
||||
DATABASE_URL=file:./data/wwv.db
|
||||
# PostgreSQL connection string.
|
||||
# For local dev: The platform will automatically spin up PostgreSQL via Docker Compose.
|
||||
# Set DATABASE_URL to: postgresql://postgres:postgres@localhost:5432/worldwideview?schema=public
|
||||
#
|
||||
# For cloud/production: Provide your external Postgres connection string (e.g. Supabase)
|
||||
# and set WWV_SKIP_LOCAL_DB=true to prevent Docker from spinning up a local database instance.
|
||||
# DATABASE_URL=postgresql://postgres:postgres@localhost:5432/worldwideview?schema=public
|
||||
|
||||
# Set this to true in production to prevent docker-compose or pnpm run dev from starting the local database.
|
||||
# WWV_SKIP_LOCAL_DB=false
|
||||
|
||||
# Default plugins enabled on boot for demo edition
|
||||
# Comma-separated list of plugin IDs
|
||||
|
||||
+2
-2
@@ -4,8 +4,8 @@
|
||||
# This file is tracked by git. Only put non-secret values here.
|
||||
# Prisma reads DATABASE_URL from this file.
|
||||
|
||||
# Database (SQLite for local — zero config; PostgreSQL for cloud)
|
||||
DATABASE_URL=file:./data/wwv.db
|
||||
# Database (PostgreSQL)
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/worldwideview
|
||||
|
||||
# ============================================================
|
||||
# .env.local — NOT committed (secrets & API keys)
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
version: 2
|
||||
updates:
|
||||
# 1. Maintain Node.js / pnpm dependencies
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
# Group all minor/patch updates into a single PR so it doesn't spam you
|
||||
groups:
|
||||
dependencies:
|
||||
patterns:
|
||||
- "*"
|
||||
update-types:
|
||||
- "minor"
|
||||
- "patch"
|
||||
|
||||
# 2. Maintain Docker base images
|
||||
- package-ecosystem: "docker"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
|
||||
# 3. Maintain GitHub Actions workflows
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "monthly" # Actions update less frequently, monthly is fine
|
||||
+10
-16
@@ -9,11 +9,9 @@ jobs:
|
||||
name: Type Check
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: pnpm/action-setup@v4
|
||||
with:
|
||||
version: 9
|
||||
- uses: actions/setup-node@v4
|
||||
- uses: actions/checkout@v6
|
||||
- uses: pnpm/action-setup@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
@@ -25,11 +23,9 @@ jobs:
|
||||
name: Unit Tests
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: pnpm/action-setup@v4
|
||||
with:
|
||||
version: 9
|
||||
- uses: actions/setup-node@v4
|
||||
- uses: actions/checkout@v6
|
||||
- uses: pnpm/action-setup@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
@@ -42,15 +38,13 @@ jobs:
|
||||
runs-on: ubuntu-latest
|
||||
needs: [typecheck, test]
|
||||
env:
|
||||
DATABASE_URL: file:./data/wwv.db
|
||||
DATABASE_URL: postgresql://ci:ci@localhost:5432/ci
|
||||
AUTH_SECRET: ci-placeholder-secret-not-used-in-tests
|
||||
NEXT_PUBLIC_WWV_EDITION: local
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: pnpm/action-setup@v4
|
||||
with:
|
||||
version: 9
|
||||
- uses: actions/setup-node@v4
|
||||
- uses: actions/checkout@v6
|
||||
- uses: pnpm/action-setup@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
|
||||
@@ -27,7 +27,7 @@ jobs:
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
fetch-depth: 1
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ jobs:
|
||||
actions: read # Required for Claude to read CI results on PRs
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
fetch-depth: 1
|
||||
|
||||
|
||||
@@ -20,10 +20,10 @@ jobs:
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
uses: actions/checkout@v6
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
uses: docker/setup-buildx-action@v4
|
||||
|
||||
- name: Log in to the Container registry
|
||||
uses: docker/login-action@v3
|
||||
@@ -34,7 +34,7 @@ jobs:
|
||||
|
||||
- name: Extract metadata (tags, labels) for Docker
|
||||
id: meta
|
||||
uses: docker/metadata-action@v5
|
||||
uses: docker/metadata-action@v6
|
||||
with:
|
||||
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
|
||||
tags: |
|
||||
|
||||
@@ -12,9 +12,9 @@ jobs:
|
||||
contents: read
|
||||
id-token: write # Required for OIDC trusted publishing (no NPM_TOKEN needed)
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/checkout@v6
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 20
|
||||
registry-url: "https://registry.npmjs.org"
|
||||
|
||||
@@ -87,3 +87,6 @@ packages/*/dist/
|
||||
|
||||
# proprietary extracted services
|
||||
packages/wwv-data-engine/
|
||||
|
||||
# IDE workspace files
|
||||
*.code-workspace
|
||||
@@ -19,7 +19,7 @@ Our primary design, feature-set, and operational layout goal is to mimic the str
|
||||
| State | Zustand (slice-based: globe, layers, timeline, UI, filters, data, config, favorites, geojson) |
|
||||
| Event Bus | Custom typed `DataBus` (pub/sub singleton) |
|
||||
| Styling | Vanilla CSS — **no Tailwind** |
|
||||
| Database | SQLite via Prisma (local), PostgreSQL (cloud) |
|
||||
| Database | PostgreSQL via Prisma 7 (local and cloud) |
|
||||
| Auth | NextAuth v5 beta (Credentials provider, JWT sessions) |
|
||||
| Package Manager | pnpm (monorepo with `pnpm-workspace.yaml`) |
|
||||
| Testing | Vitest + jsdom + React Testing Library |
|
||||
@@ -77,7 +77,7 @@ worldwideview/
|
||||
├── prisma/ # schema.prisma, migrations/
|
||||
├── public/ # Static assets, Cesium workers, plugin GeoJSON data
|
||||
├── scripts/ # Build scripts (copy-cesium, scaffold-osm-plugin, setup)
|
||||
├── data/ # SQLite database (gitignored, Docker volume)
|
||||
├── data/ # PostgreSQL data volume (gitignored)
|
||||
├── Dockerfile # Multi-stage production build
|
||||
├── docker-compose.yml # Main app + microservice backends
|
||||
└── .agents/ # Agent documentation, rules, skills, workflows
|
||||
@@ -102,7 +102,7 @@ Visibility Toggle → DataBusSubscriber subscribes to layer via WsClient
|
||||
```
|
||||
|
||||
Four plugin architectures exist (All-Bundle Model):
|
||||
1. **Data Engine Seeder** — Standalone Fastify container with SQLite microservice or unified seeders (e.g., `iranwarlive-backend`).
|
||||
1. **Data Engine Seeder** — Standalone Fastify container with PostgreSQL microservice or unified seeders (e.g., `iranwarlive-backend`).
|
||||
2. **Dynamic CDN Loaded (Bundle)** — Externally developed plugins dynamically imported at runtime via ES module CDNs (e.g., `unpkg.com` version-pinned URLs).
|
||||
3. **Static Compiled (Bundle)** — Static GeoJSON data wrapped into JS bundles via `wwvStaticCompiler` during build/sync (previously `StaticDataPlugin`).
|
||||
4. **Active Proxied (Bundle)** — Next.js API routes bundled to provide frontend interactions (previously `DeclarativePlugin`).
|
||||
@@ -213,6 +213,7 @@ Built-in plugins are instantiated in `AppShell.tsx` and registered via `PluginRe
|
||||
> - **MUST**: You MUST update Semantic Versioning numbering inside the relevant `package.json` file prior to executing any code commits, adhering strictly to the `[/commit]` workflow rules (`feat:` -> Minor, `fix/refactor/perf:` -> Patch).
|
||||
> - **MUST Detail Commit Levels & Bumps**: On description changes or release notes, you must detail the level of commit (Major/Minor/Fix) for *each* individual change. If there are multiple accumulated changes, you MUST EITHER commit them individually and bump the version each time, OR commit them all at once and bump the version multiple times.
|
||||
> - **MUST Explain Complex Concepts Simply**: Whenever providing a complicated technical explanation to the user, you MUST include a simple explanation below it. Use an analogy with reference to the correct terminology, comparing the concept to something from everyday life to ensure the user easily understands it.
|
||||
> - **MUST Be Transparent & Narrate Actions**: You MUST always be transparent about what you are doing. Narrate your goals, your current step in the process, and exactly what actions you are taking or tools you are executing **before** or **while** you do them, not after they are done. Do not work in silence or lock all your reasoning behind hidden "thought" blocks. Use visible chat messages to bring the user along the journey by describing your plan as it unfolds. **Crucially, keep this narration conversational and natural.** Avoid stiff, robotic templates (e.g., "My Goal: X. My Step: Y."). Just occasionally drop a brief, casual note about what you are checking or doing next so the user isn't left in the dark.
|
||||
|
||||
### 5.8 Workspace Hygiene
|
||||
Whenever agents generate temporary debugging scripts, test REST endpoints via `.mjs`, or dump traces/JSON outputs, they **MUST** save these exclusively inside `/local-scripts/`. The root directory is strictly for production configuration files.
|
||||
@@ -223,7 +224,7 @@ Whenever agents generate temporary debugging scripts, test REST endpoints via `.
|
||||
|
||||
| Variable | Required | Description |
|
||||
|---|---|---|
|
||||
| `DATABASE_URL` | Yes | SQLite: `file:./data/wwv.db` |
|
||||
| `DATABASE_URL` | Yes | PostgreSQL connection string |
|
||||
| `AUTH_SECRET` | Yes | JWT signing secret (generate with `openssl rand -hex 32`) |
|
||||
| `NEXT_PUBLIC_CESIUM_ION_TOKEN` | No | Cesium Ion access token |
|
||||
| `NEXT_PUBLIC_BING_MAPS_KEY` | No | Bing Maps imagery |
|
||||
@@ -244,14 +245,14 @@ Secrets go in `.env.local` (gitignored). Non-secrets go in `.env` (committed).
|
||||
```bash
|
||||
pnpm install # Install all workspace dependencies
|
||||
pnpm run setup # Generate .env.local with AUTH_SECRET (first-time setup)
|
||||
pnpm dev # Next.js frontend only (auto-runs prisma migrate deploy + copy-cesium)
|
||||
pnpm dev # Next.js frontend only (auto-runs prisma db push + copy-cesium)
|
||||
pnpm dev:all # Frontend + wwv-data-engine concurrently (normal development)
|
||||
pnpm dev:backends # Run only the data engine in dev mode
|
||||
pnpm build # Production build
|
||||
pnpm test # Run all Vitest tests (scoped to src/lib, src/core, src/plugins)
|
||||
pnpm db:reset # Reset and re-migrate the frontend SQLite database (destructive)
|
||||
pnpm db:reset # Reset and re-migrate the frontend database (destructive)
|
||||
pnpm start:backends # Start all plugin microservice backends in parallel
|
||||
pnpm clean:backends # Wipe all plugin SQLite databases
|
||||
pnpm clean:backends # Wipe all plugin database records
|
||||
pnpm run scaffold-osm-plugin <name> # Generate a new plugin from scaffold
|
||||
```
|
||||
|
||||
@@ -266,8 +267,8 @@ Frontend runs at `http://localhost:3000`.
|
||||
- **Cesium assets**: Copied to `public/cesium/` via `scripts/copy-cesium.mjs` at build time, excluded from output tracing.
|
||||
- **Prisma Configuration**: `prisma.config.ts` must export a native javascript object instead of dynamically importing CLI wrapper binaries (`prisma/config` or `dotenv`). The standalone Next.js tracer strips CLI devDependencies during the build, which will cause fatal runtime container crashes if imported.
|
||||
- **Microservices**: Separate containers defined in `docker-compose.yml`, proxied via `next.config.ts` rewrites.
|
||||
- **Coolify**: Deployed via Dockerfile builder natively mapping environment variables continuously into the container shell. Persistent storage mount required at `/app/data` for the SQLite root node database.
|
||||
- **Docker volumes**: Mount `/app/data` (frontend SQLite), `/app/packages/wwv-data-engine/data` (data engine SQLite), `/data` (Redis)
|
||||
- **Coolify**: Deployed via Dockerfile builder natively mapping environment variables continuously into the container shell.
|
||||
- **Docker volumes**: Ensure PostgreSQL data and Redis volumes are mounted for persistence.
|
||||
|
||||
---
|
||||
|
||||
@@ -314,7 +315,7 @@ Read the relevant rule file when working in that domain:
|
||||
| `plugin-architecture` | Creating/modifying plugins, lifecycle, registration | `.agents/rules/plugin-architecture.md` |
|
||||
| `cesium-rendering` | Globe rendering, entity types, primitives, LOD, culling | `.agents/rules/cesium-rendering.md` |
|
||||
| `state-management` | Zustand slices, store access, plugin settings | `.agents/rules/state-management.md` |
|
||||
| `database-migrations` | Prisma schema changes, migrations, SQLite/Postgres | `.agents/rules/database-migrations.md` |
|
||||
| `database-migrations` | Prisma schema changes, migrations, PostgreSQL | `.agents/rules/database-migrations.md` |
|
||||
| `continuous-improvement` | When to create/update rules, skills, or workflows | `.agents/rules/continuous-improvement.md` |
|
||||
| `context-and-memory` | How to orient and maintain project context between sessions | `.agents/rules/context-and-memory.md` |
|
||||
|
||||
@@ -361,3 +362,21 @@ Refer to these skill documents for specialized tasks:
|
||||
### Global Skills
|
||||
|
||||
52 skills are available across all projects. See `.agents/global-skills-index.md` for the full list and invocation paths.
|
||||
|
||||
---
|
||||
|
||||
## 15. Pull Request & Commit Guidelines
|
||||
|
||||
- **Commit Format**: We strictly enforce Conventional Commits (`feat:`, `fix:`, `refactor:`, `perf:`).
|
||||
- **Workflow**: You **MUST** use the `/commit` workflow before every git commit to ensure proper semantic versioning bumps.
|
||||
- **Required Checks**: Ensure `pnpm test` and `pnpm build` complete successfully before proposing a merge.
|
||||
- **Review Process**: Use `/pr-review` to conduct a comprehensive multi-role review on any pull request.
|
||||
|
||||
---
|
||||
|
||||
## 16. Debugging and Troubleshooting
|
||||
|
||||
- **Prisma & PostgreSQL Sync Issues**: If the local database state falls out of sync with Prisma schema, do not manually drop tables. Instead, run `pnpm db:reset` to cleanly wipe and re-apply all migrations.
|
||||
- **Cesium Entity Clipping**: If `billboard` entities are clipping or failing to render correctly, verify that you are not mixing `point` primitive properties (like `size` or `outlineWidth`) into the `billboard` options.
|
||||
- **Build Exhaustion (Docker)**: Multi-stage pnpm builds generate massive cache layers. If a Coolify deployment fails silently or PostgreSQL crashes abruptly, check host disk space and run `docker builder prune -a -f`.
|
||||
- **Next.js Typechecking Failures**: If backend-only `scripts/` fail during Next.js build, verify that the scripts directory is properly listed in the `exclude` array of `tsconfig.json`.
|
||||
+27
-15
@@ -6,47 +6,56 @@ RUN find . -type f \! -name 'package.json' \! -name 'pnpm-workspace.yaml' \! -na
|
||||
find . -type d -empty -delete
|
||||
|
||||
# Stage 1: Install ALL dependencies (needed for build)
|
||||
FROM node:22-alpine AS deps
|
||||
RUN corepack enable pnpm
|
||||
RUN apk add --no-cache python3 make g++
|
||||
FROM node:26-alpine AS deps
|
||||
RUN npm install -g [email protected]
|
||||
|
||||
WORKDIR /app
|
||||
# Copy only the extracted package.jsons
|
||||
COPY --from=extractor /app ./
|
||||
# Install dependencies with cache mount for pnpm store
|
||||
RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store pnpm install --frozen-lockfile
|
||||
RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store pnpm install
|
||||
|
||||
|
||||
# Stage 3: Build the application
|
||||
FROM deps AS builder
|
||||
# Copy full source code
|
||||
COPY . .
|
||||
RUN DATABASE_URL="file:./data/wwv.db" npx prisma generate
|
||||
|
||||
# Create an empty SQLite database with all tables applied
|
||||
RUN mkdir -p ./data && DATABASE_URL=file:./data/wwv.db npx prisma migrate deploy
|
||||
|
||||
# Next.js inlines NEXT_PUBLIC_* vars at build time — must be declared as ARGs
|
||||
ARG NEXT_PUBLIC_CESIUM_ION_TOKEN
|
||||
ARG NEXT_PUBLIC_GOOGLE_MAPS_API_KEY
|
||||
ARG NEXT_PUBLIC_BING_MAPS_KEY
|
||||
ARG NEXT_PUBLIC_WWV_EDITION
|
||||
ARG NEXT_PUBLIC_WS_ENGINE_URL
|
||||
ARG NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL
|
||||
ARG NEXT_PUBLIC_ADSENSE_CLIENT_ID
|
||||
ARG NEXT_PUBLIC_SUPABASE_URL
|
||||
ARG NEXT_PUBLIC_SUPABASE_ANON_KEY
|
||||
|
||||
# Run our pregenerate schema swap script and then generate Prisma client
|
||||
RUN NEXT_PUBLIC_WWV_EDITION=$NEXT_PUBLIC_WWV_EDITION pnpm run generate
|
||||
|
||||
# Database migrations run at container startup via docker-entrypoint.sh
|
||||
# DATABASE_URL must be set to a PostgreSQL connection string
|
||||
|
||||
# Run Next.js build with Webpack cache mounted
|
||||
RUN --mount=type=cache,target=/app/.next/cache NODE_OPTIONS="--max_old_space_size=3072" pnpm run build
|
||||
RUN node scripts/copy-cesium.mjs
|
||||
|
||||
# Deploy flattened production dependencies
|
||||
RUN pnpm --filter worldwideview deploy --prod /app/prod
|
||||
|
||||
# Stage 4: Production runner
|
||||
FROM node:22-alpine AS runner
|
||||
FROM node:26-alpine AS runner
|
||||
WORKDIR /app
|
||||
|
||||
RUN apk add --no-cache openssl
|
||||
RUN npm install -g [email protected]
|
||||
|
||||
ENV NODE_ENV=production
|
||||
ENV HOSTNAME=0.0.0.0
|
||||
ENV PORT=3000
|
||||
ENV DATABASE_URL=file:./data/wwv.db
|
||||
# DATABASE_URL must be provided via environment variable (no default)
|
||||
# Example: postgresql://user:pass@host:5432/dbname
|
||||
ENV AUTH_TRUST_HOST=true
|
||||
|
||||
# Copy Prisma schema + migrations for runtime DB init
|
||||
@@ -59,20 +68,23 @@ COPY --from=builder /app/src/generated ./src/generated
|
||||
# Copy standalone server output
|
||||
COPY --from=builder /app/.next/standalone ./
|
||||
|
||||
# Copy deployed production node_modules
|
||||
COPY --from=builder /app/prod/node_modules ./node_modules
|
||||
|
||||
# We no longer copy proddeps/node_modules. Next.js standalone output
|
||||
# already traces and copies all the exact node_modules needed for production.
|
||||
|
||||
# Copy static assets that standalone mode does NOT include
|
||||
COPY --from=builder /app/.next/static ./.next/static
|
||||
COPY --from=builder /app/public ./public
|
||||
COPY --from=builder /app/scripts/https-proxy.mjs ./scripts/https-proxy.mjs
|
||||
COPY --from=builder /app/scripts/migrate-legacy.mjs ./scripts/migrate-legacy.mjs
|
||||
|
||||
# Entrypoint: migrate DB on first run, then start server
|
||||
COPY docker-entrypoint.sh ./docker-entrypoint.sh
|
||||
RUN sed -i 's/\r$//' ./docker-entrypoint.sh
|
||||
RUN chmod +x ./docker-entrypoint.sh
|
||||
|
||||
# Declare /app/data as a persistent volume mount point.
|
||||
VOLUME ["/app/data"]
|
||||
|
||||
EXPOSE 3000
|
||||
EXPOSE 3000 3001
|
||||
|
||||
ENTRYPOINT ["./docker-entrypoint.sh"]
|
||||
Binary file not shown.
@@ -1,54 +1,87 @@
|
||||
<div align="center">
|
||||
|
||||
<!-- Generated: 2026-04-19 02:20:00 UTC -->
|
||||
# WorldWideView 🌍
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# WorldWideView
|
||||
|
||||
**The Open-Source, Plugin-Driven Geospatial Intelligence Engine**
|
||||
|
||||
[](LICENSE)
|
||||
[](CONTRIBUTING.md)
|
||||
|
||||
*A modular situational awareness platform designed to ingest live data streams and render them as interactive, cinematic layers on a high-fidelity CesiumJS 3D globe.*
|
||||
|
||||
<!-- 📸 Replace with a high-res GIF or screenshot of the platform running with multiple layers enabled -->
|
||||
[](https://github.com/silvertakana/worldwideview/actions/workflows/ci.yml)
|
||||
[](https://codecov.io/gh/silvertakana/worldwideview)
|
||||
[](https://www.npmjs.com/package/@worldwideview/wwv-plugin-sdk)
|
||||
[](https://github.com/silvertakana/worldwideview/releases)
|
||||
[](https://github.com/silvertakana/worldwideview/graphs/contributors)
|
||||
<br>
|
||||
[](https://nextjs.org/)
|
||||
[](https://cesium.com/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](https://www.docker.com/)
|
||||
[](LICENSE)
|
||||
[](#)
|
||||
[](https://makeapullrequest.com)
|
||||
|
||||

|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
WorldWideView is a real-time geospatial engine visualizing live global data on an interactive 3D globe. Utilizing a dynamic "All-Bundle" plugin architecture, independent data sources—like live aircraft, satellites, or OSINT news clusters—are ingested and rendered decoupled from the core 3D viewer.
|
||||
WorldWideView is a real-time geospatial engine visualizing live global data on an interactive 3D globe. Utilizing a dynamic "All-Bundle" plugin architecture, independent data sources—like live aircraft, maritime vessels, or conflict events—are ingested and rendered decoupled from the core 3D viewer.
|
||||
|
||||
---
|
||||
## Key Features
|
||||
|
||||
## 🛠 Prerequisites
|
||||
- **"All-Bundle" Plugin Architecture**: Ingest any data source dynamically without touching the core platform.
|
||||
- **High-Fidelity 3D Rendering**: Google Photorealistic 3D Tiles and LOD modeling powered by CesiumJS.
|
||||
- **Real-Time Data Pipeline**: High-frequency WebSocket updates managed by a custom `DataBus`.
|
||||
- **Advanced Entity Management**: Automatic horizon culling, chunked primitive rendering, and 3D stacking/spiderification.
|
||||
- **Marketplace Integration**: Download and sync new plugins directly from the UI.
|
||||
|
||||
Before starting, ensure you have the required tools installed based on how you want to use WorldWideView:
|
||||
- **For Self-Hosting:** You only need Docker.
|
||||
- **For Local Development/Contributing:** You need Node.js and `pnpm`.
|
||||
## Core Technologies
|
||||
|
||||
### Installing Docker (For Self-Hosting)
|
||||
- **Windows / Mac:** Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop/). *(Windows users: Ensure WSL 2 integration is enabled in Settings > Resources > WSL Integration).*
|
||||
- **Linux (Ubuntu/Debian):**
|
||||
```bash
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
```
|
||||
- **Frontend:** Next.js 16 (App Router), React 19, TypeScript 5
|
||||
- **3D Engine:** CesiumJS + Resium (Google Photorealistic 3D Tiles)
|
||||
- **State Management:** Zustand
|
||||
- **Event Bus:** Custom typed `DataBus` for high-frequency WebSocket updates
|
||||
- **Database:** PostgreSQL via Prisma 7
|
||||
- **Deployment:** Docker multi-stage build, Coolify
|
||||
|
||||
### Installing pnpm (For Developers)
|
||||
If you want to contribute to the code, you'll need the `pnpm` package manager:
|
||||
- **Windows (PowerShell):** `iwr https://get.pnpm.io/install.ps1 -useb | iex`
|
||||
- **Mac / Linux:** `curl -fsSL https://get.pnpm.io/install.sh | sh -`
|
||||
- **Or via npm:** `npm install -g pnpm`
|
||||
## Project Architecture
|
||||
|
||||
---
|
||||
WorldWideView separates the data acquisition layer from the frontend rendering loop, using a real-time event bus to bridge them.
|
||||
|
||||
## 🐋 Self-Hosting & Production Deployment (Docker)
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph Data Sources
|
||||
A[Public APIs] -->|Poll| B[Data Engine Seeders]
|
||||
C[Microservices] -->|Stream| B
|
||||
end
|
||||
|
||||
WorldWideView uses a multi-stage Dockerfile designed for standalone output, natively supporting deployment via Coolify or standard Docker Compose.
|
||||
subgraph Frontend Pipeline
|
||||
B -->|WebSocket /stream| D[DataBus & WsClient]
|
||||
D -->|Hydrate| E[Zustand Store]
|
||||
E -->|Memoized Entities| F[Entity Renderer]
|
||||
F -->|Primitives| G[CesiumJS Globe]
|
||||
end
|
||||
|
||||
### Instant Self-Hosting (Recommended)
|
||||
Get the platform running on your own server instantly using our automated Docker Compose deployment scripts:
|
||||
subgraph Plugins
|
||||
H[Plugin Registry] -->|Load| I[Dynamic Import CDNs]
|
||||
end
|
||||
|
||||
H -.-> D
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before running the application, ensure you have the following installed:
|
||||
- [Node.js](https://nodejs.org/) (v18+)
|
||||
- [pnpm](https://pnpm.io/) (v9+)
|
||||
- [Docker](https://www.docker.com/) (for self-hosting or full local dev)
|
||||
- PostgreSQL (or rely on the `coolify-db` / local compose container)
|
||||
|
||||
## Quick Start (Self-Hosting)
|
||||
|
||||
WorldWideView uses a multi-stage Dockerfile designed for standalone output. To deploy instantly on your own server:
|
||||
|
||||
**Mac/Linux:**
|
||||
```bash
|
||||
@@ -62,158 +95,84 @@ mkdir worldwideview; cd worldwideview
|
||||
Invoke-WebRequest -Uri https://raw.githubusercontent.com/silvertakana/worldwideview/main/setup.ps1 -UseBasicParsing | Invoke-Expression
|
||||
```
|
||||
|
||||
### Manual Docker Deployment
|
||||
If you prefer to deploy manually:
|
||||
```bash
|
||||
# Start the core app, Redis cache, and Data Engine microservice in production mode
|
||||
docker compose up -d
|
||||
```
|
||||
> [!NOTE]
|
||||
> Ensure you connect a PostgreSQL database via the `DATABASE_URL` environment variable for production deployments.
|
||||
|
||||
**Persistent Storage Requirements:**
|
||||
When deploying to production, ensure you mount the following volumes to prevent data loss:
|
||||
- Mount `/app/data` to persist the core SQLite database.
|
||||
- Mount `/app/packages/wwv-data-engine/data` to persist the custom plugin microservices SQLite layer.
|
||||
- Mount `/data` to persist the standalone Redis container.
|
||||
## Quick Start (Local Development)
|
||||
|
||||
---
|
||||
To run the source code locally for contributing or developing:
|
||||
|
||||
## 🚀 Installation & Setup (Local Development)
|
||||
|
||||
Get the source code running locally for contributing or modifying the core platform.
|
||||
|
||||
### Quick Start Scripts
|
||||
**Mac/Linux:**
|
||||
```bash
|
||||
git clone https://github.com/silvertakana/worldwideview.git
|
||||
cd worldwideview
|
||||
bash local-dev.sh
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
git clone https://github.com/silvertakana/worldwideview.git
|
||||
cd worldwideview
|
||||
.\local-dev.ps1
|
||||
```
|
||||
|
||||
### Manual Setup
|
||||
```bash
|
||||
git clone https://github.com/silvertakana/worldwideview.git
|
||||
cd worldwideview
|
||||
pnpm install
|
||||
pnpm run setup # generates .env.local with AUTH_SECRET
|
||||
pnpm run dev:all # boots the UI, cache layers, and the marketplace engine
|
||||
pnpm run dev:all # boots the UI, cache layers, and the data engine
|
||||
```
|
||||
Visit `http://localhost:3000` to see the live globe.
|
||||
|
||||
---
|
||||
## Project Structure
|
||||
|
||||
## ⚡ Plugin Development Quick Start
|
||||
The codebase utilizes a `pnpm` monorepo configuration:
|
||||
|
||||
WorldWideView’s architecture means **everything is a plugin**. The core engine is completely data-agnostic. You can build your own WorldWideView plugins using the officially supported CLI toolchain.
|
||||
|
||||
### 1. Scaffold your plugin
|
||||
The plugin folder is pure code. It contains no Docker boilerplate.
|
||||
```bash
|
||||
npx @worldwideview/create-plugin my-layer
|
||||
cd my-layer
|
||||
npm install
|
||||
```text
|
||||
worldwideview/
|
||||
├── src/ # Core frontend app
|
||||
│ ├── app/ # Next.js App Router (pages, API routes)
|
||||
│ ├── components/ # Shared UI, Globe panels, and 3D layouts
|
||||
│ ├── core/ # DataBus, Polling, PluginManager, Store
|
||||
│ └── plugins/ # Built-in plugins and registry logic
|
||||
├── packages/ # Monorepo packages
|
||||
│ ├── wwv-plugin-sdk/ # SDK interfaces and manifest schemas
|
||||
│ └── wwv-plugin-*/ # Individual plugins & their backends
|
||||
├── prisma/ # Database schemas & migrations
|
||||
└── .agents/ # Agent rules, workflows, and documentation
|
||||
```
|
||||
|
||||
### 2. Sideload the plugin into your platform
|
||||
The CLI acts as a bridge, injecting your compiled plugin directly into your running WorldWideView instance.
|
||||
## Plugin Ecosystem
|
||||
|
||||
**If you are running the platform via Docker:**
|
||||
Ensure your Docker Compose file has a volume mount exposing the plugin directory:
|
||||
`volumes: [ "./my-local-plugins:/app/public/plugins-local" ]`
|
||||
And set the environment variable: `WWV_PLUGIN_DEV=true`
|
||||
WorldWideView operates on an open-core philosophy. The platform itself is data-agnostic; all data sources are dynamically imported as plugins at runtime.
|
||||
|
||||
Then, tell the CLI where that exposed folder is:
|
||||
```bash
|
||||
# Save the path so you only have to type it once
|
||||
npx wwv config set wwv-path /absolute/path/to/my-local-plugins
|
||||
- **[Plugin Quickstart Guide](docs/plugin-quickstart.md)**: Learn how to scaffold and link your first plugin using the `@worldwideview/cli`.
|
||||
- **[Advanced Plugin Guide](docs/plugin-advanced.md)**: Deep dive into microservice data seeders, WebSockets, complex 3D rendering, and Marketplace publishing.
|
||||
|
||||
# Start the dev server and link the plugin!
|
||||
npm run link
|
||||
```
|
||||
## Repository Ecosystem
|
||||
|
||||
**If you cloned the platform repository (`pnpm dev`):**
|
||||
```bash
|
||||
npx wwv config set wwv-path ../worldwideview
|
||||
npm run link
|
||||
```
|
||||
WorldWideView is distributed across several specialized repositories:
|
||||
|
||||
The CLI will start Vite in watch mode. Every time you save a file, it compiles in milliseconds and pushes the update directly into your WorldWideView instance. Refresh your browser to see changes!
|
||||
1. **`worldwideview`** (This Repo): Main frontend, CesiumJS rendering engine, and core plugin framework.
|
||||
2. **`wwv-data-engine`**: Open-source community data backend for polling public APIs.
|
||||
3. **`worldwideview-plugins`**: First-party maintained plugins.
|
||||
4. **`worldwideview-marketplace`**: The web application driving the plugin directory.
|
||||
5. **`worldwideview-web`**: Marketing and landing site.
|
||||
|
||||
### 3. Validate & Publish
|
||||
If you are building a simple, static data layer and don't need local testing:
|
||||
```bash
|
||||
npm run validate
|
||||
npm run build
|
||||
npm publish
|
||||
```
|
||||
## Development & Workflow
|
||||
|
||||
📖 **[Read the Full Plugin Guide](docs/PLUGIN_GUIDE.md)** for a deep dive into hooking up websockets or static datasets.
|
||||
- **Branching & Commits:** We strictly enforce [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `refactor:`). Every commit should utilize our semantic versioning `[/commit]` workflow.
|
||||
- **Coding Standards:** We emphasize vanilla CSS (no Tailwind), strict TypeScript 5, and file modularity (max 150 lines per file).
|
||||
- **Testing:** We use Vitest with `jsdom`. All new core logic should be accompanied by tests, running via `pnpm test`.
|
||||
|
||||
---
|
||||
See [Docs: Development](docs/development.md) and [Docs: Testing](docs/testing.md) for more details.
|
||||
|
||||
## 🧠 Core Architecture & Philosophies
|
||||
## Contributing
|
||||
|
||||
- **Open-Core Data Engine**: The real-time backend data pipeline operates on a public/private split-routing model. Community seeders (like ISS tracking) live in the open-source `wwv-data-engine`, while proprietary sources seamlessly interleave via our internal cloud endpoints.
|
||||
- **Dynamic, Decentralized Plugins**: The plugin ecosystem uses a decentralized architecture fetching ES module CDN bundles (e.g., from unpkg) at runtime. The core engine is a lightweight shell that loads data providers dynamically via the marketplace.
|
||||
- **High-Performance Rendering**: Engineered for scale using raw Cesium primitives to smoothly handle upwards of 100,000+ objects simultaneously without GPU stalls.
|
||||
- **Cinematic Situational Awareness**: Implements horizon culling, smooth camera tracking, orientation-locked billboarding, and stack spiderification for dense locations.
|
||||
We welcome community contributions! Please review our coding standards and PR processes before submitting code. For detailed instructions on local development and setting up your environment, see our [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
---
|
||||
## License
|
||||
|
||||
## 🏛 Repository Ecosystem
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
WorldWideView follows an **Open-Core** philosophy distributed across several independent, specialized repositories:
|
||||
## Documentation Index
|
||||
|
||||
1. **[worldwideview](https://github.com/silvertakana/worldwideview)** *(This Repo)*
|
||||
The main Next.js frontend, CesiumJS rendering engine, and core plugin loading framework.
|
||||
2. **[wwv-data-engine](https://github.com/silvertakana/wwv-data-engine)**
|
||||
The open-source community data backend. It polls public APIs (like ISS tracking or USGS earthquakes) and streams them to the frontend via WebSocket.
|
||||
*(Note: The official production deployment uses a proprietary internal fork of this engine that includes additional restricted seeders like aviation and maritime).*
|
||||
3. **[worldwideview-plugins](https://github.com/silvertakana/worldwideview-plugins)**
|
||||
Our first-party maintained plugins (borders, nuclear sites, military bases, etc.) developed directly by the core team.
|
||||
4. **[worldwideview-marketplace](https://github.com/silvertakana/worldwideview-marketplace)**
|
||||
The web application driving the plugin directory and community submissions.
|
||||
5. **[worldwideview-web](https://github.com/silvertakana/worldwideview-web)**
|
||||
The marketing, documentation, and landing site.
|
||||
Explore our comprehensive documentation suite for detailed engineering insights:
|
||||
|
||||
---
|
||||
|
||||
## 🏗 Development & Code Map
|
||||
|
||||
### Key Entry Points
|
||||
- UI Loader: `src/components/layout/AppShell.tsx`
|
||||
- Dynamic Plugin Ingestion: `src/core/plugins/loadPluginFromManifest.ts`
|
||||
- Global WebSocket Event Loop: `src/core/data/DataBus.ts`
|
||||
- Environment Config: `.env.local` alongside `src/core/edition.ts`
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Index
|
||||
|
||||
- **[Setup & Installation Guide](docs/SETUP.md)**: Detailed environment and local development setup.
|
||||
- **[Architecture (Engineering Depth)](docs/ARCHITECTURE.md)**: Deep dive into the Cesium rendering pipeline, event data bus, and performance optimizations.
|
||||
- **[Contributions Guide](CONTRIBUTING.md)**: How to help out, coding standards, and commit conventions.
|
||||
- **[User Guide](docs/USER_GUIDE.md)**: Application features and navigation tips.
|
||||
|
||||
### Internal Engineering Docs
|
||||
- **[Build System](docs/build-system.md)**: Find compile targets for UI bundles and internal `wwvStaticCompiler` plugin bundling.
|
||||
- **[Testing Overview](docs/testing.md)**: Understanding Vitest strategies and isolated typing execution targets.
|
||||
- **[Development Patterns](docs/development.md)**: View standard hook approaches, Zustand architecture rules, and snippet targets.
|
||||
- **[Deployment Workflows](docs/deployment.md)**: Detailed insights on Next.js standalone execution and persistent database volume arrays.
|
||||
- **[Source File Catalog](docs/files.md)**: High-level mappings of core ingestion controllers to rendering context interfaces.
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing & Community
|
||||
|
||||
We are actively looking for contributors to help build new data plugins and optimize the core 3D engine!
|
||||
- Found a bug or have an idea? Search the [Issue Tracker](https://github.com/silvertakana/worldwideview/issues) and submit a report.
|
||||
- Want to build something? Check out our **[Pinned Plugin Wishlist](https://github.com/silvertakana/worldwideview/issues)** for great first issues!
|
||||
- **[Project Overview](docs/project-overview.md)**: High-level value proposition and technology stack.
|
||||
- **[Architecture](docs/architecture.md)**: DataBus event stream and Zustand state management.
|
||||
- **[Build System](docs/build-system.md)**: Monorepo structure, Next.js standalone output, and Docker builds.
|
||||
- **[Development](docs/development.md)**: Coding conventions and common implementation patterns.
|
||||
- **[Testing](docs/testing.md)**: Vitest setup and coverage targets.
|
||||
- **[Deployment](docs/deployment.md)**: Coolify integration and persistent volumes.
|
||||
- **[Files Catalog](docs/files.md)**: Comprehensive mapping of core source files.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Fair-Use Notice:** This application may contain copyrighted material the use of which has not always been specifically authorized by the copyright owner. Such material is made available for educational purposes, situational awareness, and to advance understanding of global events under "fair use" (Section 107 of the US Copyright Law).
|
||||
+3
-3
@@ -26,11 +26,11 @@ Each stage is **self-contained and demo-able**. Any stage can be shipped indepen
|
||||
---
|
||||
|
||||
## Stage 3: Prisma ORM & Local Database ✅
|
||||
**Demo:** "Run `pnpm run dev` on a fresh clone. SQLite auto-creates. App works with zero config."
|
||||
**Demo:** "Run `pnpm run dev` on a fresh clone with a valid DATABASE_URL. App works seamlessly."
|
||||
|
||||
- [x] Prisma (`prisma` + `@prisma/client`)
|
||||
- [x] Schema: `InstalledPlugin`, `Setting`, `User`, `AviationHistory`, `NpmCache`
|
||||
- [x] SQLite default: `DATABASE_URL=file:./data/wwv.db`
|
||||
- [x] PostgreSQL default: `DATABASE_URL` required
|
||||
- [x] `predev` script: `prisma migrate deploy`
|
||||
- [x] DB auto-creates on first run — zero manual setup
|
||||
|
||||
@@ -142,7 +142,7 @@ Each stage is **self-contained and demo-able**. Any stage can be shipped indepen
|
||||
| **License** | EL2.0 for WorldWideView core; Open Source for marketplace |
|
||||
| **Shared types** | `@worldwideview/plugin-sdk` npm package (MIT) |
|
||||
| **Hosting** | Coolify (ThinkPad T480s). Landing page on Vercel (static export) |
|
||||
| **Database** | Supabase PostgreSQL (cloud), SQLite (local), Prisma ORM |
|
||||
| **Database** | PostgreSQL, Prisma ORM |
|
||||
| **Tenant isolation** | Row-Level Security (RLS) in shared PostgreSQL |
|
||||
| **User settings** | Runtime settings store in DB, not `.env` |
|
||||
| **Bot prevention** | Email verification + Cloudflare Turnstile + rate limiting |
|
||||
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
# Security Policy
|
||||
|
||||
Security is a priority for our project. We appreciate the efforts of security researchers and the open-source community in helping us keep our software secure.
|
||||
|
||||
## Supported Versions
|
||||
|
||||
Security updates are provided for the following versions of the project. We highly recommend all users stay on the latest stable release.
|
||||
|
||||
| Version | Supported | Notes |
|
||||
| ------- | ------------------ | ----- |
|
||||
| 2.x.x | :white_check_mark: | Current main release. Receives all security updates. |
|
||||
| 1.x.x | :x: | Legacy version. No longer receiving updates. |
|
||||
| < 1.0 | :x: | Beta versions are not supported. |
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
**Please do not report security vulnerabilities through public GitHub issues.**
|
||||
|
||||
If you believe you have found a security vulnerability in this project, please report it privately so we have time to fix it before the vulnerability is made public.
|
||||
|
||||
### How to Report
|
||||
|
||||
1. **Email us directly:** Send your report to **[support@worldwideview.dev]**.
|
||||
2. **GitHub Security Advisories:** Alternatively, if this repository has Private Vulnerability Reporting enabled, you can click on the `Security` tab -> `Advisories` -> `Report a vulnerability`.
|
||||
|
||||
### What to Include
|
||||
To help us quickly validate and fix the issue, please include the following in your report:
|
||||
* A description of the vulnerability and its potential impact.
|
||||
* The steps required to reproduce the issue (a proof of concept is highly appreciated).
|
||||
* Any relevant environment details (OS, browser, version).
|
||||
|
||||
### What to Expect
|
||||
* **Acknowledgment:** We will acknowledge receipt of your vulnerability report within **48 hours**.
|
||||
* **Triage & Fix:** We will review the report, determine its severity, and work on a patch. We will keep you updated on our progress.
|
||||
* **Disclosure:** Once the vulnerability is patched and a new version is released, we will publish a security advisory. We are happy to credit you for the discovery if you would like!
|
||||
|
||||
*Note: As an open-source project, we currently do not offer financial bug bounties, but we deeply appreciate your contributions to keeping our users safe.*
|
||||
@@ -0,0 +1,7 @@
|
||||
# This file lists tools managed by Aftman, a cross-platform toolchain manager.
|
||||
# For more information, see https://github.com/LPGhatguy/aftman
|
||||
|
||||
# To add a new tool, add an entry to this table.
|
||||
[tools]
|
||||
rojo = "rojo-rbx/[email protected]"
|
||||
# rojo = "rojo-rbx/[email protected]"
|
||||
BIN
Binary file not shown.
BIN
Binary file not shown.
@@ -0,0 +1,7 @@
|
||||
SUPABASE_PG_URL=postgresql://postgres:[email protected]:5432/postgres
|
||||
SUPABASE_URL=https://xyz.supabase.co
|
||||
SUPABASE_ANON_KEY=eyJ...
|
||||
SUPABASE_SERVICE_ROLE_KEY=eyJ...
|
||||
ACME_EMAIL=[email protected]
|
||||
STRIPE_SECRET_KEY=sk_test_...
|
||||
STRIPE_WEBHOOK_SECRET=whsec_...
|
||||
@@ -0,0 +1,47 @@
|
||||
services:
|
||||
db:
|
||||
image: postgres:15-alpine
|
||||
environment:
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: password
|
||||
POSTGRES_DB: postgres
|
||||
ports:
|
||||
- "5432:5432"
|
||||
|
||||
wwv-cloud:
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: Dockerfile
|
||||
args:
|
||||
- NEXT_PUBLIC_WWV_EDITION=cloud
|
||||
restart: always
|
||||
environment:
|
||||
NEXT_PUBLIC_WWV_EDITION: cloud
|
||||
DATABASE_URL: postgresql://postgres:password@db:5432/postgres
|
||||
NEXT_PUBLIC_SUPABASE_URL: ${SUPABASE_URL:-http://dummy}
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY: ${SUPABASE_ANON_KEY:-dummy}
|
||||
SUPABASE_SERVICE_ROLE_KEY: ${SUPABASE_SERVICE_ROLE_KEY:-dummy}
|
||||
AUTH_SECRET: ${AUTH_SECRET:-dummy_secret_for_local_testing_only_1234567890}
|
||||
ports:
|
||||
- "3001:3000"
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.wwv.rule=HostRegexp(`{user:[a-z0-9-]+}.app.worldwideview.dev`) || Host(`app.worldwideview.dev`) || Host(`localhost`) || HostRegexp(`{user:[a-z0-9-]+}.localhost`)"
|
||||
- "traefik.http.routers.wwv.entrypoints=web,websecure"
|
||||
# - "traefik.http.routers.wwv.tls.certresolver=letsencrypt"
|
||||
- "traefik.http.services.wwv.loadbalancer.server.port=3000"
|
||||
depends_on:
|
||||
- db
|
||||
|
||||
traefik:
|
||||
image: traefik:v3.0
|
||||
command:
|
||||
- "--api.insecure=true"
|
||||
- "--providers.docker=true"
|
||||
- "--entrypoints.web.address=:80"
|
||||
- "--entrypoints.websecure.address=:443"
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- "/var/run/docker.sock:/var/run/docker.sock:ro"
|
||||
@@ -12,9 +12,34 @@ services:
|
||||
- "AUTH_SECRET=${AUTH_SECRET:-default_secret_for_local_dev}"
|
||||
- "WWV_DEMO_ADMIN_SECRET=${WWV_DEMO_ADMIN_SECRET:-}"
|
||||
- "WWV_BRIDGE_TOKEN=${WWV_BRIDGE_TOKEN:-}"
|
||||
- "DATABASE_URL=${DATABASE_URL:-postgresql://postgres:postgres@db:5432/worldwideview?schema=public}"
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
|
||||
db:
|
||||
image: postgres:15-alpine
|
||||
restart: always
|
||||
environment:
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: postgres
|
||||
POSTGRES_DB: worldwideview
|
||||
ports:
|
||||
- "5432:5432"
|
||||
volumes:
|
||||
- postgres-data:/var/lib/postgresql/data
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U postgres -d worldwideview"]
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 60s
|
||||
profiles:
|
||||
- "${WWV_SKIP_LOCAL_DB:-}"
|
||||
|
||||
volumes:
|
||||
wwv-data:
|
||||
postgres-data:
|
||||
|
||||
networks:
|
||||
coolify:
|
||||
|
||||
+38
-5
@@ -1,14 +1,47 @@
|
||||
#!/bin/sh
|
||||
# ─── Docker Entrypoint ───────────────────────────────────────
|
||||
# Ensures the SQLite database exists and is migrated before
|
||||
# starting the application. On first run with a fresh volume
|
||||
# the DB file won't exist yet, so we run prisma migrate deploy.
|
||||
# Ensures the PostgreSQL database is migrated before starting
|
||||
# the application. DATABASE_URL must point to a PostgreSQL
|
||||
# instance (Supabase, self-hosted, etc).
|
||||
|
||||
set -e
|
||||
|
||||
mkdir -p ./data
|
||||
if [ -z "$DATABASE_URL" ]; then
|
||||
echo "────────────────────────────────────────────────────────────────"
|
||||
echo "🚨 CRITICAL: DATABASE_URL IS NOT SET"
|
||||
echo "────────────────────────────────────────────────────────────────"
|
||||
echo "WorldWideView has migrated to PostgreSQL. If you are an old user,"
|
||||
echo "please update your docker-compose.yml to include a Postgres service."
|
||||
echo ""
|
||||
echo "To migrate your legacy data after setting up Postgres, run:"
|
||||
echo "docker exec -it <container_name> node scripts/migrate-legacy.mjs"
|
||||
echo "────────────────────────────────────────────────────────────────"
|
||||
|
||||
# If dev.db exists, we know they are upgrading. Don't crash, just wait for config.
|
||||
if [ -f "prisma/dev.db" ]; then
|
||||
echo "[entrypoint] Legacy data detected. Waiting for DATABASE_URL to be configured..."
|
||||
# We don't exit here, we'll let the app try to start or just sleep.
|
||||
# For now, let's just let it proceed so they can see the setup page error.
|
||||
else
|
||||
echo "[entrypoint] Exiting. Please provide a DATABASE_URL."
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "[entrypoint] Running database migrations..."
|
||||
npx -y prisma migrate deploy
|
||||
prisma migrate deploy
|
||||
echo "[entrypoint] Migrations complete."
|
||||
|
||||
# Generate self-signed SSL certificates for local HTTPS bridging if they don't exist
|
||||
if [ ! -f "./data/localhost.crt" ] || [ ! -f "./data/localhost.key" ]; then
|
||||
echo "[entrypoint] Generating self-signed SSL certificates for port 3001..."
|
||||
mkdir -p ./data
|
||||
openssl req -nodes -new -x509 -keyout ./data/localhost.key -out ./data/localhost.crt -days 365 -subj "/CN=localhost" 2>/dev/null || echo "[entrypoint] Warning: Failed to generate SSL certs"
|
||||
fi
|
||||
|
||||
# Start the HTTPS proxy in the background
|
||||
if [ -f "./scripts/https-proxy.mjs" ]; then
|
||||
node ./scripts/https-proxy.mjs &
|
||||
fi
|
||||
|
||||
exec node server.js
|
||||
@@ -1,91 +0,0 @@
|
||||
# API Reference
|
||||
|
||||
This document provides a technical reference for the core internal services of WorldWideView. These services are designed to be used by plugins and core components for communication and data management.
|
||||
|
||||
## `DataBus`
|
||||
|
||||
The `DataBus` is a central event emitter used for decoupled, typed communication between different parts of the application.
|
||||
|
||||
- **Import**: `import { dataBus } from "@/core/data/DataBus";`
|
||||
- **Source**: `src/core/data/DataBus.ts`
|
||||
|
||||
### Methods
|
||||
|
||||
#### `on<K>(event: K, handler: Handler): () => void`
|
||||
Subscribes to an event. Returns an unsubscribe function.
|
||||
- **event**: The event name (keys of `DataBusEvents`).
|
||||
- **handler**: A callback function receiving the event data.
|
||||
|
||||
#### `off<K>(event: K, handler: Handler): void`
|
||||
Unsubscribes from an event.
|
||||
- **event**: The event name.
|
||||
- **handler**: The handler function to remove.
|
||||
|
||||
#### `emit<K>(event: K, data: T): void`
|
||||
Broadcasts an event to all subscribers.
|
||||
- **event**: The event name.
|
||||
- **data**: The payload for the event.
|
||||
|
||||
#### `removeAllListeners(event?: string): void`
|
||||
Removes all listeners for a specific event, or all listeners if no event is provided.
|
||||
|
||||
---
|
||||
|
||||
## `PluginRegistry`
|
||||
|
||||
The `PluginRegistry` manages the registration and discovery of all `WorldPlugin` implementations.
|
||||
|
||||
- **Import**: `import { pluginRegistry } from "@/core/plugins/PluginRegistry";`
|
||||
- **Source**: `src/core/plugins/PluginRegistry.ts`
|
||||
|
||||
### Methods
|
||||
|
||||
#### `register(plugin: WorldPlugin): void`
|
||||
Adds a new plugin to the registry. Throws a warning if the plugin ID is already registered.
|
||||
|
||||
#### `get(pluginId: string): WorldPlugin | undefined`
|
||||
Retrieves a plugin by its unique ID.
|
||||
|
||||
#### `getAll(): WorldPlugin[]`
|
||||
Returns an array of all registered plugins.
|
||||
|
||||
#### `getByCategory(category: string): WorldPlugin[]`
|
||||
Returns all plugins belonging to a specific category.
|
||||
|
||||
#### `has(pluginId: string): boolean`
|
||||
Checks if a plugin with the given ID is registered.
|
||||
|
||||
#### `unregister(pluginId: string): void`
|
||||
Removes a plugin from the registry.
|
||||
|
||||
---
|
||||
|
||||
## `CacheLayer`
|
||||
|
||||
The `CacheLayer` provides a two-tier caching mechanism for geographical entities.
|
||||
|
||||
- **Import**: `import { cacheLayer } from "@/core/data/CacheLayer";`
|
||||
- **Source**: `src/core/data/CacheLayer.ts`
|
||||
|
||||
### Methods
|
||||
|
||||
#### `init(): Promise<void>`
|
||||
Initializes the IndexedDB store. Must be called before persistent storage operations.
|
||||
|
||||
#### `set(pluginId: string, entities: GeoEntity[], ttlMs?: number): void`
|
||||
Caches entities for a plugin.
|
||||
- **pluginId**: Unique identifier for the data source.
|
||||
- **entities**: Array of `GeoEntity` objects.
|
||||
- **ttlMs**: Time-to-live in milliseconds (default: 30,000).
|
||||
|
||||
#### `get(pluginId: string): GeoEntity[] | null`
|
||||
Retrieves entities from the L1 (Memory) cache. Returns `null` if expired or missing.
|
||||
|
||||
#### `getFromPersistent(pluginId: string): Promise<GeoEntity[] | null>`
|
||||
Retrieves entities from the L2 (IndexedDB) cache. This method also populates the L1 cache on success.
|
||||
|
||||
#### `invalidate(pluginId: string): void`
|
||||
Removes entries for a plugin from both L1 and L2 caches.
|
||||
|
||||
#### `clear(): void`
|
||||
Purges all data from both cache tiers.
|
||||
+25
-17
@@ -1,25 +1,33 @@
|
||||
<!-- Generated: 2026-04-19 15:23:00 UTC -->
|
||||
# System Architecture
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Architecture
|
||||
|
||||
WorldWideView operates on a decoupled Core-and-Plugin architecture. The central platform provides the 3D globe, HUD, timeline, and rendering optimizations, while separate intelligence domains are entirely handled by external plugin packages that are bundled and ingested at runtime.
|
||||
## Overview
|
||||
WorldWideView operates on a decoupled, plugin-based architecture designed for real-time visualization of geospatial data. The system is split between a Next.js 16 frontend that handles UI and CesiumJS 3D rendering, and a network of plugin data seeders that stream live updates via WebSockets.
|
||||
|
||||
The underlying data backbone uses a WebSocket Firehose, streaming continuous high-frequency metrics from standalone data engine microservices perfectly isolated from the visualization layer.
|
||||
The core design philosophy is the "All-Bundle Model," where plugins are dynamically imported at runtime as ES module bundles (`Dynamic CDN Loaded`). The frontend maintains a modular state architecture using Zustand, routing high-frequency data updates through a custom `DataBus` singleton to avoid React render cycle bottlenecks.
|
||||
|
||||
## Component Map
|
||||
- **UI Platform:** `src/components/layout/AppShell.tsx`
|
||||
- **3D Visualizer:** `src/core/globe/GlobeView.tsx`
|
||||
- **State Store:** `src/core/state/globeSlice.ts` and peers.
|
||||
- **Event Bus:** `src/core/data/DataBus.ts`
|
||||
- **Microservice Connectors:** `packages/wwv-plugin-sdk/src/PluginManifest.ts`
|
||||
- **Frontend App Shell:** Next.js App Router providing layout and base API routes (in `src/app/`).
|
||||
- **Globe Rendering Engine:** CesiumJS wrapped in Resium, responsible for 3D primitive and model rendering (in `src/core/globe/`).
|
||||
- **State Management:** Zustand slice-based architecture (in `src/core/state/`).
|
||||
- **Data Pipeline:** Custom event bus (`DataBus`) and WebSocket clients (`DataBusSubscriber`) routing live data to state (in `src/core/data/`).
|
||||
- **Plugin System:** Registration, lifecycle management, and ES module loaders (in `src/core/plugins/`).
|
||||
- **Database Layer:** Prisma ORM connecting to PostgreSQL (in `prisma/`).
|
||||
|
||||
## Key Files
|
||||
- `src/core/globe/GlobeView.tsx` (lines 60-150): The central CesiumJS ingestion point and scene orchestrator.
|
||||
- `src/core/globe/EntityRenderer.tsx` (lines 45-120): High-performance batched Primitive mapping for geometric entities.
|
||||
- `src/core/plugins/PluginManager.ts` (lines 20-100): Validates and bootstraps compiled ES Modules from CDN/local sources.
|
||||
- `src/core/plugins/PluginManager.ts` - The PluginManager class. Core registry that instantiates plugins, calls `initialize()`, and handles lifecycle events.
|
||||
- `src/core/plugins/loaders/InstalledPluginsLoader.ts` - Dynamically fetches and imports `import(/* webpackIgnore: true */ ...)` marketplace plugins into the environment.
|
||||
- `src/core/data/DataBus.ts` - Custom typed event bus singleton that routes high-frequency data around the application.
|
||||
- `src/core/globe/GlobeView.tsx` - The main Cesium viewer container, handling imagery layers, cameras, and primitive collections.
|
||||
- `src/core/state/store.ts` - The main Zustand store registry linking the nine state slices (globe, layers, timeline, ui, filter, data, config, favorites, geojson).
|
||||
|
||||
## Data Flow
|
||||
The real-time data flow triggers globally via WebSockets:
|
||||
1. `src/lib/WsClient.ts` captures the socket frame from `dataengine.worldwideview.dev`.
|
||||
2. Emits payload through `src/core/data/DataBus.ts` (lines 30-50).
|
||||
3. The `DataBusSubscriber.tsx` hook catches the event, sanitizing and merging the data into `src/core/state/dataSlice.ts`.
|
||||
4. `EntityRenderer` automatically reacts to State changes, triggering low-level Cesium Primitive re-draws against the GPU.
|
||||
Real-time data follows a strict unidirectional stream optimized for sub-second updates:
|
||||
|
||||
1. **Engine Push:** A remote data engine pushes state over WebSocket (`/stream`) from either local seeders (`ws://localhost:5001/stream`) or the cloud fallback (`wss://dataengine.worldwideview.dev/stream`).
|
||||
2. **WebSocket Client Router:** `WsClient.handleMessage()` receives the payload and pipes it to the event bus.
|
||||
3. **DataBus Emission:** The bus fires `DataBus.emit("websocketData", WsStreamPayload)`.
|
||||
4. **State Hydration:** The `DataBusSubscriber` component listens to the bus and calls `_hydrateSnapshot()` to update the Zustand store's `entitiesByPlugin` cache.
|
||||
5. **Memoized Selection:** `GlobeView` selects the visible entities from the store.
|
||||
6. **Primitive Rendering:** The `EntityRenderer` translates store entities into Cesium `PointPrimitiveCollection` and `BillboardCollection` arrays for GPU rendering.
|
||||
7. **Animation & LOD:** `AnimationLoop` handles horizon culling and hover effects, while `useModelRendering` promotes close-range entities to 3D glTF models.
|
||||
@@ -1,452 +0,0 @@
|
||||
# WorldWideView Plugin Guide
|
||||
|
||||
Build custom data layer plugins for the WorldWideView 3D globe platform. This guide covers the full plugin lifecycle, available APIs, and step-by-step instructions for creating your own plugin.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ UI Layer │
|
||||
│ LayerPanel ─ InfoCard ─ Timeline ─ ConfigPanel │
|
||||
└────────────────────┬────────────────────────────┘
|
||||
│ Zustand Store
|
||||
┌────────────────────┴────────────────────────────┐
|
||||
│ Plugin Manager │
|
||||
│ register → initialize → enable/disable → poll │
|
||||
│ ┌────────┴────────┐ │
|
||||
│ PluginRegistry PollingManager │
|
||||
│ │ │ │
|
||||
│ DataBus (events) CacheLayer (2-tier) │
|
||||
└────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌────────────────────┴────────────────────────────┐
|
||||
│ Your Plugin (WorldPlugin) │
|
||||
│ fetch() → GeoEntity[] → renderEntity() → Globe │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Plugin Lifecycle
|
||||
|
||||
1. **Instantiation**: Your class is instantiated and passed to `pluginRegistry.register()`.
|
||||
2. **Registration**: The `PluginManager` discovers the plugin in the registry during the boot sequence.
|
||||
3. **Initialization**: `initialize(ctx)` is called. This is where you should set up your domain-specific API clients or static data.
|
||||
4. **Enabled State**: When a user toggles the layer in the UI, the `PluginManager` starts the polling cycle.
|
||||
5. **Fetch/Render Cycle**: `fetch()` is called periodically; `renderEntity()` is called for result.
|
||||
6. **Destruction**: `destroy()` is called if the plugin is unregistered or the application is unmounted.
|
||||
|
||||
### Data Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant PM as PluginManager
|
||||
participant P as YourPlugin
|
||||
participant DB as DataBus
|
||||
|
||||
PM->>P: initialize(ctx)
|
||||
Note over PM, P: User toggles layer ON
|
||||
loop Every getPollingInterval()
|
||||
PM->>P: fetch(timeRange)
|
||||
P-->>PM: GeoEntity[]
|
||||
PM->>DB: emit("dataUpdated")
|
||||
end
|
||||
Note over PM, P: User toggles layer OFF
|
||||
PM->>PM: Stop Polling
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start: Minimal Plugin
|
||||
|
||||
```typescript
|
||||
// src/plugins/earthquakes/index.ts
|
||||
import { Activity } from "lucide-react";
|
||||
import type {
|
||||
WorldPlugin, GeoEntity, TimeRange, PluginContext,
|
||||
LayerConfig, CesiumEntityOptions,
|
||||
} from "@/core/plugins/PluginTypes";
|
||||
|
||||
export class EarthquakePlugin implements WorldPlugin {
|
||||
id = "earthquake";
|
||||
name = "Earthquakes";
|
||||
description = "Recent seismic activity from USGS";
|
||||
icon = Activity;
|
||||
category = "natural-disaster" as const;
|
||||
version = "1.0.0";
|
||||
|
||||
private context: PluginContext | null = null;
|
||||
|
||||
async initialize(ctx: PluginContext): Promise<void> {
|
||||
this.context = ctx;
|
||||
}
|
||||
|
||||
destroy(): void {
|
||||
this.context = null;
|
||||
}
|
||||
|
||||
async fetch(_timeRange: TimeRange): Promise<GeoEntity[]> {
|
||||
const res = await fetch("/api/earthquake");
|
||||
if (!res.ok) return [];
|
||||
const data = await res.json();
|
||||
return data.features.map((f: any): GeoEntity => ({
|
||||
id: `earthquake-${f.id}`,
|
||||
pluginId: "earthquake",
|
||||
latitude: f.geometry.coordinates[1],
|
||||
longitude: f.geometry.coordinates[0],
|
||||
altitude: 0,
|
||||
timestamp: new Date(f.properties.time),
|
||||
label: `M${f.properties.mag}`,
|
||||
properties: {
|
||||
magnitude: f.properties.mag,
|
||||
depth: f.geometry.coordinates[2],
|
||||
place: f.properties.place,
|
||||
},
|
||||
}));
|
||||
}
|
||||
|
||||
getPollingInterval(): number {
|
||||
return 120000; // 2 minutes
|
||||
}
|
||||
|
||||
getLayerConfig(): LayerConfig {
|
||||
return {
|
||||
color: "#ef4444",
|
||||
clusterEnabled: true,
|
||||
clusterDistance: 40,
|
||||
};
|
||||
}
|
||||
|
||||
renderEntity(entity: GeoEntity): CesiumEntityOptions {
|
||||
const mag = (entity.properties.magnitude as number) || 0;
|
||||
return {
|
||||
type: "point",
|
||||
color: mag >= 5 ? "#dc2626" : mag >= 3 ? "#f97316" : "#fbbf24",
|
||||
size: Math.max(4, mag * 2),
|
||||
outlineColor: "#000000",
|
||||
outlineWidth: 1,
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Register Your Plugin
|
||||
|
||||
In your app's initialization code (e.g. the root layout component):
|
||||
|
||||
```typescript
|
||||
import { pluginRegistry } from "@/core/plugins/PluginRegistry";
|
||||
import { EarthquakePlugin } from "@/plugins/earthquakes";
|
||||
|
||||
pluginRegistry.register(new EarthquakePlugin());
|
||||
```
|
||||
|
||||
That's it. The plugin will appear in the Layer Panel and can be toggled on/off.
|
||||
|
||||
---
|
||||
|
||||
## WorldPlugin Interface Reference
|
||||
|
||||
### Required Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
|---|---|---|
|
||||
| `id` | `string` | Unique identifier (e.g. `"aviation"`, `"earthquake"`) |
|
||||
| `name` | `string` | Display name shown in the Layer Panel |
|
||||
| `description` | `string` | Short description shown below the name |
|
||||
| `icon` | `string \| ComponentType` | Lucide icon component or emoji string |
|
||||
| `category` | `PluginCategory` | Grouping in the Layer Panel |
|
||||
| `version` | `string` | Semver version string |
|
||||
|
||||
**Available categories:** `aviation`, `maritime`, `conflict`, `natural-disaster`, `infrastructure`, `cyber`, `economic`, `custom`
|
||||
|
||||
### Required Methods
|
||||
|
||||
#### `initialize(ctx: PluginContext): Promise<void>`
|
||||
|
||||
Called once when the plugin is registered. Store the context for later use.
|
||||
|
||||
```typescript
|
||||
interface PluginContext {
|
||||
apiBaseUrl: string; // Base URL for API calls
|
||||
timeRange: TimeRange; // Current time window
|
||||
onDataUpdate: (entities: GeoEntity[]) => void; // Push data updates
|
||||
onError: (error: Error) => void; // Report errors
|
||||
}
|
||||
```
|
||||
|
||||
#### `destroy(): void`
|
||||
|
||||
Cleanup when the plugin is unregistered. Release any resources.
|
||||
|
||||
#### `fetch(timeRange: TimeRange): Promise<GeoEntity[]>`
|
||||
|
||||
Called by the polling system at your declared interval. Return an array of `GeoEntity` objects representing your data points.
|
||||
|
||||
#### `getPollingInterval(): number`
|
||||
|
||||
Return the polling interval in milliseconds. This determines how often `fetch()` is called.
|
||||
|
||||
#### `getLayerConfig(): LayerConfig`
|
||||
|
||||
Return the default layer configuration. These values are used to initialize the UI and the renderer:
|
||||
|
||||
```typescript
|
||||
interface LayerConfig {
|
||||
color: string; // Default CSS color for primary visualization
|
||||
iconUrl?: string; // Default icon for billboards (if applicable)
|
||||
clusterEnabled: boolean; // Enable spatial clustering at high zoom levels
|
||||
clusterDistance: number; // Cluster radius in pixels (suggested: 40)
|
||||
minZoomLevel?: number; // Hide entities when camera is too far (meters)
|
||||
maxEntities?: number; // Limit for performance safety
|
||||
showLabelsByDefault?: boolean; // If true, labels show without hover
|
||||
}
|
||||
```
|
||||
|
||||
#### `renderEntity(entity: GeoEntity): CesiumEntityOptions`
|
||||
|
||||
Called for each entity to determine how it appears on the globe:
|
||||
|
||||
```typescript
|
||||
interface CesiumEntityOptions {
|
||||
type: "billboard" | "point" | "polyline" | "polygon" | "label";
|
||||
color?: string; // CSS color string
|
||||
size?: number; // Pixel size (for points)
|
||||
iconUrl?: string; // Image URL (for billboards)
|
||||
rotation?: number; // Degrees, applied to billboards
|
||||
outlineColor?: string; // CSS color for point outlines
|
||||
outlineWidth?: number; // Outline width in pixels
|
||||
labelText?: string; // Text label above the entity
|
||||
labelFont?: string; // CSS font string for labels
|
||||
}
|
||||
```
|
||||
|
||||
### Optional Methods
|
||||
|
||||
#### `getSelectionBehavior(entity: GeoEntity): SelectionBehavior | null`
|
||||
|
||||
Return trail rendering and camera behavior when an entity is selected. Return `null` for default behavior.
|
||||
|
||||
```typescript
|
||||
interface SelectionBehavior {
|
||||
showTrail?: boolean; // Render a trail polyline
|
||||
trailDurationSec?: number; // Trail length in seconds (default: 60)
|
||||
trailStepSec?: number; // Trail point spacing (default: 5)
|
||||
trailColor?: string; // CSS color (default: '#00fff7')
|
||||
flyToOffsetMultiplier?: number; // Camera offset multiplier (default: 3)
|
||||
flyToBaseDistance?: number; // Base camera distance in meters (default: 30000)
|
||||
}
|
||||
```
|
||||
|
||||
**Example:** Show trails only for airborne entities:
|
||||
```typescript
|
||||
getSelectionBehavior(entity: GeoEntity): SelectionBehavior | null {
|
||||
if (entity.properties.on_ground) return null;
|
||||
return { showTrail: true, trailColor: "#00fff7" };
|
||||
}
|
||||
```
|
||||
|
||||
#### `getServerConfig(): ServerPluginConfig`
|
||||
|
||||
Declare your plugin's server-side data layer requirements:
|
||||
|
||||
```typescript
|
||||
interface ServerPluginConfig {
|
||||
apiBasePath: string; // e.g. "/api/aviation"
|
||||
pollingIntervalMs: number; // Server-side polling interval
|
||||
requiresAuth?: boolean; // OAuth/API key needed
|
||||
historyEnabled?: boolean; // Supports timeline playback
|
||||
availabilityEnabled?: boolean; // Reports time ranges
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** The current server infrastructure (API routes, background polling) is set up per-plugin in `src/app/api/<pluginId>/` and `src/lib/`. See [Server-Side Data Layer](#server-side-data-layer) for the pattern.
|
||||
|
||||
#### `getSidebarComponent(): ComponentType`
|
||||
|
||||
Return a React component to render in the sidebar when this plugin's layer is active.
|
||||
|
||||
#### `getDetailComponent(): ComponentType<{ entity: GeoEntity }>`
|
||||
|
||||
Return a React component to render in the detail panel when an entity from this plugin is selected.
|
||||
|
||||
---
|
||||
|
||||
## GeoEntity
|
||||
|
||||
The universal data model for all plugin entities:
|
||||
|
||||
```typescript
|
||||
interface GeoEntity {
|
||||
id: string; // Unique ID (prefix with pluginId)
|
||||
pluginId: string; // Must match your plugin's `id`
|
||||
latitude: number; // WGS84 latitude
|
||||
longitude: number; // WGS84 longitude
|
||||
altitude?: number; // Meters above sea level
|
||||
heading?: number; // Degrees (0 = North, 90 = East)
|
||||
speed?: number; // Meters per second
|
||||
timestamp: Date; // When this data was captured
|
||||
label?: string; // Short display label
|
||||
properties: Record<string, unknown>; // Plugin-specific data
|
||||
}
|
||||
```
|
||||
|
||||
**Conventions:**
|
||||
- **`id`** — Prefix with your plugin ID to avoid collisions: `"earthquake-us7000abc"`
|
||||
- **`heading` + `speed`** — If both are set, the renderer will extrapolate movement between polls (smooth animation)
|
||||
- **`properties`** — Use for domain-specific data (e.g. magnitude, vessel type, altitude). These are accessible in info cards and detail panels
|
||||
|
||||
---
|
||||
|
||||
## Core Services
|
||||
|
||||
### DataBus — Event Communication
|
||||
|
||||
Subscribe to cross-plugin events:
|
||||
|
||||
```typescript
|
||||
import { dataBus } from "@/core/data/DataBus";
|
||||
|
||||
// Available events
|
||||
dataBus.on("dataUpdated", ({ pluginId, entities }) => { ... });
|
||||
dataBus.on("entitySelected", ({ entity }) => { ... });
|
||||
dataBus.on("layerToggled", ({ pluginId, enabled }) => { ... });
|
||||
dataBus.on("timeRangeChanged", ({ timeRange }) => { ... });
|
||||
dataBus.on("cameraPreset", ({ presetId }) => { ... });
|
||||
```
|
||||
|
||||
### CacheLayer — Two-Tier Caching
|
||||
|
||||
The PluginManager automatically caches your `fetch()` results in:
|
||||
1. **Memory** — instant recall within the same session
|
||||
2. **IndexedDB** — survives page refreshes
|
||||
|
||||
You don't need to interact with the cache directly — it's managed by the PluginManager.
|
||||
|
||||
### PollingManager — Automatic Polling
|
||||
|
||||
Your `getPollingInterval()` return value is used to set up automatic polling. Features:
|
||||
- **Exponential backoff** on errors (up to 60s max)
|
||||
- **Pause/resume** support
|
||||
- **Dynamic interval updates** — users can adjust intervals in the Config Panel
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Data Layer
|
||||
|
||||
For plugins that need server-side processing (API proxying, database persistence, authentication), follow this pattern:
|
||||
|
||||
### 1. Create an API Route
|
||||
|
||||
```
|
||||
src/app/api/<your-plugin>/route.ts
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { NextResponse } from "next/server";
|
||||
|
||||
export async function GET() {
|
||||
// Fetch from your data source
|
||||
const res = await fetch("https://api.example.com/data", {
|
||||
headers: { "Authorization": `Bearer ${process.env.YOUR_API_KEY}` },
|
||||
cache: "no-store",
|
||||
});
|
||||
|
||||
if (!res.ok) {
|
||||
return NextResponse.json({ error: res.statusText }, { status: res.status });
|
||||
}
|
||||
|
||||
const data = await res.json();
|
||||
return NextResponse.json(data);
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Optional: Background Polling
|
||||
|
||||
For APIs with rate limits, create a server-side polling module:
|
||||
|
||||
```
|
||||
src/lib/<your-plugin>-polling.ts
|
||||
```
|
||||
|
||||
Register it in `src/instrumentation.ts`:
|
||||
|
||||
```typescript
|
||||
export async function register() {
|
||||
if (process.env.NEXT_RUNTIME === "nodejs") {
|
||||
const { startYourPluginPolling } = await import("./lib/your-plugin-polling");
|
||||
startYourPluginPolling();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Optional: History Endpoint
|
||||
|
||||
For timeline/playback support, add a history route:
|
||||
|
||||
```
|
||||
src/app/api/<your-plugin>/history/route.ts
|
||||
```
|
||||
|
||||
Accept a `?time=<ms>` parameter and return the closest historical records.
|
||||
|
||||
### 4. Declare in Plugin
|
||||
|
||||
Use `getServerConfig()` to document your server-side setup:
|
||||
|
||||
```typescript
|
||||
getServerConfig(): ServerPluginConfig {
|
||||
return {
|
||||
apiBasePath: "/api/earthquake",
|
||||
pollingIntervalMs: 120000,
|
||||
historyEnabled: false,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rendering Details
|
||||
|
||||
### Billboard vs Point
|
||||
|
||||
| Feature | `billboard` | `point` |
|
||||
|---|---|---|
|
||||
| Custom image | Yes via `iconUrl` | No |
|
||||
| Rotation | Yes via `rotation` | No |
|
||||
| Performance | Good (GPU batched) | Best (single draw call) |
|
||||
| Outline | No | Yes via `outlineColor/Width` |
|
||||
|
||||
**Use billboards** for entities with custom icons and rotation (aircraft, vehicles).
|
||||
**Use points** for simpler markers (fires, earthquakes, vessels).
|
||||
|
||||
### Labels
|
||||
|
||||
Labels are automatically hidden at long distances and shown within 500km or on hover/selection. Configure via `labelText` and `labelFont` in your `renderEntity()` return.
|
||||
|
||||
### Position Extrapolation
|
||||
|
||||
If your `GeoEntity` has both `heading` and `speed` set, the globe renderer will automatically extrapolate smooth movement between polling intervals (up to 5 minutes). This creates fluid animation without increasing your API call frequency.
|
||||
|
||||
---
|
||||
|
||||
## Existing Plugin Examples
|
||||
|
||||
| Plugin | Category | Data Source | Rendering | Selection |
|
||||
|---|---|---|---|---|
|
||||
| [Aviation](../src/plugins/aviation/index.ts) | `aviation` | OpenSky Network (live + Supabase fallback) | Billboards with altitude-based coloring | Trail polyline for airborne entities |
|
||||
| [Maritime](../src/plugins/maritime/index.ts) | `maritime` | AIS feeds (with demo fallback) | Points with vessel-type coloring | Default |
|
||||
| [Wildfire](../src/plugins/wildfire/index.ts) | `natural-disaster` | NASA FIRMS (VIIRS) | Points with FRP-based sizing/coloring | Default |
|
||||
|
||||
---
|
||||
|
||||
## Checklist: Publishing a Plugin
|
||||
|
||||
- [ ] Implements all required `WorldPlugin` methods
|
||||
- [ ] `id` is unique and lowercase (no spaces)
|
||||
- [ ] All `GeoEntity.id` values are prefixed with your plugin ID
|
||||
- [ ] `GeoEntity.pluginId` matches your plugin's `id`
|
||||
- [ ] `renderEntity()` returns valid `CesiumEntityOptions`
|
||||
- [ ] API route created (if needed) at `src/app/api/<id>/`
|
||||
- [ ] Plugin registered in the app initialization code
|
||||
- [ ] Tested: toggle on/off in Layer Panel
|
||||
- [ ] Tested: entity hover and click selection
|
||||
- [ ] Tested: info card displays your `properties` correctly
|
||||
@@ -1,75 +0,0 @@
|
||||
# Setup & Installation
|
||||
|
||||
Follow these steps to set up your development environment and get WorldWideView running locally.
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Node.js**: v18.17 or higher (tested on v20+)
|
||||
- **pnpm**: v8 or higher (`npm install -g pnpm`)
|
||||
- **Browser**: Chrome, Firefox, or Edge (CesiumJS requires WebGL support)
|
||||
|
||||
## Environment Setup
|
||||
|
||||
Run the setup script to auto-generate `.env.local` with a secure `AUTH_SECRET`:
|
||||
|
||||
```bash
|
||||
pnpm run setup
|
||||
```
|
||||
|
||||
This copies `.env.example` → `.env.local` and fills in `AUTH_SECRET` automatically. You can then optionally add API keys for enhanced features (Cesium Ion, Bing Maps, OpenSky, etc.).
|
||||
|
||||
> [!NOTE]
|
||||
> `AUTH_SECRET` must remain stable across restarts. The setup script generates it once and writes it to `.env.local`. Never commit `.env.local` to git.
|
||||
|
||||
## Running Locally
|
||||
|
||||
1. **Install Dependencies**:
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
2. **Generate environment file** (first time only):
|
||||
```bash
|
||||
pnpm run setup
|
||||
```
|
||||
|
||||
3. **Start Dev Server**:
|
||||
```bash
|
||||
pnpm run dev:all
|
||||
```
|
||||
|
||||
4. **Open Browser**:
|
||||
Navigate to [http://localhost:3000](http://localhost:3000).
|
||||
|
||||
## Folder Structure Explanation
|
||||
|
||||
Understanding the project layout:
|
||||
|
||||
```text
|
||||
worldwideview/
|
||||
├── docs/ # Project documentation
|
||||
├── packages/ # Plugin packages (pnpm workspaces)
|
||||
├── public/ # Static assets (GeoJSON data files, Cesium dependencies)
|
||||
├── scripts/ # Build and utility scripts (e.g., copy-cesium.mjs)
|
||||
└── src/
|
||||
├── app/ # Next.js App Router (Layouts, Pages, API Routes)
|
||||
├── components/ # React UI components (HUD, LayersPanel, Panels)
|
||||
├── core/ # Core engine logic
|
||||
│ ├── data/ # Data management (DataBus, Polling, Cache)
|
||||
│ ├── globe/ # Cesium-specific hooks and view logic
|
||||
│ └── plugins/ # Plugin system base and registry
|
||||
├── lib/ # Utility libraries and server-side logic
|
||||
└── plugins/ # Built-in plugins (Aviation, Maritime, etc.)
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
To verify your setup:
|
||||
1. Ensure the globe loads without errors in the console.
|
||||
2. Check if the "Aviation" layer is visible in the Layers Panel.
|
||||
3. Verify that the HUD (top bar) displays live camera coordinates.
|
||||
|
||||
---
|
||||
|
||||
> [!TIP]
|
||||
> The database is created automatically on first run — no manual setup is required. If you need to reset it, delete `data/wwv.db` and restart the dev server.
|
||||
@@ -1,48 +0,0 @@
|
||||
# User Guide
|
||||
|
||||
Welcome to WorldWideView! This guide will help you navigate the 3D globe and interact with live data layers.
|
||||
|
||||
## Navigating the Globe
|
||||
|
||||
- **Rotate**: Left-click and drag.
|
||||
- **Zoom**: Use the mouse wheel or pinch on a trackpad.
|
||||
- **Tilt/Rotate Perspective**: Right-click and drag (or use Ctrl + Left-click).
|
||||
- **Fly to Location**: Double-click on an entity or use the search bar (if available).
|
||||
|
||||
## Application Panels
|
||||
|
||||
### Layers Panel
|
||||
Located on the left side of the screen, the Layers Panel allows you to toggle different data sources on and off.
|
||||
- **Search Layers**: Filter the available plugins.
|
||||
- **Toggle Visibility**: Enable or disable specific data layers like Aviation, Maritime, or Wildfires.
|
||||
- **Layer Configuration**: Some layers provide settings like clustering or color customization.
|
||||
|
||||
### HUD (Heads-Up Display)
|
||||
The HUD at the top provides real-time information about your current view:
|
||||
- **Camera Coordinates**: Latitude, Longitude, and Altitude.
|
||||
- **Pitch & Heading**: Current orientation of the camera.
|
||||
- **FPS Indicator**: Performance metrics.
|
||||
|
||||
### Timeline
|
||||
The timeline at the bottom allows you to track data over time.
|
||||
- **Current Time**: Displays the simulated time on the globe.
|
||||
- **Playback Controls**: If supported by the plugin, you can scrubbing through historical data.
|
||||
|
||||
## Interacting with Entities
|
||||
|
||||
- **Hover**: Hover over a marker (point or billboard) to see a quick label.
|
||||
- **Selection**: Click on an entity to open its **Info Card**.
|
||||
- **Info Card**: Displays detailed properties about the selected object (e.g., flight number, vessel type, fire intensity).
|
||||
- **Trails**: Some entities (like aircraft) show a historical trail when selected.
|
||||
|
||||
## Settings & Configuration
|
||||
|
||||
You can access global settings through the **Config Panel**. Here you can:
|
||||
- Adjust the **Polling Interval** for data updates.
|
||||
- Toggle **Night Mode** or change the **Imagery Base Map** (e.g., Satellite, Terrain, Street).
|
||||
- Manage **Cache Settings** to clear offline data.
|
||||
|
||||
---
|
||||
|
||||
> [!TIP]
|
||||
> Use the **[Keyboard Shortcuts]** (coming soon) for faster navigation and panel toggling.
|
||||
+25
-13
@@ -1,20 +1,32 @@
|
||||
<!-- Generated: 2026-04-19 15:23:00 UTC -->
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Build System
|
||||
|
||||
WorldWideView operates using a strict `pnpm` monorepo workspace to manage the core Next.js application alongside its surrounding plugin ecosystem.
|
||||
## Overview
|
||||
WorldWideView uses a pnpm monorepo workspace for managing both the main application and its associated SDK and plugin packages. The primary build system relies on Next.js 16 with custom Webpack optimizations, specifically designed to output a standalone trace for highly efficient Docker containerization.
|
||||
|
||||
The build relies heavily on Next.js standalone output tracing optimization, allowing minimal-footprint Docker images via Multi-stage resolution.
|
||||
|
||||
## Key Files
|
||||
- `pnpm-workspace.yaml`: Governs the inclusion of `packages/*` elements.
|
||||
- `next.config.ts` (lines 10-45): Implements `output: "standalone"` and strict Content-Security-Policy headers.
|
||||
- `Dockerfile` (lines 1-110): Executes the multi-stage Extractor Pattern (`deps` → `builder` → `runner`).
|
||||
The core build configuration resides in `package.json` and `next.config.ts`. A custom standalone tracer strips unnecessary CLI dependencies (`prisma`, `dotenv`) from the final build to prevent fatal container runtime crashes.
|
||||
|
||||
## Build Workflows
|
||||
- **Dependency Install:** `pnpm install` must be run from the root directory to respect strict workspace hoisting natively.
|
||||
- **Development Proxy:** `pnpm dev` triggers the frontend server locally with active HMR, while executing pre-build scripts like `copy-cesium.mjs`.
|
||||
- **Plugin Compilation:** Run `pnpm -r build` inside `packages/worldwideview-plugins/` to trigger Vite bundle execution mapped to `dist/frontend.mjs`.
|
||||
|
||||
### Standard Development
|
||||
- **Install Dependencies:** `pnpm install` (Installs all workspace packages defined in `pnpm-workspace.yaml`).
|
||||
- **Initial Setup:** `pnpm run setup` (Executes `scripts/setup.mjs` to generate a `.env.local` with a fresh `AUTH_SECRET`).
|
||||
- **Run Development Server (All):** `pnpm dev:all` (Concurrently starts the Next.js frontend and the local `wwv-data-engine` backends).
|
||||
|
||||
### Production Build
|
||||
- **Build Command:** `pnpm build` (Executes `next build --webpack`).
|
||||
- **Output:** Generates a `.next/standalone/` folder ready for execution.
|
||||
- **Static Assets:** `scripts/copy-cesium.mjs` is executed during `predev` and `build` to copy pre-compiled CesiumJS static assets into the `public/cesium/` directory, keeping them out of the output tracer.
|
||||
|
||||
## Platform Setup
|
||||
- **Cesium Resources:** Required assets (Workers, Assets, Widgets) are structurally bound into the `public/cesium/` folder during the pre-build pipeline initialized by `scripts/copy-cesium.mjs` (lines 10-38).
|
||||
- **SQLite Engine:** `prisma.config.ts` must export native javascript objects (free of dev CLI wrappers) for Next.js to trace correctly in the final standalone Node build.
|
||||
|
||||
- **Database Migrations:** Prisma schema is located at `prisma/schema.prisma`. During development, `pnpm dev` triggers a `predev` hook running `npx prisma migrate deploy` to ensure PostgreSQL tables are initialized.
|
||||
- **Microservices:** Data engine seeders and standalone Fastify backend plugins (like `wwv-plugin-iranwarlive/backend`) are started via `pnpm start:backends` and managed locally inside `packages/*/backend`.
|
||||
- **Plugin Packages:** Internal plugin packages must be properly listed in `tsconfig.json` paths and `next.config.ts`'s `transpilePackages` array.
|
||||
|
||||
## Reference
|
||||
|
||||
- **Monorepo Config:** `pnpm-workspace.yaml` - defines package locations (`packages/*` and `packages/*/backend`).
|
||||
- **Next Config:** `next.config.ts` - controls the standalone output, `transpilePackages`, and restrictive security headers.
|
||||
- **Prisma Config:** `prisma.config.ts` - Native JavaScript object export used to bypass Next.js tracer issues with dynamic imports.
|
||||
- **Cesium Script:** `scripts/copy-cesium.mjs` - Handles static asset injection.
|
||||
@@ -1,344 +0,0 @@
|
||||
# Creating a WorldWideView Plugin
|
||||
|
||||
This guide walks you through building, publishing, and listing your own WorldWideView plugin from scratch.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
WorldWideView plugins display geospatial data on a 3D Cesium globe. Every plugin must implement the `WorldPlugin` interface from the **Plugin SDK** (`@worldwideview/wwv-plugin-sdk`).
|
||||
|
||||
There are **three plugin formats**:
|
||||
|
||||
| Format | Use Case | Example |
|
||||
|---|---|---|
|
||||
| **`static`** | GeoJSON file loaded at startup — no API calls at runtime | Military Bases, Nuclear Facilities, Embassies |
|
||||
| **`bundle`** | Full TypeScript class with custom logic, live API data, UI components | Aviation, Maritime, Wildfire |
|
||||
| **`declarative`** | JSON-only manifest that points to an external API — no code needed | *(Future)* |
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js ≥ 18
|
||||
- An NPM account (for publishing)
|
||||
- A running WorldWideView instance (local clone or Docker container)
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Scaffold Your Plugin
|
||||
|
||||
WorldWideView plugins are strictly decoupled from the core application. You do **not** build them inside the WorldWideView monorepo. Instead, use the official CLI tool:
|
||||
|
||||
```bash
|
||||
npx @worldwideview/create-plugin@latest my-data-layer
|
||||
cd my-data-layer
|
||||
npm install
|
||||
```
|
||||
|
||||
This will generate a ready-to-use template including your `package.json`, `plugin.json`, and Vite build configuration.
|
||||
|
||||
### Linking During Development
|
||||
|
||||
To see your plugin live on the globe while you develop:
|
||||
|
||||
1. Configure your CLI to point to your running WorldWideView instance:
|
||||
```bash
|
||||
npx wwv config set wwv-path C:\path\to\your\worldwideview
|
||||
```
|
||||
2. Link the plugin:
|
||||
```bash
|
||||
npm run link
|
||||
```
|
||||
3. Run the dev watcher to rebuild on save:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
*Note: If you are running WorldWideView via Docker, ensure `WWV_PLUGIN_DEV=true` is set in your environment variables and mount your plugin's `dist/` folder into the container's `/app/plugins-local/` directory.*
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The `worldwideview` object block inside your `package.json` is strictly required for the CLI link command and if you intend to publish your plugin to the WorldWideView Marketplace. The marketplace uses this internal manifest to determine how to categorize and display your plugin automatically.
|
||||
> * `id`: The unique string identifier.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The SDK is declared as a **peer dependency**, not a direct dependency. The host application provides it at runtime.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Write Your Plugin Code
|
||||
|
||||
Create `src/index.ts`. Here are examples for the two most common formats:
|
||||
|
||||
### Option A — Static GeoJSON Plugin (simplest)
|
||||
|
||||
For static plugins, the npm package is just metadata. The actual loading is handled by the `StaticDataPlugin` loader at runtime, driven by a manifest + GeoJSON file.
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* @worldwideview/wwv-plugin-my-data
|
||||
*
|
||||
* Static GeoJSON plugin — my custom dataset.
|
||||
*
|
||||
* This package exists for npm registry metadata. The actual plugin logic
|
||||
* is handled by WorldWideView's StaticDataPlugin loader at runtime using
|
||||
* the manifest + GeoJSON data file served from the host application.
|
||||
*/
|
||||
export const PLUGIN_ID = "my-data" as const;
|
||||
```
|
||||
|
||||
For static plugins you also need:
|
||||
1. A **GeoJSON file** placed at `public/data/my_data.geojson` in the main app
|
||||
2. A **manifest entry** in the marketplace (see Step 4)
|
||||
|
||||
### Option B — Bundle Plugin (full control)
|
||||
|
||||
For bundle plugins, you write a class that implements the `WorldPlugin` interface:
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
WorldPlugin,
|
||||
GeoEntity,
|
||||
TimeRange,
|
||||
PluginContext,
|
||||
LayerConfig,
|
||||
CesiumEntityOptions,
|
||||
} from "@worldwideview/wwv-plugin-sdk";
|
||||
|
||||
export class MyDataPlugin implements WorldPlugin {
|
||||
// ─── Required Metadata ──────────────────────────────
|
||||
id = "my-data";
|
||||
name = "My Data Layer";
|
||||
description = "Displays custom points on the globe.";
|
||||
icon = "MapPin"; // Lucide icon name (string)
|
||||
category = "custom" as const;
|
||||
version = "1.0.0";
|
||||
|
||||
// ─── Lifecycle ──────────────────────────────────────
|
||||
async initialize(ctx: PluginContext): Promise<void> {
|
||||
// Called once when the plugin is loaded.
|
||||
// Use ctx.apiBaseUrl, ctx.timeRange, ctx.onDataUpdate, etc.
|
||||
}
|
||||
|
||||
destroy(): void {
|
||||
// Called when the plugin is unloaded. Clean up timers, sockets, etc.
|
||||
}
|
||||
|
||||
// ─── Data ───────────────────────────────────────────
|
||||
async fetch(timeRange: TimeRange): Promise<GeoEntity[]> {
|
||||
// Fetch your data from an API and return GeoEntity objects.
|
||||
const res = await fetch("https://api.example.com/points");
|
||||
const data = await res.json();
|
||||
|
||||
return data.map((item: any) => ({
|
||||
id: String(item.id),
|
||||
pluginId: this.id,
|
||||
latitude: item.lat,
|
||||
longitude: item.lon,
|
||||
altitude: 0,
|
||||
timestamp: new Date(),
|
||||
label: item.name,
|
||||
properties: { type: item.type },
|
||||
}));
|
||||
}
|
||||
|
||||
getPollingInterval(): number {
|
||||
return 60_000; // Re-fetch every 60 seconds
|
||||
}
|
||||
|
||||
// ─── Rendering ──────────────────────────────────────
|
||||
getLayerConfig(): LayerConfig {
|
||||
return {
|
||||
color: "#3b82f6",
|
||||
clusterEnabled: true,
|
||||
clusterDistance: 40,
|
||||
maxEntities: 5000,
|
||||
};
|
||||
}
|
||||
|
||||
renderEntity(entity: GeoEntity): CesiumEntityOptions {
|
||||
return {
|
||||
type: "point",
|
||||
color: "#3b82f6",
|
||||
size: 8,
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — Publish to npm
|
||||
|
||||
```bash
|
||||
cd packages/wwv-plugin-my-data
|
||||
pnpm publish --access public
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> The marketplace pulls metadata (version, description, keywords, readme) directly from the npm registry. You do not need to duplicate this information anywhere else.
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Submit to the Marketplace
|
||||
|
||||
Once your package is published to npm, submit it for listing in the WorldWideView Marketplace:
|
||||
|
||||
1. Go to [marketplace.worldwideview.dev/submit](https://marketplace.worldwideview.dev/submit) (or open the Admin UI on a local marketplace instance)
|
||||
2. Enter your **npm package name** (e.g. `@worldwideview/wwv-plugin-my-data`)
|
||||
3. The marketplace automatically fetches your metadata from npm and reads the `"worldwideview"` block from your `package.json`
|
||||
4. Your plugin enters a **pending** state for review
|
||||
5. Once approved, it appears in the browse catalog
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The `"worldwideview"` block in your `package.json` is required for submission. Make sure `id`, `icon`, `category`, and `format` are correctly set before publishing.
|
||||
|
||||
### For static format plugins
|
||||
|
||||
If your plugin uses `"format": "static"`, your **GeoJSON file** must be hosted and accessible at a public URL, or included in the `public/data/` folder of the host WorldWideView application. The `dataFile` path in your manifest should point to that URL.
|
||||
|
||||
If you are contributing a plugin for inclusion in the official WorldWideView release, place the GeoJSON at `public/data/<name>.geojson` and open a pull request.
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Test Locally
|
||||
|
||||
1. Start all WorldWideView services: `pnpm run dev:all` (in the monorepo root)
|
||||
2. (Wait for both the main app and marketplace to start)
|
||||
3. Open the marketplace at `http://localhost:3001/browse`
|
||||
4. Find your plugin and click **Install**
|
||||
5. Verify the data appears on the globe at `http://localhost:3000`
|
||||
|
||||
---
|
||||
|
||||
## SDK Interface Reference
|
||||
|
||||
The `WorldPlugin` interface requires these properties and methods:
|
||||
|
||||
### Required Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
|---|---|---|
|
||||
| `id` | `string` | Unique plugin identifier (e.g., `"my-data"`) |
|
||||
| `name` | `string` | Display name shown in the sidebar |
|
||||
| `description` | `string` | Short description |
|
||||
| `icon` | `string \| ComponentType` | Lucide icon name or React component |
|
||||
| `category` | `PluginCategory` | One of: `aviation`, `maritime`, `conflict`, `natural-disaster`, `infrastructure`, `cyber`, `economic`, `custom` |
|
||||
| `version` | `string` | Semver version string |
|
||||
|
||||
### Required Methods
|
||||
|
||||
| Method | Returns | Description |
|
||||
|---|---|---|
|
||||
| `initialize(ctx)` | `Promise<void>` | Set up the plugin. Receives `PluginContext` with API URLs, time range, callbacks |
|
||||
| `destroy()` | `void` | Clean up resources (timers, sockets, etc.) |
|
||||
| `fetch(timeRange)` | `Promise<GeoEntity[]>` | Return the data to display on the globe |
|
||||
| `getPollingInterval()` | `number` | Milliseconds between `fetch()` calls |
|
||||
| `getLayerConfig()` | `LayerConfig` | Layer appearance (color, clustering, limits) |
|
||||
| `renderEntity(entity)` | `CesiumEntityOptions` | How each entity renders on the globe |
|
||||
|
||||
### Optional Methods
|
||||
|
||||
| Method | Returns | Description |
|
||||
|---|---|---|
|
||||
| `getSelectionBehavior(entity)` | `SelectionBehavior \| null` | Trail / fly-to on click |
|
||||
| `getServerConfig()` | `ServerPluginConfig` | Server-side API routing |
|
||||
| `getFilterDefinitions()` | `FilterDefinition[]` | Declarative filter UI |
|
||||
| `getSidebarComponent()` | `ComponentType` | Custom sidebar panel |
|
||||
| `getDetailComponent()` | `ComponentType<{ entity }>` | Custom detail panel |
|
||||
| `getSettingsComponent()` | `ComponentType<{ pluginId }>` | Custom settings panel |
|
||||
|
||||
### Key Types
|
||||
|
||||
```typescript
|
||||
interface GeoEntity {
|
||||
id: string;
|
||||
pluginId: string;
|
||||
latitude: number;
|
||||
longitude: number;
|
||||
altitude?: number;
|
||||
heading?: number;
|
||||
speed?: number;
|
||||
timestamp: Date;
|
||||
label?: string;
|
||||
properties: Record<string, unknown>;
|
||||
}
|
||||
|
||||
interface LayerConfig {
|
||||
color: string;
|
||||
iconUrl?: string;
|
||||
clusterEnabled: boolean;
|
||||
clusterDistance: number;
|
||||
minZoomLevel?: number;
|
||||
maxEntities?: number;
|
||||
}
|
||||
|
||||
interface CesiumEntityOptions {
|
||||
type: "billboard" | "point" | "polyline" | "polygon" | "label" | "model";
|
||||
color?: string;
|
||||
size?: number;
|
||||
iconUrl?: string;
|
||||
rotation?: number;
|
||||
modelUrl?: string;
|
||||
modelScale?: number;
|
||||
// ... more options
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Real Examples
|
||||
|
||||
### Borders Plugin (bundle format)
|
||||
|
||||
A minimal bundle plugin that implements the `WorldPlugin` interface directly:
|
||||
|
||||
- **Source**: `packages/wwv-plugin-borders/src/index.ts`
|
||||
- **npm**: `@worldwideview/wwv-plugin-borders`
|
||||
|
||||
### Military Bases Plugin (static format)
|
||||
|
||||
A static GeoJSON plugin where the npm package is just metadata:
|
||||
|
||||
- **Source**: `packages/wwv-plugin-military-bases/src/index.ts`
|
||||
- **GeoJSON**: `public/data/military_bases.geojson`
|
||||
- **npm**: `@worldwideview/wwv-plugin-military-bases`
|
||||
- **Manifest**: Defined in `worldwideview-marketplace/src/data/pluginManifests.ts`
|
||||
|
||||
---
|
||||
|
||||
## How It All Connects
|
||||
|
||||
```
|
||||
Developer writes plugin
|
||||
│
|
||||
▼
|
||||
Publish to npm ► npm registry (stores version, description, keywords, readme)
|
||||
│
|
||||
▼
|
||||
Submit npm package name to Marketplace
|
||||
│
|
||||
▼
|
||||
Marketplace fetches metadata from npm ← npm registry
|
||||
and reads the "worldwideview" block from package.json
|
||||
│
|
||||
▼
|
||||
Review → Plugin appears in browse catalog
|
||||
│
|
||||
▼
|
||||
User clicks "Install"
|
||||
│
|
||||
▼
|
||||
Marketplace sends manifest to WorldWideView instance
|
||||
│
|
||||
▼
|
||||
Plugin saved to database (Prisma) → loaded on next startup
|
||||
│
|
||||
▼
|
||||
loadPluginFromManifest() routes by format:
|
||||
static → StaticDataPlugin (GeoJSON loader)
|
||||
bundle → dynamic import()
|
||||
│
|
||||
▼
|
||||
Plugin renders on the 3D globe
|
||||
```
|
||||
+58
-10
@@ -1,18 +1,66 @@
|
||||
<!-- Generated: 2026-04-19 15:23:00 UTC -->
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Deployment
|
||||
|
||||
WorldWideView is container-first. The codebase relies entirely on Dockerizing the Next.js `output: "standalone"` artifact and its localized Prisma SQLite core to enable horizontal orchestration.
|
||||
|
||||
Deployments are coordinated directly via Coolify natively compiling the Docker configurations.
|
||||
## Overview
|
||||
WorldWideView utilizes a containerized deployment strategy based on Docker's multi-stage builds. To minimize the footprint of the Next.js runtime, it leverages the Next.js `standalone` output trace, effectively dropping unnecessary development dependencies and generating a highly optimized Node.js artifact.
|
||||
|
||||
## Package Types
|
||||
- **Next.js Core Bundle:** Built directly via `pnpm build`, extracting into `<root>/.next/standalone`.
|
||||
- **Plugin Microservices:** Hosted alongside the Next.js router natively using Fastify images (defined in `docker-compose.yml`), enabling real-time Python/Node scraping backends exclusively connected via docker network aliases.
|
||||
- **CDN ESM Bundles:** Independent frontend plugins run via Vite rollup configurations (`vite.config.ts`), generating `dist/frontend.mjs` payloads published to the public NPM registry.
|
||||
|
||||
### Main Application
|
||||
- **Build Output:** Located at `.next/standalone/`.
|
||||
- **Static Assets:** Cesium static workers are injected at build time via `scripts/copy-cesium.mjs`.
|
||||
|
||||
### Plugin Microservices
|
||||
- Standalone plugin backends (e.g., `wwv-plugin-iranwarlive/backend`) are isolated via individual `Dockerfile` configurations and orchestrated together in production using `docker-compose.yml`.
|
||||
|
||||
## Platform Deployment
|
||||
- **Dockerfile:** `Dockerfile` explicitly targets `node:22-alpine` instances to restrict vulnerability surface areas while mapping the necessary system volume at `/app/data` to capture the `wwv.db` SQLite instantiation safely out-of-container (lines 80-112).
|
||||
- **Environment Hydration:** Coolify directly passes the active environment headers `.env` values at runtime, utilizing `.env.local` natively for credentials like `AUTH_SECRET` and `DATABASE_URL`.
|
||||
|
||||
### Coolify Integration
|
||||
WorldWideView deploys optimally to Coolify using a Dockerfile builder.
|
||||
- **Environment Variables:** Must be explicitly mapped in the Coolify UI (e.g., `DATABASE_URL`, `AUTH_SECRET`).
|
||||
- **Persistent Storage:** PostgreSQL databases must be hosted externally or mounted via persistent volumes to ensure the frontend registry (installed plugins, user configs) survives container rebuilds.
|
||||
- **Microservices Deployment:** The `wwv-data-engine-internal` and associated plugin seeders are deployed as separate Coolify services communicating over private internal networks.
|
||||
|
||||
### Docker Structure
|
||||
- **Dockerfile:** Found at the project root (`Dockerfile`). Uses an Extractor Pattern (`deps` → `builder` → `runner`). The `.git` and `node_modules` folders must be explicitly untracked to prevent cache overlap.
|
||||
- **Compose:** Local multi-container emulation is handled via `docker-compose.yml`.
|
||||
|
||||
## Reverse Proxies (Nginx Proxy Manager)
|
||||
|
||||
When deploying WorldWideView behind a reverse proxy like Nginx Proxy Manager (NPM), you must configure both the proxy and the container environment correctly to prevent NextAuth from hanging during login, and to allow the real-time Cesium data stream to function.
|
||||
|
||||
### Container Environment Variables
|
||||
NextAuth v5 requires strict host trust when placed behind a proxy. Add the following to your Docker `.env` file or Coolify environment variables:
|
||||
|
||||
```bash
|
||||
# Required: Tells NextAuth to trust the reverse proxy headers
|
||||
AUTH_TRUST_HOST=true
|
||||
|
||||
# Required: The exact external URL your users visit
|
||||
NEXTAUTH_URL=https://your-domain.com
|
||||
```
|
||||
|
||||
### Nginx Proxy Manager Configuration
|
||||
In the NPM UI for your WorldWideView Proxy Host:
|
||||
1. **Details Tab:** Ensure **Websockets Support** is toggled **ON** (Required for the live `/stream` telemetry).
|
||||
2. **Details Tab:** Ensure **Force SSL** is toggled **ON**. NextAuth will often refuse authentication flows over plain HTTP.
|
||||
3. **Advanced Tab:** Nginx Proxy Manager sometimes fails to pass the correct host headers required by Next.js. Add the following to the Custom Nginx Configuration box:
|
||||
|
||||
```nginx
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-Host $host;
|
||||
proxy_set_header Host $host;
|
||||
|
||||
# Optional: Disable proxy buffering if 3D tiles load slowly
|
||||
proxy_buffering off;
|
||||
proxy_request_buffering off;
|
||||
```
|
||||
|
||||
## Reference
|
||||
The core production mapping operates cleanly off HTTP port `3000`. Refer to `next.config.ts` (lines 5-15) for strict caching strategies utilized globally across deployments.
|
||||
- **Standalone Config:** `next.config.ts` (sets `output: "standalone"`).
|
||||
- **Prisma Export:** `prisma.config.ts` ensures no CLI wrappers are invoked inside the standalone container, preventing fatal `MODULE_NOT_FOUND` runtime crashes.
|
||||
- **Docker Mounts:**
|
||||
- Main App: PostgreSQL data volume (if running in-cluster)
|
||||
- Data Engine: PostgreSQL data volume (if running in-cluster)
|
||||
- Cache: `/data` (Redis)
|
||||
+61
-14
@@ -1,26 +1,73 @@
|
||||
<!-- Generated: 2026-04-19 15:23:00 UTC -->
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Development
|
||||
|
||||
Development on WorldWideView leverages modern, rigid structural constraints to ensure cross-plugin consistency, extreme browser optimization, and a minimal global footprint.
|
||||
|
||||
New features are designed within isolated workspaces, using SDK structures rather than forcing logic into the core engine.
|
||||
## Overview
|
||||
Development on WorldWideView prioritizes modularity, high performance, and strict architectural boundaries between the UI and the 3D rendering context. We adhere to rigorous file size constraints and rely heavily on Vanilla CSS and Zustand slice-patterns to maintain clarity across the large ecosystem.
|
||||
|
||||
## Code Style
|
||||
- **TypeScript Strictness:** Strict types are enforced across all domains (`tsconfig.json` lines 4-20). Any use of `any` inside platform routers is forbidden.
|
||||
- **Styling constraints:** All CSS is strictly limited to Vanilla CSS via CSS Modules (`.module.css`). Tailwind is prohibited to prevent styling collisions natively with dynamically loaded elements from third-party plugins. (`src/app/globals.css`).
|
||||
|
||||
### File Size Limits
|
||||
- **Max 150 lines per file.** If a component or function grows beyond this, you must modularize it. Extract helper functions, split React components, and utilize custom hooks.
|
||||
|
||||
### Styling Conventions
|
||||
- **Vanilla CSS Only:** Do not use Tailwind CSS or CSS-in-JS.
|
||||
- **Global Styles:** Located at `src/app/globals.css`.
|
||||
- **Component Styles:** Use CSS Modules (`.module.css`) or co-locate `.css` files directly next to their components.
|
||||
- **HUD Animations:** Specialized interface animations are stored in `src/styles/hud-animations.css`.
|
||||
|
||||
### Import Aliases
|
||||
- Application core: `@/*` → `./src/*`
|
||||
- Plugin SDK: `@worldwideview/wwv-plugin-sdk` → `./packages/wwv-plugin-sdk/src`
|
||||
- Custom plugins use their respective names configured in `tsconfig.json`.
|
||||
|
||||
## Common Patterns
|
||||
- **Env Variable Injection:** Plugins read remote contexts generically instantiated via the SDK.
|
||||
|
||||
### Entity Rendering
|
||||
When translating raw plugin data into `CesiumEntityOptions` inside `renderEntity()`, follow these strict graphical rules:
|
||||
```typescript
|
||||
// From wwv-plugin-aviation/src/index.ts:60-70
|
||||
let engineBase = this.context?.env?.DATA_ENGINE_URL || "https://dataengine.worldwideview.dev";
|
||||
// Correct Point Pattern
|
||||
renderEntity(entity: GeoEntity): CesiumEntityOptions {
|
||||
return {
|
||||
type: "point",
|
||||
color: "#ff0000",
|
||||
size: 10,
|
||||
outlineColor: "#ffffff",
|
||||
outlineWidth: 2
|
||||
};
|
||||
}
|
||||
|
||||
// Correct Billboard Pattern
|
||||
renderEntity(entity: GeoEntity): CesiumEntityOptions {
|
||||
return {
|
||||
type: "billboard",
|
||||
color: "#ffffff",
|
||||
iconUrl: "/icons/aircraft.png",
|
||||
iconScale: 0.5
|
||||
};
|
||||
}
|
||||
```
|
||||
> [!WARNING]
|
||||
> **NEVER MIX PROPERTIES:** Do not apply `size`, `outlineWidth`, or `outlineColor` to a `billboard` entity. Mixing these parameters causes severe GPU clipping and rendering artifacts in Cesium.
|
||||
|
||||
### State Access
|
||||
Zustand is divided into slices. For performance, components must select exactly the properties they need to avoid over-rendering:
|
||||
```typescript
|
||||
// From src/components/panels/LayerPanel.tsx
|
||||
const activeLayers = useStore((state) => state.layers.active);
|
||||
const toggleLayer = useStore((state) => state.layers.toggle);
|
||||
```
|
||||
- **Zustand Slices:** The store is heavily splintered based on structural domain, keeping the hook listeners granular so mapping updates don't aggressively trigger `AppShell` root rerenders. (`src/core/state/globeSlice.ts`).
|
||||
|
||||
## Workflows
|
||||
- **Local Database Setup:** Run `pnpm db:reset` to nuke and redeploy the standard Prisma schema across `data/wwv.db`.
|
||||
- **Generating Plugins:** Use the global CLI `npx @worldwideview/create-plugin@latest <name>` to initialize a decoupled plugin outside of the monorepo.
|
||||
- **Linking Plugins:** Use `npm run link` in the plugin directory after setting `npx wwv config set wwv-path <path>`.
|
||||
|
||||
### Debugging & Temporary Scripts
|
||||
Whenever generating temporary debugging scripts, testing REST endpoints via `.mjs`, or dumping traces/JSON outputs, **save these exclusively inside `/local-scripts/`**.
|
||||
- *Reference:* The root directory is strictly for production configuration files.
|
||||
|
||||
### Scaffold a New Component
|
||||
1. Create a new directory under `src/components/{category}/MyComponent`.
|
||||
2. Add `MyComponent.tsx` and `MyComponent.module.css`.
|
||||
3. Export from a local `index.ts` if creating a composite view.
|
||||
|
||||
## Reference
|
||||
File size is constrained to a 150-line soft cap. Hooks and computational math helpers must be rigorously offloaded (e.g. `src/core/globe/hooks/useModelRendering.ts`).
|
||||
- **Core Abstractions:** See `packages/wwv-plugin-sdk/src/PluginTypes.ts` for interface expectations.
|
||||
- **State Slices:** Located in `src/core/state/` (e.g., `globeSlice.ts`, `dataSlice.ts`).
|
||||
+22
-14
@@ -1,25 +1,33 @@
|
||||
<!-- Generated: 2026-04-19 15:23:00 UTC -->
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Files Catalog
|
||||
|
||||
WorldWideView maps rigid structural directories to manage its layered microservice architecture, distinguishing tightly between UI layout routing, system memory, 3D visualization, and microservice ingestion mechanisms.
|
||||
## Overview
|
||||
WorldWideView is structured as a pnpm monorepo. The primary application resides in the root `src/` directory, while external dependencies, plugins, and the core Plugin SDK are abstracted into the `packages/` directory.
|
||||
|
||||
Every major component is siloed deeply to ensure the monolithic main engine remains perfectly isolated and agnostic to individual data sources.
|
||||
The system is highly modularized to separate React UI rendering from heavy CesiumJS 3D operations and high-frequency real-time WebSocket state management.
|
||||
|
||||
## Core Source Files
|
||||
- `src/app/` - The Next.js 16 core routing platform, housing layout constraints, `api/` backends, and full-screen auth portals.
|
||||
- `src/components/` - Segmented React JSX components handling overlay panels, timeline UI, and floating popups.
|
||||
- `src/core/plugins/` - Essential bridge scripts that validate manifested metadata parameters before dynamically allocating JS module environments to run external logic. (`PluginManager.ts`)
|
||||
- `src/app/` - The Next.js App Router entry points. Contains `layout.tsx` (the core React shell), `page.tsx` (the globe view), and `/api/` (server-side NextAuth and API handlers).
|
||||
- `src/core/plugins/PluginManager.ts` - Central orchestration unit for dynamic plugins. Handles loading, lifecycle (`initialize`, `destroy`), and manifest resolution.
|
||||
- `src/core/globe/GlobeView.tsx` - The primary CesiumJS container. It memoizes Zustand state to prevent heavy re-renders while injecting `EntityRenderer` primitives.
|
||||
- `src/core/data/DataBus.ts` - Singleton pub/sub event bus handling all high-velocity WebSocket stream events without triggering React re-renders.
|
||||
- `src/core/state/store.ts` - The primary Zustand state registry exporting all nine discrete slices (`globe`, `layers`, `timeline`, `ui`, `filter`, `data`, `config`, `favorites`, `geojson`).
|
||||
|
||||
## Platform Implementation
|
||||
- `src/core/globe/GlobeView.tsx` - Initializer mapping global config hooks to the main Cesium `Viewer`.
|
||||
- `src/core/globe/EntityRenderer.tsx` - Extremely hot processing loop extracting Zustand state variables directly to WebGL GPU hardware calls via Cesium Primitives.
|
||||
- `src/core/globe/StackManager.ts` - Spiderifier spatial engine dynamically resolving overlapping coordinate markers geometrically in 3D-space.
|
||||
- `src/core/plugins/loaders/InstalledPluginsLoader.ts` - Platform-specific loader that dynamically injects ES module CDNs via `import(/* webpackIgnore: true */)`.
|
||||
- `src/core/globe/hooks/useCameraActions.ts` - Abstraction connecting React UI logic to raw CesiumJS camera math (flyTo, lookAt).
|
||||
- `src/lib/edition.ts` - Platform edition configuration. Exposes runtime feature flags for `local`, `cloud`, and `demo` deployments.
|
||||
|
||||
## Build System
|
||||
- `Dockerfile` - Multi-stage container instructions targeting a 110MB production Alpine build footprint.
|
||||
- `next.config.ts` - NextJS 16 overrides forcing standalone rendering extraction and tight CSP headers.
|
||||
- `prisma/schema.prisma` - DB tables strictly configuring Prisma to bind exclusively towards locally-mounted SQLite structures.
|
||||
- `package.json` - Root monorepo configuration with `pnpm` workspace bindings.
|
||||
- `next.config.ts` - Next.js compiler settings, security headers, and standalone output configuration.
|
||||
- `docker-compose.yml` - Defines the orchestration of the frontend, Redis cache, and all local plugin microservice backends (`wwv-data-engine`).
|
||||
|
||||
## Configuration
|
||||
- `.agents/` - Complete repository workflow configuration (Antigravity Code). Contains AI `rules/`, `skills/`, and internal architectural `context/` for automatic coordination.
|
||||
- `public/cesium/` - Runtime engine bundles duplicated exclusively during pre-build tracking (copied from `node_modules`).
|
||||
- `prisma/schema.prisma` - PostgreSQL database schema for storing user settings and installed plugin manifests.
|
||||
- `scripts/copy-cesium.mjs` - Crucial build-time script that extracts and copies CesiumJS static web workers to `public/cesium/`.
|
||||
- `public/` - Static assets, plugin icons, and compiled Cesium workers.
|
||||
|
||||
## Reference
|
||||
- **Plugins Directory:** All plugins conform to the `@worldwideview/wwv-plugin-sdk` interface and are developed inside `packages/wwv-plugin-<name>/`.
|
||||
- **Microservices Directory:** Standalone Fastify backends are nested within `packages/wwv-plugin-<name>/backend/`.
|
||||
@@ -0,0 +1,328 @@
|
||||
<!-- Generated: 2026-04-23 20:29:00 UTC -->
|
||||
# End-to-End Tutorial: Building a Real-Time ISS Tracking Plugin
|
||||
|
||||
Welcome! This tutorial is designed for complete beginners. If you have never built a WorldWideView plugin before, you are in the right place.
|
||||
|
||||
By following these steps exactly, you will build a complete, real-time International Space Station (ISS) tracker from scratch. You will learn how to set up your environment, stream live data using a backend seeder, render it in 3D on the globe, and publish your work to the world.
|
||||
|
||||
Let's get started.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Setting up your Workspace
|
||||
|
||||
Before we write any code, we need to prepare your computer. We will install the required tools and download the two main repositories that make up the WorldWideView platform.
|
||||
|
||||
### 1.1 Install Prerequisites
|
||||
|
||||
Ensure you have the following installed on your machine:
|
||||
1. **Node.js**: Download and install [Node.js](https://nodejs.org/) (Version 18 or higher is required).
|
||||
2. **Git**: Download and install [Git](https://git-scm.com/).
|
||||
3. **pnpm**: This is the package manager we use. Open your terminal and run:
|
||||
```bash
|
||||
npm install -g pnpm
|
||||
```
|
||||
|
||||
### 1.2 Clone the Repositories
|
||||
|
||||
You need both the frontend application and the backend data engine. Open your terminal and navigate to the folder where you want to store your code (e.g., `C:\dev`).
|
||||
|
||||
Run these commands to download the code:
|
||||
```bash
|
||||
git clone https://github.com/silvertakana/worldwideview.git
|
||||
git clone https://github.com/silvertakana/wwv-data-engine.git
|
||||
```
|
||||
|
||||
### 1.3 Install Dependencies
|
||||
|
||||
Next, we need to install the libraries that these projects depend on.
|
||||
|
||||
First, install dependencies for the Data Engine:
|
||||
```bash
|
||||
cd wwv-data-engine
|
||||
pnpm install
|
||||
```
|
||||
|
||||
Second, install dependencies for the main WorldWideView application:
|
||||
```bash
|
||||
cd ../worldwideview
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 1.4 Setup Environment Variables
|
||||
|
||||
WorldWideView needs a few basic configuration keys to run.
|
||||
|
||||
While still in the `worldwideview` folder, run the automated setup script. This will generate a `.env.local` file with the necessary secrets:
|
||||
```bash
|
||||
pnpm run setup
|
||||
```
|
||||
|
||||
Your workspace is now ready!
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Creating the Data Engine Seeder (Backend)
|
||||
|
||||
The ISS moves incredibly fast. If our frontend tries to ask for its location every second, it will lag. Instead, we use the **Bring Your Own Backend (BYOB)** pattern. We will write a "Seeder" script in the Data Engine that fetches the ISS location and instantly broadcasts it to the frontend via WebSockets.
|
||||
|
||||
### 2.1 Create the Seeder File
|
||||
|
||||
Navigate to your data engine repository and create a new file named `iss.ts` in the `src/seeders` folder:
|
||||
`c:\dev\wwv-data-engine\src\seeders\iss.ts`
|
||||
|
||||
### 2.2 Write the Polling Logic
|
||||
|
||||
Open `iss.ts` in your text editor and paste the following code. This script reaches out to the free WhereTheISS.at API every 5 seconds and saves the data to the engine's memory (Redis).
|
||||
|
||||
```typescript
|
||||
import { setLiveSnapshot } from '../core/redis';
|
||||
import axios from 'axios';
|
||||
|
||||
const WTIA_URL = 'https://api.wheretheiss.at/v1/satellites/25544';
|
||||
const POLLING_INTERVAL = 5000; // 5 seconds
|
||||
|
||||
async function pollISS() {
|
||||
try {
|
||||
// 1. Fetch data from the API
|
||||
const response = await axios.get(WTIA_URL);
|
||||
const data = response.data;
|
||||
|
||||
// 2. Format the data into a GeoEntity object
|
||||
const stateObj = {
|
||||
id: 25544,
|
||||
name: "International Space Station",
|
||||
latitude: data.latitude,
|
||||
longitude: data.longitude,
|
||||
altitude: data.altitude * 1000, // Convert kilometers to meters
|
||||
velocity: data.velocity,
|
||||
visibility: data.visibility,
|
||||
footprint: data.footprint
|
||||
};
|
||||
|
||||
// 3. Save to Redis under the 'iss' namespace for 60 seconds
|
||||
await setLiveSnapshot('iss', { "25544": stateObj }, 60);
|
||||
console.log(`[ISS] Poll OK: updated position to ${data.latitude}, ${data.longitude}`);
|
||||
|
||||
} catch (error) {
|
||||
console.error(`[ISS] Polling error:`, error.message);
|
||||
} finally {
|
||||
// 4. Repeat the process after 5 seconds
|
||||
setTimeout(pollISS, POLLING_INTERVAL);
|
||||
}
|
||||
}
|
||||
|
||||
// Start the loop
|
||||
pollISS();
|
||||
```
|
||||
|
||||
### 2.3 Register the Seeder
|
||||
|
||||
The engine needs to know your seeder exists. Open `c:\dev\wwv-data-engine\src\seeders\index.ts` and add this line at the bottom:
|
||||
|
||||
```typescript
|
||||
import './iss';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Testing the Data Engine
|
||||
|
||||
Before we build the frontend, let's prove that our backend is actually fetching the ISS data.
|
||||
|
||||
### 3.1 Start the Engine
|
||||
|
||||
In your terminal, navigate to the `wwv-data-engine` folder and start the backend:
|
||||
```bash
|
||||
pnpm dev:backends
|
||||
```
|
||||
You should see `[ISS] Poll OK: updated position` appearing in your console every 5 seconds. Leave this terminal running.
|
||||
|
||||
### 3.2 Write a Quick Test Script
|
||||
|
||||
Open a *new* terminal window. Let's write a tiny script to peek into the engine's memory. Create a file called `test_iss.mjs` in the `wwv-data-engine` folder:
|
||||
|
||||
```javascript
|
||||
// test_iss.mjs
|
||||
import Redis from 'ioredis';
|
||||
const redis = new Redis();
|
||||
|
||||
async function verify() {
|
||||
const data = await redis.get('data:iss:live');
|
||||
if (data) {
|
||||
console.log("Success! We found the ISS:", JSON.parse(data));
|
||||
} else {
|
||||
console.log("No data found yet.");
|
||||
}
|
||||
process.exit(0);
|
||||
}
|
||||
verify();
|
||||
```
|
||||
|
||||
Run the script:
|
||||
```bash
|
||||
node test_iss.mjs
|
||||
```
|
||||
If you see a large block of data containing coordinates and altitude, your backend is working perfectly!
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Creating the WorldWideView Plugin (Frontend)
|
||||
|
||||
Now we will build the visual part of the plugin that connects to our backend stream and draws the ISS on the 3D globe.
|
||||
|
||||
### 4.1 Scaffold the Plugin
|
||||
|
||||
In your terminal, navigate back to your main `c:\dev` folder. We will use the official CLI tool to generate a blank plugin template. Run:
|
||||
|
||||
```bash
|
||||
npx @worldwideview/create-plugin@latest wwv-plugin-iss
|
||||
```
|
||||
When prompted, name the folder `wwv-plugin-iss`.
|
||||
|
||||
Move into your new plugin folder and install its dependencies:
|
||||
```bash
|
||||
cd wwv-plugin-iss
|
||||
npm install
|
||||
```
|
||||
|
||||
### 4.2 Write the Plugin Logic
|
||||
|
||||
Open `c:\dev\wwv-plugin-iss\src\index.ts` in your text editor. Replace everything in the file with this code:
|
||||
|
||||
```typescript
|
||||
import type { WorldPlugin, GeoEntity, PluginContext, LayerConfig, CesiumEntityOptions } from "@worldwideview/wwv-plugin-sdk";
|
||||
|
||||
export class IssPlugin implements WorldPlugin {
|
||||
// The ID MUST match the namespace we used in the backend ('iss')
|
||||
id = "iss";
|
||||
name = "ISS Live Tracker";
|
||||
description = "Real-time International Space Station tracking.";
|
||||
icon = "Satellite";
|
||||
category = "space" as const;
|
||||
version = "1.0.0";
|
||||
|
||||
async initialize(ctx: PluginContext): Promise<void> {
|
||||
console.log("ISS Plugin loaded!");
|
||||
}
|
||||
|
||||
destroy(): void { }
|
||||
|
||||
async fetch(): Promise<GeoEntity[]> {
|
||||
// We return an empty array because the WebSockets handle the data automatically.
|
||||
return [];
|
||||
}
|
||||
|
||||
getPollingInterval(): number {
|
||||
return 0; // Disabled: we use continuous WebSockets instead of polling.
|
||||
}
|
||||
|
||||
getLayerConfig(): LayerConfig {
|
||||
return {
|
||||
color: "#00ffcc",
|
||||
clusterEnabled: false
|
||||
};
|
||||
}
|
||||
|
||||
renderEntity(entity: GeoEntity): CesiumEntityOptions {
|
||||
// Level of Detail (LOD): Use a 2D billboard from far away,
|
||||
// and transition to a 3D model when zooming in close.
|
||||
return {
|
||||
type: "billboard",
|
||||
color: "#ffffff",
|
||||
iconUrl: "https://unpkg.com/wwv-plugin-iss/assets/iss-icon.png",
|
||||
iconScale: 0.8,
|
||||
modelUrl: "https://unpkg.com/wwv-plugin-iss/assets/ISS_stationary.glb",
|
||||
modelScale: 2.5,
|
||||
heading: entity.heading || 0,
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Connecting and Testing Everything
|
||||
|
||||
Now we will link your new plugin to your local WorldWideView application to see it in action.
|
||||
|
||||
### 5.1 Link the Plugin
|
||||
|
||||
In your `wwv-plugin-iss` terminal, tell the CLI where your main WorldWideView folder is:
|
||||
```bash
|
||||
npx wwv config set wwv-path C:\dev\worldwideview
|
||||
```
|
||||
|
||||
Now, link the plugin. This creates a shortcut so WorldWideView can see your code:
|
||||
```bash
|
||||
npm run link
|
||||
```
|
||||
|
||||
Start the plugin watcher. This will automatically update your plugin if you make any changes to the code:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
Leave this terminal running.
|
||||
|
||||
### 5.2 Start WorldWideView
|
||||
|
||||
Open a third, final terminal window. Navigate to your main `worldwideview` folder and start the frontend application:
|
||||
```bash
|
||||
cd C:\dev\worldwideview
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### 5.3 View the ISS
|
||||
|
||||
1. Open your web browser and go to `http://localhost:3000`.
|
||||
2. Click the **Layers** icon on the left sidebar.
|
||||
3. Find **ISS Live Tracker** in the list and toggle it ON.
|
||||
4. The globe will instantly fly to the current location of the ISS, and you will see it moving in real-time!
|
||||
|
||||
> [!TIP]
|
||||
> **Troubleshooting missing points:**
|
||||
> - Ensure your Data Engine terminal (`pnpm dev:backends`) is still running.
|
||||
> - Press `F12` in your browser to open Developer Tools. Check the `Console` tab for any red errors.
|
||||
> - Ensure the `id` in your plugin (`"iss"`) exactly matches the name you used in the backend `setLiveSnapshot('iss', ...)`.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Publishing Your Plugin
|
||||
|
||||
You've built it, now share it with the world!
|
||||
|
||||
### 6.1 Update package.json
|
||||
|
||||
Open `c:\dev\wwv-plugin-iss\package.json`. You must add a `"worldwideview"` metadata block so the marketplace knows how to read your plugin. Ensure your file looks like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "wwv-plugin-iss",
|
||||
"version": "1.0.0",
|
||||
"main": "dist/index.js",
|
||||
"worldwideview": {
|
||||
"id": "iss",
|
||||
"name": "ISS Live Tracker",
|
||||
"version": "1.0.0",
|
||||
"icon": "Satellite",
|
||||
"category": "space"
|
||||
},
|
||||
"scripts": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 Publish to NPM
|
||||
|
||||
In your plugin terminal, log in to NPM and publish your package:
|
||||
```bash
|
||||
npm login
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
### 6.3 Submit to the Marketplace
|
||||
|
||||
1. Go to the official marketplace at `https://marketplace.worldwideview.dev/submit`.
|
||||
2. Type in your package name (`wwv-plugin-iss`) and click submit.
|
||||
3. The system will automatically verify your code. Once approved, any WorldWideView user on the planet can click "Install" to add your ISS tracker to their globe.
|
||||
|
||||
**Congratulations!** You have successfully navigated the entire stack, from API polling and WebSockets to 3D rendering and global publishing.
|
||||
@@ -0,0 +1,80 @@
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Advanced Plugin Guide
|
||||
|
||||
This guide covers complex architectures, real-time telemetry streaming, and the deployment lifecycle for WorldWideView plugins. If you haven't built a basic plugin yet, start with the **[Quickstart](plugin-quickstart.md)**.
|
||||
|
||||
## Architecture Paradigm: The All-Bundle Model
|
||||
|
||||
WorldWideView operates on a strict **Dynamic CDN Loaded (Bundle)** architecture.
|
||||
|
||||
> [!WARNING]
|
||||
> **Deprecation Notice:** The legacy `StaticDataPlugin` (GeoJSON loaders) and `DeclarativePlugin` runtimes are fully deprecated. All new plugins must be dynamically imported at runtime as ES module bundles via `import(/* webpackIgnore: true */ entry)`.
|
||||
|
||||
### How Plugins Load
|
||||
1. A user clicks "Install" in the **Marketplace**.
|
||||
2. The marketplace sends the plugin manifest (containing an ES Module CDN URL, like `unpkg.com`) to the WorldWideView database.
|
||||
3. At runtime, the `InstalledPluginsLoader` dynamically fetches the JavaScript bundle.
|
||||
4. The plugin is instantiated, and its `initialize(ctx)` method is invoked.
|
||||
|
||||
## Real-Time Data: Bring Your Own Backend (BYOB)
|
||||
|
||||
Relying on the frontend `fetch()` method is insufficient for high-frequency real-time tracking (like aviation or maritime). For continuous telemetry, you must build a **Data Engine Seeder** — a containerized backend microservice.
|
||||
|
||||
### Microservice Seeder Architecture
|
||||
Instead of the frontend fetching data, your backend container connects to an upstream source, normalizes the data, and publishes it to the central Redis stream managed by `wwv-data-engine`.
|
||||
|
||||
1. **Scaffold a Backend:** Use the CLI to generate a backend template.
|
||||
```bash
|
||||
npx @worldwideview/cli create-backend my-plugin-backend
|
||||
```
|
||||
2. **Containerize:** This generates a Fastify Node.js server with a `Dockerfile` and `docker-compose.yml`.
|
||||
3. **Publish to Redis:** Your backend polls the external API (e.g., ADS-B Exchange) and pushes snapshots to the WorldWideView Redis pipeline.
|
||||
4. **WebSocket Delivery:** The central `wwv-data-engine` immediately broadcasts these updates over WebSockets to all connected clients.
|
||||
|
||||
> [!TIP]
|
||||
> **Debugging WebSockets:** If your frontend isn't receiving data from your backend seeder:
|
||||
> 1. Check the `wwv-data-engine` logs to ensure your seeder is publishing to Redis successfully.
|
||||
> 2. Verify the frontend is connected to the correct WebSocket endpoint. Local instances default to `ws://localhost:5001/stream`, while unrecognized seeders fall back to the cloud at `wss://dataengine.worldwideview.dev/stream`.
|
||||
|
||||
## Advanced Cesium Rendering
|
||||
|
||||
When returning `CesiumEntityOptions` in `renderEntity(entity)`, you have direct access to the 3D engine's capabilities.
|
||||
|
||||
### 3D Models vs. Billboards (LOD Strategy)
|
||||
To maintain 60 FPS with tens of thousands of entities, use WorldWideView's Level of Detail (LOD) promotion system.
|
||||
- Render distant entities as simple `billboard` or `point` primitives.
|
||||
- When the camera gets close, the system's `useModelRendering` hook can promote the entity to a full 3D glTF model.
|
||||
|
||||
```typescript
|
||||
renderEntity(entity: GeoEntity): CesiumEntityOptions {
|
||||
return {
|
||||
type: "billboard", // Primary lightweight renderer
|
||||
color: "#ffffff",
|
||||
iconUrl: "https://unpkg.com/my-plugin/assets/icon.png",
|
||||
iconScale: 0.5,
|
||||
// Provide a 3D model URL. The engine will swap it in automatically at close range.
|
||||
modelUrl: "https://unpkg.com/my-plugin/assets/model.glb",
|
||||
modelScale: 1.0,
|
||||
heading: entity.heading,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
> [!CAUTION]
|
||||
> **GPU Clipping Bug:** NEVER mix `size`, `outlineWidth`, or `outlineColor` properties onto an entity of `type: "billboard"`. This will cause the WebGL compiler to panic and result in severe visual clipping artifacts.
|
||||
|
||||
## Publishing to the Marketplace
|
||||
|
||||
To distribute your plugin globally:
|
||||
|
||||
1. **Publish to NPM:**
|
||||
```bash
|
||||
npm publish --access public
|
||||
```
|
||||
2. **Submit:** Navigate to `https://marketplace.worldwideview.dev/submit`.
|
||||
3. **Register:** Enter your NPM package name. The marketplace automatically scrapes your `package.json` for the required `"worldwideview"` object block (containing your `id`, `icon`, and `category`).
|
||||
4. **Review:** Once approved, your plugin's ES Module bundle will be served via CDN to all WorldWideView instances worldwide.
|
||||
|
||||
### Debugging Marketplace Submissions
|
||||
- **"Invalid Manifest" Error:** Ensure you are using `@worldwideview/wwv-plugin-sdk` as a `peerDependency` (not a direct dependency) so the host application injects the context correctly.
|
||||
- **Icon Not Showing:** Icons must be valid Lucide icon strings (e.g., `"Plane"`, `"Anchor"`).
|
||||
@@ -0,0 +1,126 @@
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Quickstart: Creating Your First Plugin
|
||||
|
||||
Welcome to WorldWideView plugin development! This tutorial will guide you through creating your first custom data layer on the 3D globe.
|
||||
|
||||
By the end of this guide, you will have a working plugin that plots real-time data on the WorldWideView map.
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
Before you start, ensure you have:
|
||||
- Node.js ≥ 18
|
||||
- `npm` or `pnpm` installed
|
||||
- A running instance of WorldWideView on your local machine (running at `http://localhost:3000`).
|
||||
|
||||
## 2. Scaffold Your Plugin
|
||||
|
||||
WorldWideView plugins are built as standard NPM packages. They are entirely decoupled from the core application, allowing you to develop and publish them independently.
|
||||
|
||||
To generate a new plugin template, use the official CLI:
|
||||
|
||||
```bash
|
||||
npx @worldwideview/create-plugin@latest my-first-plugin
|
||||
cd my-first-plugin
|
||||
npm install
|
||||
```
|
||||
|
||||
This creates a lightweight Vite-based project pre-configured with the `@worldwideview/wwv-plugin-sdk`.
|
||||
|
||||
## 3. Link Your Plugin to WorldWideView
|
||||
|
||||
To see your plugin live on the globe while you develop, you need to link it to your local WorldWideView instance.
|
||||
|
||||
First, tell the CLI where your WorldWideView repository is located:
|
||||
```bash
|
||||
npx wwv config set wwv-path C:\path\to\your\worldwideview
|
||||
```
|
||||
|
||||
Next, link the plugin. This creates a symlink so your local WorldWideView instance can dynamically load your code:
|
||||
```bash
|
||||
npm run link
|
||||
```
|
||||
|
||||
Finally, start the plugin watcher. This will automatically rebuild your plugin whenever you save a file:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> **Debugging Link Issues:** If your plugin doesn't appear in the WorldWideView "Installed Plugins" list after linking, check your `package.json`. The `"worldwideview"` object block is strictly required. Ensure `id`, `name`, and `version` are populated correctly.
|
||||
|
||||
## 4. Explore the Code
|
||||
|
||||
Open `src/index.ts` in your text editor. You'll see a class that implements the `WorldPlugin` interface:
|
||||
|
||||
```typescript
|
||||
import type { WorldPlugin, GeoEntity, PluginContext, LayerConfig, CesiumEntityOptions } from "@worldwideview/wwv-plugin-sdk";
|
||||
|
||||
export class MyFirstPlugin implements WorldPlugin {
|
||||
id = "my-first-plugin";
|
||||
name = "My First Data Layer";
|
||||
description = "A simple example plugin.";
|
||||
icon = "MapPin";
|
||||
category = "custom" as const;
|
||||
version = "1.0.0";
|
||||
|
||||
async initialize(ctx: PluginContext): Promise<void> {
|
||||
console.log("Plugin initialized!");
|
||||
}
|
||||
|
||||
destroy(): void { }
|
||||
|
||||
async fetch(timeRange: TimeRange): Promise<GeoEntity[]> {
|
||||
// Generate a single dummy point over Paris
|
||||
return [{
|
||||
id: "test-point-1",
|
||||
pluginId: this.id,
|
||||
latitude: 48.8566,
|
||||
longitude: 2.3522,
|
||||
timestamp: new Date(),
|
||||
properties: { name: "Hello World" },
|
||||
}];
|
||||
}
|
||||
|
||||
getPollingInterval(): number {
|
||||
return 60_000; // Fetch every 60 seconds
|
||||
}
|
||||
|
||||
getLayerConfig(): LayerConfig {
|
||||
return {
|
||||
color: "#ff0000",
|
||||
clusterEnabled: false,
|
||||
clusterDistance: 40,
|
||||
};
|
||||
}
|
||||
|
||||
renderEntity(entity: GeoEntity): CesiumEntityOptions {
|
||||
return {
|
||||
type: "point",
|
||||
color: "#ff0000",
|
||||
size: 15,
|
||||
outlineColor: "#ffffff",
|
||||
outlineWidth: 2
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. View Your Plugin
|
||||
|
||||
1. Ensure your WorldWideView main application is running (`pnpm dev` or `pnpm dev:all` in the main repo).
|
||||
2. Open your browser to `http://localhost:3000`.
|
||||
3. Open the **Layers** panel on the left sidebar.
|
||||
4. Locate "My First Data Layer" and toggle it on.
|
||||
5. The globe will fly to Paris, and you should see a red dot!
|
||||
|
||||
> [!WARNING]
|
||||
> **Debugging Missing Points:** If the layer is toggled on but you don't see the point:
|
||||
> 1. Check your browser's Developer Console (F12) for any `DataBus` errors.
|
||||
> 2. Ensure your `fetch()` method returns an array of `GeoEntity` objects with valid `latitude` and `longitude` properties.
|
||||
> 3. Verify that your `renderEntity()` function returns a valid type (`point`, `billboard`, etc.).
|
||||
|
||||
## Next Steps
|
||||
|
||||
Congratulations! You've successfully built and linked your first plugin.
|
||||
|
||||
For advanced features—like real-time WebSocket streaming, containerizing your own backend microservices, or publishing your plugin to the global Marketplace—proceed to the **[Advanced Plugin Guide](docs/plugin-advanced.md)**.
|
||||
+18
-11
@@ -1,21 +1,28 @@
|
||||
<!-- Generated: 2026-04-19 15:23:00 UTC -->
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Project Overview
|
||||
|
||||
WorldWideView is a real-time geospatial intelligence engine that visualizes live global data on an interactive 3D globe. It leverages a modern frontend stack to render high-density datasets (aircraft, maritime vessels, conflict events, environmental data) synchronously.
|
||||
WorldWideView is a real-time geospatial intelligence engine that visualizes live global data on an interactive 3D globe. It leverages a modern frontend stack to render high-density datasets synchronously, including aircraft, maritime vessels, conflict events, satellites, and environmental data.
|
||||
|
||||
The core value proposition is mapping diverse, decoupled intelligence streams onto a central geographic interface using a dynamically loaded plugin architecture. Data sources operate completely decoupled from the display platform, streaming observations via WebSockets for sub-second visual updates.
|
||||
The core value proposition of WorldWideView is mapping diverse, decoupled intelligence streams onto a central geographic interface using a dynamically loaded plugin architecture. Data sources operate completely decoupled from the display platform, streaming observations via WebSockets for sub-second visual updates. The ecosystem consists of multiple repositories, including the main app (`worldwideview`), the plugin marketplace (`worldwideview-marketplace`), and the WebSocket push server (`wwv-data-engine`).
|
||||
|
||||
## Key Files
|
||||
- `package.json` (lines 1-80) - Core dependencies and project metadata.
|
||||
- `src/app/layout.tsx` (lines 15-40) - Global application shell and React structure.
|
||||
- `src/core/plugins/PluginManager.ts` (lines 20-56) - Heart of the engine, registers and lifecycle-manages external intelligence views.
|
||||
- `package.json` (Lines 1-76) - Core dependencies and project metadata for the monorepo workspace.
|
||||
- `src/app/layout.tsx` - Global application shell and React structure.
|
||||
- `src/core/plugins/PluginManager.ts` - Heart of the engine, registers and lifecycle-manages external intelligence views.
|
||||
- `src/core/globe/GlobeView.tsx` - Main Cesium globe component rendering.
|
||||
|
||||
## Technology Stack
|
||||
- **Framework:** Next.js 16 (App Router) — `src/app/`
|
||||
- **3D Engine:** CesiumJS + Resium — `src/core/globe/GlobeView.tsx` (lines 40-90)
|
||||
- **State Management:** Zustand — `src/core/state/store.ts` (slice pattern)
|
||||
- **Database:** Prisma ORM w/ SQLite locally — `prisma/schema.prisma`
|
||||
- **Typing:** TypeScript 5 w/ Strict Mode — `tsconfig.json`
|
||||
- **Language:** TypeScript 5 (Strict Mode) — `tsconfig.json`
|
||||
- **3D Engine:** CesiumJS + Resium (Google Photorealistic 3D Tiles) — `src/core/globe/GlobeView.tsx`
|
||||
- **State Management:** Zustand — `src/core/state/` (slice-based store)
|
||||
- **Event Bus:** Custom typed `DataBus` — `src/core/data/DataBus.ts`
|
||||
- **Database:** PostgreSQL via Prisma 7 — `prisma/schema.prisma`
|
||||
- **Styling:** Vanilla CSS (no Tailwind) — `src/app/globals.css`
|
||||
|
||||
## Platform Support
|
||||
Built as a highly portable Next.js container, it supports `local`, `cloud`, and `demo` editions via the `NEXT_PUBLIC_WWV_EDITION` flag declared in `.env.local` and evaluated at runtime in `src/core/edition.ts`.
|
||||
Built as a highly portable Next.js container, it supports multiple deployment profiles controlled by `NEXT_PUBLIC_WWV_EDITION` (default: `local`).
|
||||
- **Local (`local`)**: Self-hosted, full features, auth enabled.
|
||||
- **Cloud (`cloud`)**: Managed cloud instance, full features.
|
||||
- **Demo (`demo`)**: Public demo, auth disabled, optional admin via `WWV_DEMO_ADMIN_SECRET`.
|
||||
Feature flags are evaluated at runtime in `src/core/edition.ts`.
|
||||
+35
-18
@@ -1,25 +1,42 @@
|
||||
<!-- Generated: 2026-04-19 15:23:00 UTC -->
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Testing
|
||||
|
||||
WorldWideView maintains a robust Vitest testing infrastructure utilizing `jsdom` environments to mock browser globals and React Testing Library utilities for accurate integration flow testing.
|
||||
|
||||
The primary requirement is full test coverage over authentication routes, edge-case platform parsing, and API rate-limit security.
|
||||
## Overview
|
||||
WorldWideView utilizes Vitest alongside a `jsdom` environment and the React Testing Library to ensure high reliability across core application logic, server APIs, and plugin loaders. Test coverage is strategically focused on shared libraries, core state logic, and the plugin ecosystem mechanisms.
|
||||
|
||||
## Test Types
|
||||
- **Unit Logic:** Verifies math, utilities, and configuration mappings (e.g. `edition.test.ts`).
|
||||
- **Middleware Integration:** Evaluates Request/Response blocks (e.g. `rateLimit.test.ts`).
|
||||
- **Component Mocking:** Exercises the React ecosystem state behaviors (e.g. `DeclarativePlugin.test.ts`).
|
||||
|
||||
## Key Files
|
||||
- `vitest.config.ts` (lines 5-25): Defines the inclusion criteria spanning `src/lib/**`, `src/core/**`, and `src/plugins/**`.
|
||||
- `src/lib/rateLimit.test.ts` (lines 15-60): Demonstrates test encapsulation regarding the Upstash Redis fallbacks.
|
||||
- `src/core/edition.test.ts` (lines 10-30): Confirms valid feature flag evaluations across local/demo builds.
|
||||
### Unit Tests
|
||||
Focused on validating standalone functions and state slice reducers without mounting React components.
|
||||
- **Example:** Validating the runtime edition feature flags.
|
||||
- *File:* `src/core/edition.test.ts`
|
||||
- **Example:** Validating marketplace token exchanges and rate limiting logic.
|
||||
- *Files:* `src/lib/marketplaceToken.test.ts`, `src/lib/rateLimit.test.ts`
|
||||
|
||||
### Integration Tests
|
||||
Focused on ensuring module interaction, such as the event bus properly interacting with state, or plugin loaders successfully resolving manifests.
|
||||
- **Example:** Testing local database repositories.
|
||||
- *File:* `src/lib/repository.test.ts`
|
||||
- **Example:** Validating cross-origin resource sharing (CORS) handlers for data engine streaming.
|
||||
- *File:* `src/lib/cors.test.ts`
|
||||
- **Example:** Verifying demo-admin bypass secrets.
|
||||
- *File:* `src/lib/demoAdmin.test.ts`
|
||||
|
||||
## Running Tests
|
||||
Run tests natively within the root directory utilizing `pnpm`:
|
||||
```bash
|
||||
# Execute standard test suite runs over all watched directories
|
||||
pnpm test
|
||||
# OR
|
||||
vitest run
|
||||
```
|
||||
|
||||
Execute the following commands from the root `worldwideview` directory:
|
||||
|
||||
- **Run all tests once:**
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
*(Alias for `vitest run`)*
|
||||
|
||||
- **Run tests in watch mode (for active development):**
|
||||
```bash
|
||||
npx vitest
|
||||
```
|
||||
|
||||
## Reference
|
||||
- **Coverage Scope:** The Vitest configuration primarily targets tests located inside `src/lib/**`, `src/core/**`, and `src/plugins/**`.
|
||||
- **Environment:** The test environment is configured as `jsdom` via `vite.config.ts` or `vitest.config.ts`, ensuring that DOM-specific API calls function outside of a real browser.
|
||||
@@ -15,6 +15,9 @@ pnpm install
|
||||
Write-Host "[*] Running initial setup (generating secrets)..."
|
||||
pnpm run setup
|
||||
|
||||
Write-Host "[*] Generating Prisma client..."
|
||||
npx prisma generate
|
||||
|
||||
# Check for the sibling Data Engine repository
|
||||
if (-not (Test-Path "../wwv-data-engine")) {
|
||||
Write-Host ""
|
||||
@@ -32,6 +35,21 @@ if (-not (Test-Path "../wwv-data-engine")) {
|
||||
Write-Host ""
|
||||
}
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "=====================================================================" -ForegroundColor Cyan
|
||||
Write-Host "[!] DATABASE SETUP REQUIRED" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
Write-Host "WorldWideView uses PostgreSQL. Choose one option:" -ForegroundColor White
|
||||
Write-Host ""
|
||||
Write-Host " Option A (Easiest): Run Prisma's built-in local database:" -ForegroundColor Green
|
||||
Write-Host " npx prisma dev" -ForegroundColor Yellow
|
||||
Write-Host " (Copy the DATABASE_URL it prints into your .env.local file)" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
Write-Host " Option B: Use your own PostgreSQL or Supabase instance:" -ForegroundColor Green
|
||||
Write-Host " Set DATABASE_URL in .env.local to your connection string" -ForegroundColor Gray
|
||||
Write-Host "=====================================================================" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
|
||||
Write-Host "[*] Starting local Next.js frontend server..."
|
||||
Write-Host " (To run the data engine backends concurrently, run: pnpm dev:all)"
|
||||
pnpm run dev
|
||||
+9
-6
@@ -2,16 +2,17 @@ import type { NextConfig } from "next";
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
output: "standalone",
|
||||
serverExternalPackages: ["better-sqlite3", "@prisma/adapter-better-sqlite3", "@prisma/client", "prisma"],
|
||||
transpilePackages: ["@worldwideview/wwv-plugin-sdk","resium",
|
||||
"react-player",
|
||||
"satellite.js"
|
||||
],
|
||||
serverExternalPackages: ["@prisma/client", "prisma"],
|
||||
transpilePackages: ["@worldwideview/wwv-plugin-sdk", "resium", "react-player", "satellite.js"],
|
||||
allowedDevOrigins: process.env.ALLOWED_DEV_ORIGIN ? [process.env.ALLOWED_DEV_ORIGIN] : undefined,
|
||||
experimental: {
|
||||
memoryBasedWorkersCount: true,
|
||||
cpus: 2,
|
||||
optimizePackageImports: ["lucide-react"],
|
||||
},
|
||||
outputFileTracingIncludes: {
|
||||
"/*": ["./scripts/**/*"],
|
||||
},
|
||||
typescript: {
|
||||
ignoreBuildErrors: true,
|
||||
},
|
||||
@@ -54,7 +55,9 @@ const nextConfig: NextConfig = {
|
||||
},
|
||||
|
||||
outputFileTracingExcludes: {
|
||||
"*": ["./public/cesium/**"],
|
||||
"*": [
|
||||
"./public/cesium/**"
|
||||
],
|
||||
},
|
||||
env: {
|
||||
CESIUM_BASE_URL: "/cesium",
|
||||
|
||||
+31
-22
@@ -1,7 +1,9 @@
|
||||
{
|
||||
"name": "worldwideview",
|
||||
"version": "1.19.0",
|
||||
"version": "2.1.6",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"packageManager": "[email protected]",
|
||||
"scripts": {
|
||||
"setup": "node scripts/setup.mjs",
|
||||
"test-worktree": "node scripts/test-worktree.mjs",
|
||||
@@ -9,39 +11,46 @@
|
||||
"dev": "next dev --webpack",
|
||||
"dev:all": "concurrently -n \"next,backends\" -c \"magenta,blue\" \"pnpm dev\" \"pnpm dev:backends\"",
|
||||
"dev:backends": "cd ../wwv-data-engine && pnpm dev",
|
||||
"predev": "npx prisma migrate deploy && node scripts/copy-cesium.mjs",
|
||||
"predev": "node scripts/boot-db.mjs && npx dotenv-cli -e .env.local -c -- npx prisma db push --accept-data-loss && npx prisma generate && node scripts/copy-cesium.mjs",
|
||||
"copy-cesium": "node scripts/copy-cesium.mjs",
|
||||
"prebuild": "node scripts/check-build-env.mjs",
|
||||
"build": "next build --webpack",
|
||||
"start": "next start",
|
||||
"test": "vitest run",
|
||||
"db:reset": "npx prisma migrate reset --force"
|
||||
"db:reset": "npx prisma migrate reset --force",
|
||||
"generate": "prisma generate"
|
||||
},
|
||||
"dependencies": {
|
||||
"@auth/prisma-adapter": "^2.11.1",
|
||||
"@prisma/adapter-better-sqlite3": "^7.5.0",
|
||||
"@prisma/client": "^7.5.0",
|
||||
"@sentry/nextjs": "^10.48.0",
|
||||
"@supabase/supabase-js": "^2.98.0",
|
||||
"@auth/prisma-adapter": "^2.11.2",
|
||||
"@auth/supabase-adapter": "^1.11.2",
|
||||
"@prisma/adapter-pg": "^7.8.0",
|
||||
"@prisma/client": "^7.8.0",
|
||||
"@prisma/client-runtime-utils": "7.8.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:*",
|
||||
"bcryptjs": "^3.0.3",
|
||||
"cesium": "^1.139.0",
|
||||
"cesium": "^1.141.0",
|
||||
"cheerio": "^1.2.0",
|
||||
"hls.js": "^1.6.15",
|
||||
"hls.js": "^1.6.16",
|
||||
"insecam-api": "^0.0.3",
|
||||
"jose": "^6.2.2",
|
||||
"jose": "^6.2.3",
|
||||
"lucide-react": "^0.576.0",
|
||||
"next": "16.2.3",
|
||||
"next": "16.2.6",
|
||||
"next-auth": "^5.0.0-beta.30",
|
||||
"prisma": "^7.5.0",
|
||||
"react": "19.2.3",
|
||||
"react-dom": "19.2.3",
|
||||
"pg": "^8.20.0",
|
||||
"prisma": "^7.8.0",
|
||||
"react": "19.2.6",
|
||||
"react-dom": "19.2.6",
|
||||
"react-player": "^3.4.0",
|
||||
"resium": "1.19.4",
|
||||
"resium": "1.21.0",
|
||||
"satellite.js": "^7.0.0",
|
||||
"stripe": "^22.1.1",
|
||||
"tslib": "^2.8.1",
|
||||
"ws": "^8.14.2",
|
||||
"zustand": "^5.0.11"
|
||||
"zustand": "^5.0.13"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@testing-library/dom": "^10.4.1",
|
||||
@@ -57,19 +66,19 @@
|
||||
"copy-webpack-plugin": "^14.0.0",
|
||||
"jsdom": "^28.1.0",
|
||||
"rollup-plugin-external-globals": "^0.13.0",
|
||||
"tsx": "^4.21.0",
|
||||
"typescript": "^5",
|
||||
"vite": "^8.0.8",
|
||||
"vitest": "^4.0.18"
|
||||
"vite": "^8.0.11",
|
||||
"vitest": "^4.1.5"
|
||||
},
|
||||
"pnpm": {
|
||||
"onlyBuiltDependencies": [
|
||||
"@prisma/engines",
|
||||
"better-sqlite3",
|
||||
"esbuild",
|
||||
"@sentry/cli",
|
||||
"prisma",
|
||||
"protobufjs",
|
||||
"sharp",
|
||||
"unrs-resolver"
|
||||
"esbuild"
|
||||
]
|
||||
}
|
||||
}
|
||||
Generated
+1089
-1737
File diff suppressed because it is too large.
Load diff
+14
-4
@@ -5,14 +5,24 @@ let dbUrl = process.env.DATABASE_URL;
|
||||
|
||||
if (!dbUrl) {
|
||||
try {
|
||||
const envPath = path.resolve(process.cwd(), ".env");
|
||||
if (fs.existsSync(envPath)) {
|
||||
const envContent = fs.readFileSync(envPath, "utf8");
|
||||
const match = envContent.match(/^DATABASE_URL=(.*)$/m);
|
||||
const envLocalPath = path.resolve(process.cwd(), ".env.local");
|
||||
if (fs.existsSync(envLocalPath)) {
|
||||
const envContent = fs.readFileSync(envLocalPath, "utf8");
|
||||
const match = envContent.match(/^DATABASE_URL=["']?(.*?)["']?$/m);
|
||||
if (match) {
|
||||
dbUrl = match[1].trim();
|
||||
}
|
||||
}
|
||||
if (!dbUrl) {
|
||||
const envPath = path.resolve(process.cwd(), ".env");
|
||||
if (fs.existsSync(envPath)) {
|
||||
const envContent = fs.readFileSync(envPath, "utf8");
|
||||
const match = envContent.match(/^DATABASE_URL=["']?(.*?)["']?$/m);
|
||||
if (match) {
|
||||
dbUrl = match[1].trim();
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch (e) {
|
||||
// Ignore
|
||||
}
|
||||
|
||||
@@ -0,0 +1,103 @@
|
||||
-- CreateTable
|
||||
CREATE TABLE "users" (
|
||||
"id" TEXT NOT NULL,
|
||||
"tenantId" TEXT,
|
||||
"email" TEXT NOT NULL,
|
||||
"name" TEXT NOT NULL,
|
||||
"hashedPassword" TEXT NOT NULL,
|
||||
"role" TEXT NOT NULL DEFAULT 'user',
|
||||
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
|
||||
CONSTRAINT "users_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
-- CreateTable
|
||||
CREATE TABLE "favorites" (
|
||||
"id" TEXT NOT NULL,
|
||||
"tenantId" TEXT,
|
||||
"entityId" TEXT NOT NULL,
|
||||
"pluginId" TEXT NOT NULL,
|
||||
"label" TEXT NOT NULL,
|
||||
"pluginName" TEXT NOT NULL,
|
||||
"lastSeen" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"userId" TEXT NOT NULL,
|
||||
|
||||
CONSTRAINT "favorites_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
-- CreateTable
|
||||
CREATE TABLE "installed_plugins" (
|
||||
"id" TEXT NOT NULL,
|
||||
"tenantId" TEXT,
|
||||
"pluginId" TEXT NOT NULL,
|
||||
"version" TEXT NOT NULL,
|
||||
"config" TEXT NOT NULL DEFAULT '{}',
|
||||
"enabled" BOOLEAN NOT NULL DEFAULT true,
|
||||
"installedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"updatedAt" TIMESTAMP(3) NOT NULL,
|
||||
|
||||
CONSTRAINT "installed_plugins_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
-- CreateTable
|
||||
CREATE TABLE "settings" (
|
||||
"id" TEXT NOT NULL,
|
||||
"tenantId" TEXT,
|
||||
"key" TEXT NOT NULL,
|
||||
"value" TEXT NOT NULL,
|
||||
|
||||
CONSTRAINT "settings_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
-- CreateTable
|
||||
CREATE TABLE "workspaces" (
|
||||
"id" TEXT NOT NULL,
|
||||
"name" TEXT NOT NULL,
|
||||
"subdomain" TEXT NOT NULL,
|
||||
"status" TEXT NOT NULL DEFAULT 'trialing',
|
||||
"plan" TEXT NOT NULL DEFAULT 'basic',
|
||||
"stripeCustomerId" TEXT,
|
||||
"stripeSubscriptionId" TEXT,
|
||||
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"updatedAt" TIMESTAMP(3) NOT NULL,
|
||||
|
||||
CONSTRAINT "workspaces_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
-- CreateTable
|
||||
CREATE TABLE "workspace_members" (
|
||||
"id" TEXT NOT NULL,
|
||||
"userId" TEXT NOT NULL,
|
||||
"workspaceId" TEXT NOT NULL,
|
||||
"role" TEXT NOT NULL DEFAULT 'member',
|
||||
"joinedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
|
||||
CONSTRAINT "workspace_members_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
-- CreateIndex
|
||||
CREATE UNIQUE INDEX "users_tenantId_email_key" ON "users"("tenantId", "email");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE UNIQUE INDEX "favorites_userId_entityId_key" ON "favorites"("userId", "entityId");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE UNIQUE INDEX "installed_plugins_tenantId_pluginId_key" ON "installed_plugins"("tenantId", "pluginId");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE UNIQUE INDEX "settings_tenantId_key_key" ON "settings"("tenantId", "key");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE UNIQUE INDEX "workspaces_subdomain_key" ON "workspaces"("subdomain");
|
||||
|
||||
-- CreateIndex
|
||||
CREATE UNIQUE INDEX "workspace_members_userId_workspaceId_key" ON "workspace_members"("userId", "workspaceId");
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "favorites" ADD CONSTRAINT "favorites_userId_fkey" FOREIGN KEY ("userId") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "workspace_members" ADD CONSTRAINT "workspace_members_userId_fkey" FOREIGN KEY ("userId") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
|
||||
-- AddForeignKey
|
||||
ALTER TABLE "workspace_members" ADD CONSTRAINT "workspace_members_workspaceId_fkey" FOREIGN KEY ("workspaceId") REFERENCES "workspaces"("id") ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
@@ -1,3 +1,3 @@
|
||||
# Please do not edit this file manually
|
||||
# It should be added in your version-control system (e.g., Git)
|
||||
provider = "sqlite"
|
||||
provider = "postgresql"
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,3 @@
|
||||
# Please do not edit this file manually
|
||||
# It should be added in your version-control system (e.g., Git)
|
||||
provider = "sqlite"
|
||||
+49
-8
@@ -1,29 +1,34 @@
|
||||
// Prisma schema — SQLite for local, PostgreSQL for cloud.
|
||||
// Connection URL configured in prisma.config.ts
|
||||
// Prisma schema — PostgreSQL for all environments.
|
||||
// Local dev: use `npx prisma dev` for a zero-install local PGLite instance.
|
||||
// Cloud/Production: set DATABASE_URL to your Supabase/Postgres connection string.
|
||||
|
||||
datasource db {
|
||||
provider = "sqlite"
|
||||
provider = "postgresql"
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client"
|
||||
provider = "prisma-client-js"
|
||||
output = "../src/generated/prisma"
|
||||
}
|
||||
|
||||
model User {
|
||||
id String @id @default(uuid())
|
||||
email String @unique
|
||||
tenantId String?
|
||||
email String
|
||||
name String
|
||||
hashedPassword String
|
||||
role String @default("user")
|
||||
createdAt DateTime @default(now())
|
||||
favorites Favorite[]
|
||||
memberships WorkspaceMember[]
|
||||
|
||||
@@unique([tenantId, email])
|
||||
@@map("users")
|
||||
}
|
||||
|
||||
model Favorite {
|
||||
id String @id @default(uuid())
|
||||
tenantId String?
|
||||
entityId String
|
||||
pluginId String
|
||||
label String
|
||||
@@ -58,19 +63,55 @@ model Favorite {
|
||||
|
||||
model InstalledPlugin {
|
||||
id String @id @default(uuid())
|
||||
pluginId String @unique
|
||||
tenantId String?
|
||||
pluginId String
|
||||
version String
|
||||
config String @default("{}")
|
||||
enabled Boolean @default(true)
|
||||
installedAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
|
||||
@@unique([tenantId, pluginId])
|
||||
@@map("installed_plugins")
|
||||
}
|
||||
|
||||
model Setting {
|
||||
key String @id
|
||||
value String
|
||||
id String @id @default(uuid())
|
||||
tenantId String?
|
||||
key String
|
||||
value String
|
||||
|
||||
@@unique([tenantId, key])
|
||||
@@map("settings")
|
||||
}
|
||||
|
||||
// NEW — Global workspace registry
|
||||
model Workspace {
|
||||
id String @id @default(uuid())
|
||||
name String
|
||||
subdomain String @unique
|
||||
status String @default("trialing")
|
||||
plan String @default("basic")
|
||||
stripeCustomerId String?
|
||||
stripeSubscriptionId String?
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
members WorkspaceMember[]
|
||||
|
||||
@@map("workspaces")
|
||||
}
|
||||
|
||||
// NEW — Links global users to workspaces with roles
|
||||
model WorkspaceMember {
|
||||
id String @id @default(uuid())
|
||||
userId String
|
||||
workspaceId String
|
||||
role String @default("member")
|
||||
joinedAt DateTime @default(now())
|
||||
|
||||
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
||||
workspace Workspace @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
|
||||
|
||||
@@unique([userId, workspaceId])
|
||||
@@map("workspace_members")
|
||||
}
|
||||
File mode changed.
@@ -0,0 +1,64 @@
|
||||
import { execSync } from 'child_process';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
|
||||
// Load environment variables manually since dotenv might not be installed globally
|
||||
const loadEnv = (file) => {
|
||||
try {
|
||||
if (fs.existsSync(file)) {
|
||||
const content = fs.readFileSync(file, 'utf8');
|
||||
content.split('\n').forEach(line => {
|
||||
const match = line.match(/^\s*([\w.-]+)\s*=\s*(.*)?\s*$/);
|
||||
if (match) {
|
||||
const key = match[1];
|
||||
let value = match[2] || '';
|
||||
// Remove quotes
|
||||
if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
|
||||
if (value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
|
||||
process.env[key] = value;
|
||||
}
|
||||
});
|
||||
}
|
||||
} catch (e) {
|
||||
// Ignore read errors
|
||||
}
|
||||
};
|
||||
|
||||
loadEnv('.env');
|
||||
loadEnv('.env.local');
|
||||
|
||||
const skipLocalDb = process.env.WWV_SKIP_LOCAL_DB === 'true' || process.env.WWV_SKIP_LOCAL_DB === '1';
|
||||
|
||||
if (skipLocalDb) {
|
||||
console.log('⏭️ Skipping local PostgreSQL startup (WWV_SKIP_LOCAL_DB is set).');
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
console.log('🚀 Checking local PostgreSQL database...');
|
||||
|
||||
try {
|
||||
// Check if docker is installed
|
||||
try {
|
||||
execSync('docker --version', { stdio: 'ignore' });
|
||||
} catch (e) {
|
||||
console.log('⚠️ Docker is not installed or not in PATH. Skipping local database startup.');
|
||||
console.log('💡 If you want to run a local database automatically, please install Docker Desktop.');
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Start the db service using docker compose
|
||||
console.log('📦 Starting PostgreSQL via Docker Compose...');
|
||||
execSync('docker compose up -d db', { stdio: 'inherit' });
|
||||
|
||||
// Wait a few seconds for postgres to be ready
|
||||
console.log('⏳ Waiting for PostgreSQL to be ready...');
|
||||
|
||||
// Simple sleep since we can't easily rely on pg_isready without pg client
|
||||
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 3000);
|
||||
|
||||
console.log('✅ Local PostgreSQL database is ready!');
|
||||
|
||||
} catch (error) {
|
||||
console.error('❌ Failed to start local database:', error.message);
|
||||
console.log('💡 You may need to start it manually or set WWV_SKIP_LOCAL_DB=true to use an external database.');
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
/**
|
||||
* Pre-build sanity check for build-time public env vars.
|
||||
*
|
||||
* Some NEXT_PUBLIC_* vars are inlined into the client bundle by Next.js at
|
||||
* build time, so they must be set when `next build` runs (not just at runtime).
|
||||
* Missing ones don't fail the build — most have library defaults — but they
|
||||
* surface as opaque runtime 401s / blank panes that are painful to diagnose.
|
||||
*
|
||||
* This script prints actionable warnings instead.
|
||||
*/
|
||||
|
||||
const checks = [
|
||||
{
|
||||
name: "NEXT_PUBLIC_CESIUM_ION_TOKEN",
|
||||
why: "Cesium ships a built-in default Ion token, but Cesium periodically revokes it. Without your own token, base imagery and world terrain may return 401 Unauthorized at runtime.",
|
||||
how: "Get a free token at https://ion.cesium.com and set NEXT_PUBLIC_CESIUM_ION_TOKEN before building (e.g. in .env).",
|
||||
},
|
||||
];
|
||||
|
||||
const missing = checks.filter(c => !process.env[c.name]);
|
||||
if (missing.length === 0) process.exit(0);
|
||||
|
||||
const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
|
||||
console.warn(yellow("\n⚠ Build-time env vars not set:"));
|
||||
for (const c of missing) {
|
||||
console.warn(yellow(`\n ${c.name}`));
|
||||
console.warn(` ${c.why}`);
|
||||
console.warn(` Fix: ${c.how}`);
|
||||
}
|
||||
console.warn(yellow("\nContinuing build — these are warnings, not errors.\n"));
|
||||
@@ -0,0 +1,23 @@
|
||||
import { prisma } from "../src/lib/db";
|
||||
|
||||
async function main() {
|
||||
const plugins = await prisma.installedPlugin.findMany();
|
||||
console.log("Installed plugins:");
|
||||
plugins.forEach((p) => console.log(` ${p.pluginId} | config: ${p.config.substring(0, 60)}`));
|
||||
|
||||
const geojson = plugins.find((p) => p.pluginId === "geojson");
|
||||
if (geojson) {
|
||||
await prisma.installedPlugin.delete({ where: { id: geojson.id } });
|
||||
console.log("\nDeleted orphaned 'geojson' record.");
|
||||
} else {
|
||||
console.log("\nNo orphaned 'geojson' record found.");
|
||||
}
|
||||
|
||||
const remaining = await prisma.installedPlugin.findMany();
|
||||
console.log("\nRemaining plugins:");
|
||||
remaining.forEach((p) => console.log(` ${p.pluginId}`));
|
||||
|
||||
await prisma.$disconnect();
|
||||
}
|
||||
|
||||
main().catch(console.error);
|
||||
@@ -0,0 +1,51 @@
|
||||
import https from 'https';
|
||||
import http from 'http';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
const targetPort = 3000;
|
||||
const listenPort = 3001;
|
||||
const certPath = path.join(process.cwd(), 'data', 'localhost.crt');
|
||||
const keyPath = path.join(process.cwd(), 'data', 'localhost.key');
|
||||
|
||||
if (!fs.existsSync(certPath) || !fs.existsSync(keyPath)) {
|
||||
console.error('[HTTPS Proxy] Certificates not found. Proxy will not start.');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const options = {
|
||||
key: fs.readFileSync(keyPath),
|
||||
cert: fs.readFileSync(certPath)
|
||||
};
|
||||
|
||||
const server = https.createServer(options, (req, res) => {
|
||||
const proxyReq = http.request({
|
||||
hostname: '127.0.0.1',
|
||||
port: targetPort,
|
||||
path: req.url,
|
||||
method: req.method,
|
||||
headers: {
|
||||
...req.headers,
|
||||
'x-forwarded-proto': 'https',
|
||||
'x-forwarded-port': String(listenPort)
|
||||
}
|
||||
}, (proxyRes) => {
|
||||
res.writeHead(proxyRes.statusCode || 500, proxyRes.headers);
|
||||
proxyRes.pipe(res, { end: true });
|
||||
});
|
||||
|
||||
proxyReq.on('error', (e) => {
|
||||
console.error(`[HTTPS Proxy] Error proxying request to ${req.url}:`, e.message);
|
||||
res.writeHead(502);
|
||||
res.end('Bad Gateway');
|
||||
});
|
||||
|
||||
req.pipe(proxyReq, { end: true });
|
||||
});
|
||||
|
||||
server.listen(listenPort, '0.0.0.0', () => {
|
||||
console.log(`[HTTPS Proxy] Secure bridge listening on https://0.0.0.0:${listenPort} (forwarding to http://127.0.0.1:${targetPort})`);
|
||||
});
|
||||
@@ -0,0 +1,39 @@
|
||||
import { prisma } from "../src/lib/db";
|
||||
import { hashSync } from "bcryptjs";
|
||||
|
||||
async function main() {
|
||||
const action = process.argv[2];
|
||||
|
||||
if (action === "list") {
|
||||
const users = await prisma.user.findMany();
|
||||
if (users.length === 0) {
|
||||
console.log("No users found — visit /setup to create one.");
|
||||
} else {
|
||||
users.forEach((u) =>
|
||||
console.log(` ${u.email} | ${u.name} | ${u.role} | ${u.createdAt}`)
|
||||
);
|
||||
}
|
||||
} else if (action === "reset") {
|
||||
const email = process.argv[3];
|
||||
const newPass = process.argv[4];
|
||||
if (!email || !newPass) {
|
||||
console.log("Usage: tsx scripts/manage-users.ts reset <email> <password>");
|
||||
return;
|
||||
}
|
||||
const hashed = hashSync(newPass, 12);
|
||||
await prisma.user.update({
|
||||
where: { email },
|
||||
data: { hashedPassword: hashed },
|
||||
});
|
||||
console.log(`Password reset for ${email}`);
|
||||
} else if (action === "delete-all") {
|
||||
await prisma.user.deleteMany();
|
||||
console.log("All users deleted — visit /setup to create a new admin.");
|
||||
} else {
|
||||
console.log("Usage: tsx scripts/manage-users.ts <list|reset|delete-all>");
|
||||
}
|
||||
|
||||
await prisma.$disconnect();
|
||||
}
|
||||
|
||||
main().catch(console.error);
|
||||
@@ -0,0 +1,125 @@
|
||||
/**
|
||||
* @deprecated This script uses better-sqlite3 directly to migrate data
|
||||
* from Supabase into the legacy data engine's SQLite database.
|
||||
* It is NOT part of the main application's database layer.
|
||||
* It will be removed once the data engine migration is complete.
|
||||
*/
|
||||
import { createClient } from "@supabase/supabase-js";
|
||||
import Database from "better-sqlite3";
|
||||
import path from "path";
|
||||
import fs from "fs";
|
||||
import dotenv from "dotenv";
|
||||
|
||||
// Load environment from .env.local
|
||||
const envPath = path.resolve(process.cwd(), ".env.local");
|
||||
if (fs.existsSync(envPath)) {
|
||||
dotenv.config({ path: envPath });
|
||||
} else {
|
||||
dotenv.config();
|
||||
}
|
||||
|
||||
const SUPABASE_URL = process.env.NEXT_PUBLIC_SUPABASE_URL!;
|
||||
const SUPABASE_KEY = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!;
|
||||
|
||||
if (!SUPABASE_URL || !SUPABASE_KEY) {
|
||||
console.error("Missing Supabase credentials in .env.local");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY);
|
||||
|
||||
// Connect to SQLite DB (respects DB_PATH, fallback to data engine location)
|
||||
const defaultDbPath = path.resolve(process.cwd(), "packages/wwv-data-engine/data/engine.db");
|
||||
const dbPath = process.env.DB_PATH || defaultDbPath;
|
||||
console.log(`Connecting to SQLite at ${dbPath}...`);
|
||||
|
||||
// Ensure DB directory exists
|
||||
const dbDir = path.dirname(dbPath);
|
||||
if (!fs.existsSync(dbDir)) {
|
||||
fs.mkdirSync(dbDir, { recursive: true });
|
||||
}
|
||||
|
||||
const db = new Database(dbPath);
|
||||
db.pragma('journal_mode = WAL');
|
||||
|
||||
// Ensure table exists (mirroring what we'll inject into Data Engine later)
|
||||
db.exec(`
|
||||
CREATE TABLE IF NOT EXISTS aviation_history (
|
||||
icao24 TEXT NOT NULL,
|
||||
ts INTEGER NOT NULL,
|
||||
lat REAL,
|
||||
lon REAL,
|
||||
alt REAL,
|
||||
hdg REAL,
|
||||
spd REAL,
|
||||
fetched_at INTEGER NOT NULL,
|
||||
PRIMARY KEY (icao24, ts)
|
||||
)
|
||||
`);
|
||||
|
||||
const insertHistory = db.prepare(`
|
||||
INSERT OR IGNORE INTO aviation_history (icao24, ts, lat, lon, alt, hdg, spd, fetched_at)
|
||||
VALUES (@icao24, @ts, @lat, @lon, @alt, @hdg, @spd, @fetched_at)
|
||||
`);
|
||||
|
||||
async function migrate() {
|
||||
console.log("Fetching existing aviation_history records from Supabase...");
|
||||
let offset = 0;
|
||||
const limit = 10000; // Chunk size
|
||||
let totalInserted = 0;
|
||||
|
||||
while (true) {
|
||||
const { data, error } = await supabase
|
||||
.from("aviation_history")
|
||||
.select("*")
|
||||
.range(offset, offset + limit - 1);
|
||||
|
||||
if (error) {
|
||||
console.error("Fetch error:", error);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (!data || data.length === 0) {
|
||||
console.log("No more records to fetch.");
|
||||
break;
|
||||
}
|
||||
|
||||
console.log(`Processing ${data.length} records (Offset: ${offset})...`);
|
||||
|
||||
// Batch insert to SQLite
|
||||
const insertMany = db.transaction((records) => {
|
||||
for (const r of records) {
|
||||
// Determine timestamp logic: Postgres is Timestamp so convert to epoch seconds
|
||||
const tsMs = new Date(r.timestamp).getTime();
|
||||
|
||||
insertHistory.run({
|
||||
icao24: r.icao24,
|
||||
ts: Math.floor(tsMs / 1000),
|
||||
lat: r.latitude,
|
||||
lon: r.longitude,
|
||||
alt: r.altitude,
|
||||
hdg: r.heading,
|
||||
spd: r.speed,
|
||||
fetched_at: Math.floor(Date.now() / 1000)
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
try {
|
||||
insertMany(data);
|
||||
totalInserted += data.length;
|
||||
} catch (err) {
|
||||
console.error("SQLite Insert Error:", err);
|
||||
}
|
||||
|
||||
if (data.length < limit) {
|
||||
break;
|
||||
}
|
||||
|
||||
offset += limit;
|
||||
}
|
||||
|
||||
console.log(`Migration complete! Successfully injected ~${totalInserted} records into SQLite.`);
|
||||
}
|
||||
|
||||
migrate();
|
||||
@@ -0,0 +1,97 @@
|
||||
import { DatabaseSync } from "node:sqlite";
|
||||
import { PrismaClient } from "../src/generated/prisma/index.js";
|
||||
import { PrismaPg } from "@prisma/adapter-pg";
|
||||
import pg from "pg";
|
||||
import path from "node:path";
|
||||
import fs from "node:fs";
|
||||
|
||||
async function migrate() {
|
||||
const targetPath = process.argv[2] || "data/wwv.db";
|
||||
const sqlitePath = path.resolve(process.cwd(), targetPath);
|
||||
|
||||
if (!fs.existsSync(sqlitePath)) {
|
||||
console.error(`❌ No legacy SQLite database found at ${targetPath}`);
|
||||
console.error("💡 Usage: node scripts/migrate-legacy.mjs [path-to-db]");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(`📂 Found legacy database at ${targetPath}. Initializing migration...`);
|
||||
|
||||
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
|
||||
const adapter = new PrismaPg(pool);
|
||||
const prisma = new PrismaClient({ adapter });
|
||||
const db = new DatabaseSync(sqlitePath);
|
||||
|
||||
try {
|
||||
// 1. Migrate Users
|
||||
console.log("👤 Migrating users...");
|
||||
const users = db.prepare("SELECT * FROM users").all();
|
||||
for (const user of users) {
|
||||
await prisma.user.upsert({
|
||||
where: { id: user.id },
|
||||
update: {},
|
||||
create: {
|
||||
id: user.id,
|
||||
email: user.email,
|
||||
name: user.name,
|
||||
hashedPassword: user.hashedPassword,
|
||||
role: user.role,
|
||||
createdAt: new Date(user.createdAt),
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// 2. Migrate Favorites
|
||||
console.log("⭐️ Migrating favorites...");
|
||||
const favorites = db.prepare("SELECT * FROM favorites").all();
|
||||
for (const fav of favorites) {
|
||||
await prisma.favorite.upsert({
|
||||
where: { id: fav.id },
|
||||
update: {},
|
||||
create: {
|
||||
id: fav.id,
|
||||
userId: fav.userId,
|
||||
entityId: fav.entityId,
|
||||
pluginId: fav.pluginId,
|
||||
label: fav.label,
|
||||
pluginName: fav.pluginName,
|
||||
lastSeen: new Date(fav.lastSeen),
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// 3. Migrate Settings
|
||||
console.log("⚙️ Migrating settings...");
|
||||
const settings = db.prepare("SELECT * FROM settings").all();
|
||||
for (const setting of settings) {
|
||||
const existing = await prisma.setting.findFirst({
|
||||
where: { key: setting.key, tenantId: setting.tenantId || null }
|
||||
});
|
||||
if (existing) {
|
||||
await prisma.setting.update({
|
||||
where: { id: existing.id },
|
||||
data: { value: setting.value }
|
||||
});
|
||||
} else {
|
||||
await prisma.setting.create({
|
||||
data: {
|
||||
id: setting.id || undefined, // Let Prisma generate if undefined
|
||||
tenantId: setting.tenantId || null,
|
||||
key: setting.key,
|
||||
value: setting.value,
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
console.log("✅ Migration successful! All data moved to PostgreSQL.");
|
||||
console.log("💡 You can now safely delete prisma/dev.db");
|
||||
|
||||
} catch (error) {
|
||||
console.error("❌ Migration failed:", error);
|
||||
} finally {
|
||||
await prisma.$disconnect();
|
||||
}
|
||||
}
|
||||
|
||||
migrate();
|
||||
@@ -12,13 +12,41 @@ if (!branchName) {
|
||||
}
|
||||
|
||||
const rootDir = process.cwd();
|
||||
const worktreeDirName = branchName.replace(/\//g, '-');
|
||||
const worktreePath = path.join(rootDir, '.worktrees', worktreeDirName);
|
||||
|
||||
// 2. Validate worktree exists
|
||||
// 2. Find worktree path dynamically
|
||||
let worktreePath = null;
|
||||
try {
|
||||
const output = execSync('git worktree list --porcelain', { encoding: 'utf8' });
|
||||
const blocks = output.trim().split(/\r?\n\r?\n/);
|
||||
|
||||
for (const block of blocks) {
|
||||
const lines = block.split(/\r?\n/);
|
||||
const wtPathLine = lines.find(l => l.startsWith('worktree '));
|
||||
const branchLine = lines.find(l => l.startsWith('branch '));
|
||||
|
||||
if (wtPathLine && branchLine) {
|
||||
const currentBranch = branchLine.substring('branch refs/heads/'.length);
|
||||
if (currentBranch === branchName) {
|
||||
worktreePath = wtPathLine.substring('worktree '.length);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch (err) {
|
||||
console.warn('\x1b[33mWarning: Failed to parse git worktree list.\x1b[0m');
|
||||
}
|
||||
|
||||
// Fallback to legacy behavior if not found via git
|
||||
if (!worktreePath) {
|
||||
const worktreeDirName = branchName.replace(/\//g, '-');
|
||||
worktreePath = path.join(rootDir, '.worktrees', worktreeDirName);
|
||||
}
|
||||
|
||||
// 3. Validate worktree exists
|
||||
if (!fs.existsSync(worktreePath)) {
|
||||
console.error(`\x1b[31mError: Worktree directory not found at ${worktreePath}\x1b[0m`);
|
||||
console.error(`Ensure you have created it using 'git worktree add .worktrees/${worktreeDirName} -b ${branchName}'`);
|
||||
console.error(`\x1b[31mError: Worktree directory not found for branch '${branchName}'\x1b[0m`);
|
||||
console.error(`Searched path: ${worktreePath}`);
|
||||
console.error(`Ensure you have created it using 'git worktree add <path> -b ${branchName}'`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
services:
|
||||
wwv:
|
||||
image: ghcr.io/silvertakana/worldwideview:latest
|
||||
pull_policy: always
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- wwv-data:/app/data
|
||||
env_file:
|
||||
- path: .env
|
||||
required: false
|
||||
environment:
|
||||
- "AUTH_SECRET=${AUTH_SECRET:-default_secret_for_local_dev}"
|
||||
- "WWV_DEMO_ADMIN_SECRET=${WWV_DEMO_ADMIN_SECRET:-}"
|
||||
- "WWV_BRIDGE_TOKEN=${WWV_BRIDGE_TOKEN:-}"
|
||||
- "DATABASE_URL=${DATABASE_URL:-postgresql://postgres:postgres@db:5432/worldwideview?schema=public}"
|
||||
restart: unless-stopped
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
|
||||
db:
|
||||
image: postgres:15-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: postgres
|
||||
POSTGRES_DB: worldwideview
|
||||
ports:
|
||||
- "5432:5432"
|
||||
volumes:
|
||||
- postgres-data:/var/lib/postgresql/data
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U postgres -d worldwideview"]
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 60s
|
||||
|
||||
volumes:
|
||||
wwv-data:
|
||||
postgres-data:
|
||||
+8
-21
@@ -20,25 +20,8 @@ try {
|
||||
}
|
||||
|
||||
# Generate docker-compose.yml
|
||||
Write-Host "[*] Creating docker-compose.yml..."
|
||||
|
||||
$dockerCompose = @(
|
||||
"services:"
|
||||
" wwv:"
|
||||
" image: ghcr.io/silvertakana/worldwideview:latest"
|
||||
" ports:"
|
||||
" - `"3000:3000`""
|
||||
" volumes:"
|
||||
" - wwv-data:/app/data"
|
||||
" env_file:"
|
||||
" - .env"
|
||||
" restart: unless-stopped"
|
||||
""
|
||||
"volumes:"
|
||||
" wwv-data:"
|
||||
)
|
||||
|
||||
$dockerCompose | Out-File -FilePath docker-compose.yml -Encoding utf8
|
||||
Write-Host "[*] Downloading docker-compose.yml..."
|
||||
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/silvertakana/worldwideview/main/self-host/docker-compose.yml" -OutFile docker-compose.yml
|
||||
|
||||
# Generate .env
|
||||
if (-Not (Test-Path .env)) {
|
||||
@@ -46,8 +29,12 @@ if (-Not (Test-Path .env)) {
|
||||
$bytes = New-Object Byte[] 32
|
||||
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
|
||||
$secret = -join ($bytes | ForEach-Object { $_.ToString("x2") })
|
||||
"AUTH_SECRET=$secret" | Out-File -FilePath .env -Encoding ascii
|
||||
"NEXT_PUBLIC_WWV_EDITION=local" | Out-File -FilePath .env -Encoding ascii -Append
|
||||
Write-Host "[*] Downloading .env template..."
|
||||
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/silvertakana/worldwideview/main/.env.example" -OutFile .env
|
||||
|
||||
$envContent = Get-Content .env -Raw
|
||||
$envContent = $envContent -replace "(?m)^AUTH_SECRET=.*", "AUTH_SECRET=$secret"
|
||||
$envContent | Out-File -FilePath .env -Encoding utf8
|
||||
} else {
|
||||
Write-Host "[Success] .env already exists, skipping generation."
|
||||
}
|
||||
|
||||
+9
-19
@@ -17,23 +17,9 @@ if ! docker compose version > /dev/null 2>&1; then
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 1. Generate docker-compose.yml
|
||||
echo "📦 Creating docker-compose.yml..."
|
||||
cat > docker-compose.yml << 'EOF'
|
||||
services:
|
||||
wwv:
|
||||
image: ghcr.io/silvertakana/worldwideview:latest
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- wwv-data:/app/data
|
||||
env_file:
|
||||
- .env
|
||||
restart: unless-stopped # ← Auto-starts on boot
|
||||
|
||||
volumes:
|
||||
wwv-data:
|
||||
EOF
|
||||
# 1. Download docker-compose.yml
|
||||
echo "📦 Downloading docker-compose.yml..."
|
||||
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/silvertakana/worldwideview/main/self-host/docker-compose.yml
|
||||
|
||||
# 2. Generate .env with a persistent secret
|
||||
if [ ! -f .env ]; then
|
||||
@@ -44,8 +30,12 @@ if [ ! -f .env ]; then
|
||||
else
|
||||
SECRET=$(head -c 32 /dev/urandom | xxd -p)
|
||||
fi
|
||||
echo "AUTH_SECRET=$SECRET" > .env
|
||||
echo "NEXT_PUBLIC_WWV_EDITION=local" >> .env
|
||||
echo "📥 Downloading .env template..."
|
||||
curl -fsSL -o .env https://raw.githubusercontent.com/silvertakana/worldwideview/main/.env.example
|
||||
|
||||
# Replace AUTH_SECRET= with the generated secret
|
||||
# (macOS sed requires an empty string backup extension, Linux does not. Perl is safer across platforms)
|
||||
perl -pi -e "s/^AUTH_SECRET=.*$/AUTH_SECRET=$SECRET/" .env
|
||||
else
|
||||
echo "✅ .env already exists, skipping generation."
|
||||
fi
|
||||
|
||||
@@ -20,25 +20,8 @@ try {
|
||||
}
|
||||
|
||||
# Generate docker-compose.yml
|
||||
Write-Host "[*] Creating docker-compose.yml..."
|
||||
|
||||
$dockerCompose = @(
|
||||
"services:"
|
||||
" wwv:"
|
||||
" image: ghcr.io/silvertakana/worldwideview:latest"
|
||||
" ports:"
|
||||
" - `"3000:3000`""
|
||||
" volumes:"
|
||||
" - wwv-data:/app/data"
|
||||
" env_file:"
|
||||
" - .env"
|
||||
" restart: unless-stopped"
|
||||
""
|
||||
"volumes:"
|
||||
" wwv-data:"
|
||||
)
|
||||
|
||||
$dockerCompose | Out-File -FilePath docker-compose.yml -Encoding utf8
|
||||
Write-Host "[*] Downloading docker-compose.yml..."
|
||||
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/silvertakana/worldwideview/main/self-host/docker-compose.yml" -OutFile docker-compose.yml
|
||||
|
||||
# Generate .env
|
||||
if (-Not (Test-Path .env)) {
|
||||
@@ -46,12 +29,19 @@ if (-Not (Test-Path .env)) {
|
||||
$bytes = New-Object Byte[] 32
|
||||
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
|
||||
$secret = -join ($bytes | ForEach-Object { $_.ToString("x2") })
|
||||
"AUTH_SECRET=$secret" | Out-File -FilePath .env -Encoding ascii
|
||||
"NEXT_PUBLIC_WWV_EDITION=local" | Out-File -FilePath .env -Encoding ascii -Append
|
||||
Write-Host "[*] Downloading .env template..."
|
||||
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/silvertakana/worldwideview/main/.env.example" -OutFile .env
|
||||
|
||||
$envContent = Get-Content .env -Raw
|
||||
$envContent = $envContent -replace "(?m)^AUTH_SECRET=.*", "AUTH_SECRET=$secret"
|
||||
$envContent | Out-File -FilePath .env -Encoding utf8
|
||||
} else {
|
||||
Write-Host "[Success] .env already exists, skipping generation."
|
||||
}
|
||||
|
||||
Write-Host "[*] Pulling latest image updates..."
|
||||
docker compose pull
|
||||
|
||||
Write-Host "[*] Starting Docker container..."
|
||||
docker compose up -d
|
||||
|
||||
|
||||
@@ -17,23 +17,9 @@ if ! docker compose version > /dev/null 2>&1; then
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 1. Generate docker-compose.yml
|
||||
echo "📦 Creating docker-compose.yml..."
|
||||
cat > docker-compose.yml << 'EOF'
|
||||
services:
|
||||
wwv:
|
||||
image: ghcr.io/silvertakana/worldwideview:latest
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- wwv-data:/app/data
|
||||
env_file:
|
||||
- .env
|
||||
restart: unless-stopped # ← Auto-starts on boot
|
||||
|
||||
volumes:
|
||||
wwv-data:
|
||||
EOF
|
||||
# 1. Download docker-compose.yml
|
||||
echo "📦 Downloading docker-compose.yml..."
|
||||
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/silvertakana/worldwideview/main/self-host/docker-compose.yml
|
||||
|
||||
# 2. Generate .env with a persistent secret
|
||||
if [ ! -f .env ]; then
|
||||
@@ -44,13 +30,20 @@ if [ ! -f .env ]; then
|
||||
else
|
||||
SECRET=$(head -c 32 /dev/urandom | xxd -p)
|
||||
fi
|
||||
echo "AUTH_SECRET=$SECRET" > .env
|
||||
echo "NEXT_PUBLIC_WWV_EDITION=local" >> .env
|
||||
echo "📥 Downloading .env template..."
|
||||
curl -fsSL -o .env https://raw.githubusercontent.com/silvertakana/worldwideview/main/.env.example
|
||||
|
||||
# Replace AUTH_SECRET= with the generated secret
|
||||
# (macOS sed requires an empty string backup extension, Linux does not. Perl is safer across platforms)
|
||||
perl -pi -e "s/^AUTH_SECRET=.*$/AUTH_SECRET=$SECRET/" .env
|
||||
else
|
||||
echo "✅ .env already exists, skipping generation."
|
||||
fi
|
||||
|
||||
# 3. Start it
|
||||
echo "📥 Pulling latest image updates..."
|
||||
docker compose pull
|
||||
|
||||
echo "🚀 Starting Docker container..."
|
||||
docker compose up -d
|
||||
|
||||
|
||||
@@ -31,6 +31,24 @@
|
||||
"sourceType": "github",
|
||||
"computedHash": "f91df0be8d0ac0f12c5402b5c53da12a31b284e5501dba027086bb12db879903"
|
||||
},
|
||||
"prisma-database-setup": {
|
||||
"source": "prisma/skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "prisma-database-setup/SKILL.md",
|
||||
"computedHash": "0d6f44ac34b1ed3f8ed2970ecf90483d0f658fd1d204458f62bfefa28f31b095"
|
||||
},
|
||||
"prisma-postgres": {
|
||||
"source": "prisma/skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "prisma-postgres/SKILL.md",
|
||||
"computedHash": "fd8f16f26e2cce1dd3e8e7916dcddbffddf295003eba86141f53e9d2d9d2bc0c"
|
||||
},
|
||||
"prisma-upgrade-v7": {
|
||||
"source": "prisma/skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "prisma-upgrade-v7/SKILL.md",
|
||||
"computedHash": "075d1fc3156d5593c3e9a559ebb07f82a2991db07125ff9df16ad90270f5c584"
|
||||
},
|
||||
"redis-best-practices": {
|
||||
"source": "mindrally/skills",
|
||||
"sourceType": "github",
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
import { stripe } from "@/lib/stripe/client";
|
||||
import { NextResponse } from "next/server";
|
||||
import { auth } from "@/lib/auth";
|
||||
|
||||
export async function POST(req: Request) {
|
||||
const session = await auth();
|
||||
if (!session?.user) return new NextResponse("Unauthorized", { status: 401 });
|
||||
|
||||
const { priceId } = await req.json();
|
||||
|
||||
const checkoutSession = await stripe.checkout.sessions.create({
|
||||
mode: "subscription",
|
||||
payment_method_types: ["card"],
|
||||
line_items: [{ price: priceId, quantity: 1 }],
|
||||
success_url: `${process.env.NEXT_PUBLIC_APP_URL}/settings?success=true`,
|
||||
cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/settings?canceled=true`,
|
||||
client_reference_id: session.user.id,
|
||||
});
|
||||
|
||||
return NextResponse.json({ url: checkoutSession.url });
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
import { stripe } from "@/lib/stripe/client";
|
||||
import { NextResponse } from "next/server";
|
||||
|
||||
export async function POST(req: Request) {
|
||||
const body = await req.text();
|
||||
const sig = req.headers.get("stripe-signature");
|
||||
|
||||
let event;
|
||||
|
||||
try {
|
||||
event = stripe.webhooks.constructEvent(
|
||||
body,
|
||||
sig!,
|
||||
process.env.STRIPE_WEBHOOK_SECRET!
|
||||
);
|
||||
} catch (err: any) {
|
||||
return new NextResponse(`Webhook Error: ${err.message}`, { status: 400 });
|
||||
}
|
||||
|
||||
if (event.type === "checkout.session.completed") {
|
||||
console.log("Subscription completed!");
|
||||
// Update user tier in DB, send license key via email
|
||||
}
|
||||
|
||||
return new NextResponse(null, { status: 200 });
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
import { fetchCaltransCameras } from "../caltrans/caltransFetcher";
|
||||
import type { CameraAdapter, CameraFeature } from "./types";
|
||||
|
||||
export const caltransAdapter: CameraAdapter = {
|
||||
id: "caltrans",
|
||||
displayName: "Caltrans (California)",
|
||||
region: "United States — California",
|
||||
fetch: async () => (await fetchCaltransCameras()) as CameraFeature[],
|
||||
};
|
||||
@@ -0,0 +1,35 @@
|
||||
import { fetchGdotCameras } from "../gdot/gdotFetcher";
|
||||
import type { CameraAdapter, CameraFeature } from "./types";
|
||||
|
||||
// GDOT's snapshot infrastructure (navigator-c2c.dot.ga.gov, vss5live.dot.ga.gov)
|
||||
// has been retired upstream as of 2026 — both hosts NXDOMAIN. The metadata
|
||||
// API still returns those URLs, so strip them so the client doesn't trigger
|
||||
// DNS errors on click. Drop these entries from the filter list once GDOT
|
||||
// publishes a working snapshot endpoint.
|
||||
const DEAD_STREAM_HOSTS = [
|
||||
"navigator-c2c.dot.ga.gov",
|
||||
"vss5live.dot.ga.gov",
|
||||
];
|
||||
|
||||
function isDeadHost(url: string | null | undefined): boolean {
|
||||
if (!url) return false;
|
||||
return DEAD_STREAM_HOSTS.some((h) => url.includes(h));
|
||||
}
|
||||
|
||||
export const gdotAdapter: CameraAdapter = {
|
||||
id: "gdot",
|
||||
displayName: "GDOT (Georgia)",
|
||||
region: "United States — Georgia",
|
||||
fetch: async () => {
|
||||
const features = (await fetchGdotCameras()) as CameraFeature[];
|
||||
return features.map((f) => {
|
||||
const p = f.properties;
|
||||
const stream = isDeadHost(p.stream) ? null : (p.stream ?? null);
|
||||
const hls = isDeadHost(p.hls) ? null : (p.hls ?? null);
|
||||
return {
|
||||
...f,
|
||||
properties: { ...p, stream, hls },
|
||||
};
|
||||
});
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,9 @@
|
||||
import { fetch511NyCameras } from "../ny511/ny511Fetcher";
|
||||
import type { CameraAdapter, CameraFeature } from "./types";
|
||||
|
||||
export const ny511Adapter: CameraAdapter = {
|
||||
id: "ny511",
|
||||
displayName: "511NY (New York State)",
|
||||
region: "United States — New York",
|
||||
fetch: async () => (await fetch511NyCameras()) as CameraFeature[],
|
||||
};
|
||||
@@ -0,0 +1,131 @@
|
||||
import type { CameraAdapter, CameraAdapterMeta, CameraFeature } from "./types";
|
||||
import { caltransAdapter } from "./caltrans";
|
||||
import { gdotAdapter } from "./gdot";
|
||||
import { tflAdapter } from "./tfl";
|
||||
import { ny511Adapter } from "./ny511";
|
||||
import { wsdotAdapter } from "./wsdot";
|
||||
|
||||
/**
|
||||
* All registered adapters. To add a new source, add an import + push the
|
||||
* adapter object here. No other file needs to change for the new source
|
||||
* to appear in `/api/camera/list`, `/api/camera/traffic?sources=...`, and
|
||||
* the client's source-picker UI.
|
||||
*/
|
||||
export const ALL_ADAPTERS: CameraAdapter[] = [
|
||||
caltransAdapter,
|
||||
gdotAdapter,
|
||||
tflAdapter,
|
||||
ny511Adapter,
|
||||
wsdotAdapter,
|
||||
];
|
||||
|
||||
const ADAPTERS_BY_ID: Map<string, CameraAdapter> = new Map(
|
||||
ALL_ADAPTERS.map((a) => [a.id, a]),
|
||||
);
|
||||
|
||||
const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
|
||||
|
||||
interface CacheEntry {
|
||||
data: CameraFeature[];
|
||||
expiry: number;
|
||||
fetchedAt: string;
|
||||
error?: string;
|
||||
}
|
||||
|
||||
const cache: Map<string, CacheEntry> = new Map();
|
||||
|
||||
export function getAdapter(id: string): CameraAdapter | undefined {
|
||||
return ADAPTERS_BY_ID.get(id);
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a `?sources=` query value into a list of adapter ids.
|
||||
* - empty / unset / "all" → all known adapter ids
|
||||
* - "none" → empty list (clients use this to short-circuit)
|
||||
* - comma-separated list → only the registered ones, unknown ids dropped
|
||||
*/
|
||||
export function resolveSources(raw: string | null): string[] {
|
||||
if (!raw || raw === "all") return ALL_ADAPTERS.map((a) => a.id);
|
||||
if (raw === "none") return [];
|
||||
const requested = raw.split(",").map((s) => s.trim()).filter(Boolean);
|
||||
return requested.filter((id) => ADAPTERS_BY_ID.has(id));
|
||||
}
|
||||
|
||||
function isKeyAvailable(adapter: CameraAdapter): boolean {
|
||||
if (!adapter.requiresKey) return true;
|
||||
return !!process.env[adapter.requiresKey.envVar];
|
||||
}
|
||||
|
||||
/** Return all adapter metadata for `/api/camera/list`. */
|
||||
export function getAdapterMetadata(): CameraAdapterMeta[] {
|
||||
return ALL_ADAPTERS.map((a) => {
|
||||
const c = cache.get(a.id);
|
||||
const keyOk = isKeyAvailable(a);
|
||||
return {
|
||||
id: a.id,
|
||||
displayName: a.displayName,
|
||||
region: a.region,
|
||||
requiresKey: a.requiresKey,
|
||||
healthy: keyOk && !!c && !c.error,
|
||||
lastFetchedAt: c?.fetchedAt ?? null,
|
||||
lastFeatureCount: c ? c.data.length : null,
|
||||
lastError: c?.error,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetch a single adapter's data with per-adapter caching.
|
||||
* Each adapter has its own TTL (default 24h, overridable via `cacheTtlMs`),
|
||||
* so fast sources can refresh hourly while slow ones stay daily.
|
||||
*
|
||||
* On error: returns the stale cached value if present, or rethrows. Either
|
||||
* way, the cache entry's `error` field is set so `/api/camera/list` can
|
||||
* report unhealthy adapters.
|
||||
*/
|
||||
export async function fetchAdapter(adapter: CameraAdapter): Promise<CameraFeature[]> {
|
||||
if (!isKeyAvailable(adapter)) {
|
||||
return [];
|
||||
}
|
||||
const now = Date.now();
|
||||
const ttl = adapter.cacheTtlMs ?? DEFAULT_TTL_MS;
|
||||
const c = cache.get(adapter.id);
|
||||
if (c && now < c.expiry && !c.error) {
|
||||
return c.data;
|
||||
}
|
||||
try {
|
||||
const data = await adapter.fetch();
|
||||
cache.set(adapter.id, {
|
||||
data,
|
||||
expiry: now + ttl,
|
||||
fetchedAt: new Date(now).toISOString(),
|
||||
});
|
||||
return data;
|
||||
} catch (e: any) {
|
||||
const errMsg = e?.message ?? String(e);
|
||||
if (c) {
|
||||
cache.set(adapter.id, { ...c, error: errMsg });
|
||||
return c.data;
|
||||
}
|
||||
cache.set(adapter.id, {
|
||||
data: [],
|
||||
expiry: now + 60_000, // short retry window on first failure
|
||||
fetchedAt: new Date(now).toISOString(),
|
||||
error: errMsg,
|
||||
});
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
|
||||
/** Fetch many adapters in parallel and merge the results. */
|
||||
export async function fetchManyAdapters(ids: string[]): Promise<CameraFeature[]> {
|
||||
const adapters = ids
|
||||
.map((id) => ADAPTERS_BY_ID.get(id))
|
||||
.filter((a): a is CameraAdapter => !!a);
|
||||
const results = await Promise.allSettled(adapters.map(fetchAdapter));
|
||||
const out: CameraFeature[] = [];
|
||||
for (const r of results) {
|
||||
if (r.status === "fulfilled") out.push(...r.value);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
import { fetchTflCameras } from "../tfl/tflFetcher";
|
||||
import type { CameraAdapter, CameraFeature } from "./types";
|
||||
|
||||
export const tflAdapter: CameraAdapter = {
|
||||
id: "tfl",
|
||||
displayName: "TfL JamCams (London)",
|
||||
region: "United Kingdom — London",
|
||||
fetch: async () => (await fetchTflCameras()) as CameraFeature[],
|
||||
};
|
||||
@@ -0,0 +1,97 @@
|
||||
/**
|
||||
* Public-camera adapter interface.
|
||||
*
|
||||
* Each upstream camera source (Caltrans, GDOT, TfL, 511NY, WSDOT, …)
|
||||
* implements `CameraAdapter`. The registry collects them; `/api/camera/traffic`
|
||||
* merges; `/api/camera/list` exposes their metadata for client-side source
|
||||
* discovery + selection UI.
|
||||
*
|
||||
* `CameraFeature` is the normalized record shape every adapter returns.
|
||||
* Replaces the legacy `GdotCameraFeature` alias which leaked the first
|
||||
* adapter's name into every other one.
|
||||
*/
|
||||
|
||||
export type StreamType = "image" | "hls" | "mp4" | "iframe" | null;
|
||||
|
||||
export interface CameraFeature {
|
||||
type: "Feature";
|
||||
geometry: {
|
||||
type: "Point";
|
||||
coordinates: [number, number]; // [lon, lat]
|
||||
};
|
||||
properties: {
|
||||
/** Stable identifier within source (used as React key on client). */
|
||||
id?: string;
|
||||
/**
|
||||
* Adapter id ("caltrans", "gdot", "ny511", ...). Plugins use this
|
||||
* for filtering and for routing clicks to the right player.
|
||||
*/
|
||||
source: string;
|
||||
/**
|
||||
* Direct snapshot/stream URL the client should render. May be null
|
||||
* when the upstream source provides location-only data or the
|
||||
* adapter has detected a dead host.
|
||||
*/
|
||||
stream: string | null;
|
||||
streamType?: StreamType;
|
||||
/** Optional HLS-specific URL when both image + HLS are available. */
|
||||
hls?: string | null;
|
||||
// Display + filter fields — adapters fill what they have.
|
||||
name?: string;
|
||||
country?: string;
|
||||
region?: string;
|
||||
city?: string;
|
||||
route?: string;
|
||||
direction?: string;
|
||||
location_description?: string;
|
||||
categories?: string[];
|
||||
/**
|
||||
* Adapter-specific extras (mile markers, county ids, etc.). Kept
|
||||
* under one key so the top-level shape stays predictable.
|
||||
*/
|
||||
extra?: Record<string, unknown>;
|
||||
};
|
||||
}
|
||||
|
||||
/** Metadata about an adapter, exposed via `/api/camera/list`. */
|
||||
export interface CameraAdapterMeta {
|
||||
/** Stable id used in `?sources=` and as the `properties.source` value. */
|
||||
id: string;
|
||||
/** Human-readable name for settings UI ("Caltrans (California)"). */
|
||||
displayName: string;
|
||||
/** Geographic scope, used for grouping in source-picker UIs. */
|
||||
region: string;
|
||||
/** True if the adapter requires an env var to function. */
|
||||
requiresKey?: {
|
||||
envVar: string;
|
||||
signupUrl: string;
|
||||
};
|
||||
/** True iff a successful fetch landed within the last cache window. */
|
||||
healthy: boolean;
|
||||
/** ISO timestamp of the last successful fetch, or null if never. */
|
||||
lastFetchedAt: string | null;
|
||||
/** Number of features returned by the most recent successful fetch. */
|
||||
lastFeatureCount: number | null;
|
||||
/** Brief error from the last fetch, if any. */
|
||||
lastError?: string;
|
||||
}
|
||||
|
||||
/** Adapter implementation contract. */
|
||||
export interface CameraAdapter {
|
||||
readonly id: string;
|
||||
readonly displayName: string;
|
||||
readonly region: string;
|
||||
readonly requiresKey?: { envVar: string; signupUrl: string };
|
||||
/** Default cache TTL for this adapter's feed. Defaults to 24h. */
|
||||
readonly cacheTtlMs?: number;
|
||||
/** Fetch the source's full feed and normalize to CameraFeature[]. */
|
||||
fetch(): Promise<CameraFeature[]>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Legacy alias — every existing fetcher imports this name. Kept as alias
|
||||
* to `CameraFeature` so old code keeps compiling while we migrate.
|
||||
*
|
||||
* @deprecated Use `CameraFeature` from `adapters/types` directly.
|
||||
*/
|
||||
export type GdotCameraFeatureLegacy = CameraFeature;
|
||||
@@ -0,0 +1,13 @@
|
||||
import { fetchWsdotCameras } from "../wsdot/wsdotFetcher";
|
||||
import type { CameraAdapter, CameraFeature } from "./types";
|
||||
|
||||
export const wsdotAdapter: CameraAdapter = {
|
||||
id: "wsdot",
|
||||
displayName: "WSDOT (Washington State)",
|
||||
region: "United States — Washington",
|
||||
requiresKey: {
|
||||
envVar: "WSDOT_API_KEY",
|
||||
signupUrl: "https://wsdot.wa.gov/traffic/api/",
|
||||
},
|
||||
fetch: async () => (await fetchWsdotCameras()) as CameraFeature[],
|
||||
};
|
||||
Loaded 100 of 156 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user