Compare commits
418
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
922b7acc03 | ||
|
|
dc83f97be4 | ||
|
|
7f7d7588f3 | ||
|
|
b9c6d193a4 | ||
|
|
062adaf9d3 | ||
|
|
1cf4074eb3 | ||
|
|
bc6f087efb | ||
|
|
8cb1756d6c | ||
|
|
851811eb35 | ||
|
|
f5802cf34a | ||
|
|
c9bb6efa43 | ||
|
|
67fcd7923e | ||
|
|
26568429bc | ||
|
|
f3720ff2c1 | ||
|
|
68716b9e56 | ||
|
|
c2d850a0d0 | ||
|
|
6d62ca5677 | ||
|
|
58aac77a0b | ||
|
|
0462ab1f88 | ||
|
|
60fca4d540 | ||
|
|
dba5d49448 | ||
|
|
1633c7bb7b | ||
|
|
7eda6c50a4 | ||
|
|
f2ae2a7de7 | ||
|
|
3210b3bd15 | ||
|
|
9fad051f75 | ||
|
|
a818822023 | ||
|
|
012184af30 | ||
|
|
c1f7ffb5b4 | ||
|
|
6816081644 | ||
|
|
433004598d | ||
|
|
02d8355a83 | ||
|
|
89010b2425 | ||
|
|
0ff1d23e4a | ||
|
|
fd29865e7a | ||
|
|
42564b537f | ||
|
|
598e00171c | ||
|
|
b849bb2b4d | ||
|
|
fc7dd02ee2 | ||
|
|
caf1638fdc | ||
|
|
ad3c7845a5 | ||
|
|
339bf6c0f3 | ||
|
|
16c82c9184 | ||
|
|
ad324a6592 | ||
|
|
0a51e198d7 | ||
|
|
1d6381182e | ||
|
|
beb295445f | ||
|
|
dd62116351 | ||
|
|
d675d91441 | ||
|
|
fb07195ec2 | ||
|
|
1838f1a5cd | ||
|
|
28e4e67043 | ||
|
|
594f85afb2 | ||
|
|
b29133fca0 | ||
|
|
ac0092c8a8 | ||
|
|
f0daefd53d | ||
|
|
94f8a47e0d | ||
|
|
161401a0af | ||
|
|
399b811c7e | ||
|
|
786e60865a | ||
|
|
ded2d587e4 | ||
|
|
b177c6987d | ||
|
|
b11125fd5f | ||
|
|
db1a9ad191 | ||
|
|
cfd8e4b7d0 | ||
|
|
a475a5a562 | ||
|
|
8f859f4559 | ||
|
|
8a594d28ea | ||
|
|
382ceed2f1 | ||
|
|
df072feea7 | ||
|
|
943ab91564 | ||
|
|
7a262c617c | ||
|
|
a69b1d9aac | ||
|
|
a1b3a71e6e | ||
|
|
338cde0813 | ||
|
|
b7311268f8 | ||
|
|
54078f351c | ||
|
|
a149be8560 | ||
|
|
10fdafbdb6 | ||
|
|
2280fc4d19 | ||
|
|
118106ff8f | ||
|
|
6a915cca62 | ||
|
|
42dadd0b40 | ||
|
|
583c0e57a6 | ||
|
|
ae14a30168 | ||
|
|
019b427442 | ||
|
|
04beadc0e2 | ||
|
|
cf67c5d96f | ||
|
|
bf7e9c4bee | ||
|
|
a1c4fed23b | ||
|
|
e6c7dcf295 | ||
|
|
9e44e91d81 | ||
|
|
c6cd515588 | ||
|
|
0f871729c0 | ||
|
|
e73f81d6fe | ||
|
|
f5235bf219 | ||
|
|
19f10d25df | ||
|
|
3ddd6ec150 | ||
|
|
e26aee6dd2 | ||
|
|
42f4701fda | ||
|
|
4c6978ea90 | ||
|
|
3c03b4e7a4 | ||
|
|
d2bdb0cee8 | ||
|
|
335b74a486 | ||
|
|
014a360d5d | ||
|
|
21adb9f2e8 | ||
|
|
b792dc0373 | ||
|
|
cbbc38ecc9 | ||
|
|
bbb231541b | ||
|
|
70fd3e1818 | ||
|
|
0ee8ae700c | ||
|
|
2c17b1e701 | ||
|
|
2ed8da0e1c | ||
|
|
9006064240 | ||
|
|
fe2cfa9dac | ||
|
|
84f3691c22 | ||
|
|
f9384b8244 | ||
|
|
d0ae85049f | ||
|
|
64815c114c | ||
|
|
e86fdf56d0 | ||
|
|
c25a1e6d58 | ||
|
|
f9c8bcff17 | ||
|
|
008e8cd01d | ||
|
|
1d1c7b270b | ||
|
|
63a5e5d8a1 | ||
|
|
39c1172b0b | ||
|
|
09ac165420 | ||
|
|
1daa8a6979 | ||
|
|
2c97f8e1e3 | ||
|
|
1fb830e962 | ||
|
|
5e542c3ca6 | ||
|
|
7e25fdfba2 | ||
|
|
c56987d6ce | ||
|
|
40888fb7dd | ||
|
|
1845a1ced9 | ||
|
|
e6305ca92f | ||
|
|
ebd9106cb8 | ||
|
|
51c8c28a08 | ||
|
|
9b7c41834c | ||
|
|
98c724a8c8 | ||
|
|
e6e0b8cbd4 | ||
|
|
98ab6372a1 | ||
|
|
772754e069 | ||
|
|
a254784c3a | ||
|
|
4889d7abea | ||
|
|
045eb03440 | ||
|
|
a773336d4b | ||
|
|
fcbe5f460e | ||
|
|
ab80dad42b | ||
|
|
69b66b44c9 | ||
|
|
e1d2c38687 | ||
|
|
1e21de55d7 | ||
|
|
c480bfdbd2 | ||
|
|
8dcb9f406d | ||
|
|
0625371ed4 | ||
|
|
45a213ac09 | ||
|
|
753071224e | ||
|
|
93504624ae | ||
|
|
ca17552d3d | ||
|
|
a9934f471e | ||
|
|
25e4280cad | ||
|
|
2e30a04ff1 | ||
|
|
6adb693f53 | ||
|
|
ef323f2c57 | ||
|
|
215dd9251c | ||
|
|
ce081c21fc | ||
|
|
0634712802 | ||
|
|
179dbdfad2 | ||
|
|
62d344baec | ||
|
|
6a3b143614 | ||
|
|
6cb7be0de1 | ||
|
|
1e59c9868e | ||
|
|
af1915805a | ||
|
|
d8205e6c3a | ||
|
|
e5b686c556 | ||
|
|
400a6abe74 | ||
|
|
6c8163dae3 | ||
|
|
e0ac5041c2 | ||
|
|
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 | ||
|
|
138ea6c721 | ||
|
|
dc10e8ad5c | ||
|
|
84f694f93b | ||
|
|
fa60f845c1 | ||
|
|
6e3a8ab625 | ||
|
|
739bffa05b | ||
|
|
9888f11a4b | ||
|
|
7354b414e7 | ||
|
|
196380c0af | ||
|
|
06e919639d | ||
|
|
f948f2aaab | ||
|
|
a5125dba7b | ||
|
|
21a6c618c8 | ||
|
|
48a17bf3ee | ||
|
|
2e4c074f77 | ||
|
|
e2108f5049 | ||
|
|
b76067c0bb | ||
|
|
04e614e1ed | ||
|
|
0d14a63246 | ||
|
|
781fe9e790 | ||
|
|
f0c2d81e18 | ||
|
|
f86b7d1e94 | ||
|
|
28704e6fe1 | ||
|
|
01e291a40e | ||
|
|
909e150b3d | ||
|
|
1fe3a77383 | ||
|
|
998f98851e | ||
|
|
9c51cdb8a2 | ||
|
|
d74ae694a4 | ||
|
|
ec4c89fe51 | ||
|
|
44e8ff9b70 | ||
|
|
cc90d3c2a3 | ||
|
|
0e6268bf72 | ||
|
|
764af74d14 | ||
|
|
29269c668a | ||
|
|
c60a0c9d56 | ||
|
|
05b2dce394 | ||
|
|
390518be0f | ||
|
|
e07bc60672 | ||
|
|
d75618f9aa | ||
|
|
aa34e1c49d | ||
|
|
2f618ce2cf | ||
|
|
085f4aa90c | ||
|
|
c1ddb91268 | ||
|
|
b3bc62ad8e | ||
|
|
32a4df4952 | ||
|
|
3ac36446bf | ||
|
|
ac95a64115 | ||
|
|
1d07698df7 | ||
|
|
583622f091 | ||
|
|
bfdbd0313d | ||
|
|
a70f93af0a | ||
|
|
26970e6adc | ||
|
|
63bc49949a | ||
|
|
ce45f2d4b6 | ||
|
|
bec1080cb8 | ||
|
|
ed4826484c | ||
|
|
77e6bf1d55 | ||
|
|
fa6413e953 | ||
|
|
53a9931e94 | ||
|
|
055ead345a | ||
|
|
89c247e913 | ||
|
|
df7df20c46 | ||
|
|
b738072e05 | ||
|
|
414ac3b194 | ||
|
|
f3b48ac302 | ||
|
|
bea39455e6 | ||
|
|
1a984251b6 | ||
|
|
67ca2abdbc | ||
|
|
b10e7d0a7f | ||
|
|
6be56b9966 | ||
|
|
4951a2d047 | ||
|
|
3fa1aeb80c | ||
|
|
c6b27a6079 | ||
|
|
c8c619210f | ||
|
|
01f923b806 | ||
|
|
487cb46f03 | ||
|
|
d05f93e610 | ||
|
|
701b7b3b23 | ||
|
|
1eff015bbb | ||
|
|
84129f1d9e | ||
|
|
60dbc5af66 | ||
|
|
8abc2ea2ef | ||
|
|
76243e08c0 | ||
|
|
57d6bbbe02 | ||
|
|
e1910011aa | ||
|
|
f81d9315e0 | ||
|
|
48cf43e68d | ||
|
|
f30a539ebf | ||
|
|
57a602eb60 | ||
|
|
a2c8dd2f55 | ||
|
|
f272a9a617 | ||
|
|
8fe71c637d | ||
|
|
aee5154eaf | ||
|
|
ae8c422c2f | ||
|
|
e61928b2a1 | ||
|
|
7749804365 | ||
|
|
c115058008 | ||
|
|
86c97ec191 | ||
|
|
b5b925dd06 | ||
|
|
7488677f7a | ||
|
|
14a8bf5369 | ||
|
|
96e4a1c591 | ||
|
|
6cb6dfd1d6 | ||
|
|
c31871b321 | ||
|
|
245118412f | ||
|
|
a75a4f0f9a | ||
|
|
f8664d8255 | ||
|
|
dad91079b2 | ||
|
|
273112424c | ||
|
|
9cc51f483a | ||
|
|
0adef65616 | ||
|
|
5b2b8a0a8d | ||
|
|
f33e7efb8d | ||
|
|
425dcbbc8e | ||
|
|
484104a2b0 | ||
|
|
7e34ab6da0 | ||
|
|
5b45d79790 | ||
|
|
7684d23398 | ||
|
|
a5610f0c8d | ||
|
|
4d178544e5 | ||
|
|
8a58f4a732 | ||
|
|
026eaae074 | ||
|
|
6515b43711 | ||
|
|
94a0ca4731 | ||
|
|
de60ed3ffe | ||
|
|
f5898b253a | ||
|
|
561a44fe77 | ||
|
|
b431fc526a | ||
|
|
3deefc9607 | ||
|
|
20363d509b | ||
|
|
134c3a5443 | ||
|
|
ab4cb2553a | ||
|
|
3bc3b3461f | ||
|
|
11a75b6458 | ||
|
|
62b8436353 | ||
|
|
875eda7ea2 | ||
|
|
82246daab0 | ||
|
|
7513ff9dfa | ||
|
|
96b032c2d0 | ||
|
|
de4f77d250 | ||
|
|
7c59ba4dc3 | ||
|
|
951e070466 | ||
|
|
adadce06b1 | ||
|
|
2341409bb4 | ||
|
|
7fee8e9fcf | ||
|
|
682c21296c | ||
|
|
aec6f20edc | ||
|
|
c89b55884f | ||
|
|
ded3ae9416 | ||
|
|
0808326967 | ||
|
|
889bd5aade | ||
|
|
a17aafa6f6 | ||
|
|
18da3a492c | ||
|
|
2fd3f84b2f | ||
|
|
68d350572f | ||
|
|
7660e707f7 | ||
|
|
f510c7de34 | ||
|
|
35e9e7d70d | ||
|
|
74f3793313 | ||
|
|
913e25ccac | ||
|
|
2ec151c68b | ||
|
|
cf49eef883 | ||
|
|
b56dacf04f | ||
|
|
22bb77492e | ||
|
|
ca1447f26a | ||
|
|
7f1bf00ef7 | ||
|
|
aeb9ddb96b | ||
|
|
3852e1175d | ||
|
|
1474e28de0 | ||
|
|
8a5ace61b2 | ||
|
|
932713e7a2 | ||
|
|
50228a43c8 | ||
|
|
326c69e92f | ||
|
|
e3225d4dab | ||
|
|
23d1538ea2 | ||
|
|
5f89715ee6 | ||
|
|
22f22ead37 | ||
|
|
5eff117972 | ||
|
|
b92e5b3683 | ||
|
|
b79f0f025d | ||
|
|
f40615ee21 | ||
|
|
222ae0950e | ||
|
|
afe89f8c0e | ||
|
|
867e495353 | ||
|
|
6263f7766b | ||
|
|
d65600786f | ||
|
|
a3a04d84c0 | ||
|
|
f295609ea2 | ||
|
|
80064996e9 | ||
|
|
973bef6386 | ||
|
|
4e2287aa5f | ||
|
|
17b8c7bb62 | ||
|
|
d10c68004a | ||
|
|
10830efca5 | ||
|
|
c3d9b2b536 | ||
|
|
3a04c64e79 | ||
|
|
eea424a826 | ||
|
|
4edcce2468 | ||
|
|
d54d9a480c | ||
|
|
b7d76b5e58 | ||
|
|
e83e45e8b9 | ||
|
|
86b7550c38 | ||
|
|
09b4b44c3e | ||
|
|
c6b26d20bc | ||
|
|
36ee84857b | ||
|
|
25b19ec635 | ||
|
|
614d3af796 | ||
|
|
bc05d93ce8 | ||
|
|
c0789f831c | ||
|
|
3be23a3ebc | ||
|
|
abd40ede1b | ||
|
|
aab5e39aa3 |
No files matched your search
@@ -0,0 +1,223 @@
|
||||
---
|
||||
name: garbage-collector
|
||||
description: Daily maintenance agent that reads pre-scanned gc-findings.json, then opens Tier A draft PRs (mechanical fixes like removing stale TODOs and console.logs) and Tier B GitHub Issues (architectural drift, oversized files, outdated deps). Runs headless via the garbage-collector.yml cron. Also invokable interactively as @garbage-collector for manual sweeps.
|
||||
tools: Read, Grep, Glob, Bash, Edit, Write
|
||||
model: haiku
|
||||
color: orange
|
||||
---
|
||||
|
||||
You are the WorldWideView Garbage Collector — a low-cost maintenance agent responsible for keeping the codebase clean between human-led development cycles.
|
||||
|
||||
## Step 1 — Read your charter
|
||||
|
||||
```bash
|
||||
cat .agents/rules/garbage-collection.md
|
||||
```
|
||||
|
||||
Internalize all guard rails, caps, and the never-touch list before taking any action.
|
||||
|
||||
## Step 2 — Read the findings
|
||||
|
||||
```bash
|
||||
cat gc-findings.json
|
||||
```
|
||||
|
||||
This was produced by `scripts/gc-scan.mjs` before you were invoked. You do **not** re-scan the codebase — you triage this list only.
|
||||
|
||||
If `gc-findings.json` does not exist or is empty, output "No findings to process." and stop.
|
||||
|
||||
## Step 3 — Check dry-run mode
|
||||
|
||||
```bash
|
||||
echo "${DRY_RUN:-false}"
|
||||
```
|
||||
|
||||
If `true`, jump to **Step 7 (Dry-run summary)** and skip all PR/Issue creation.
|
||||
|
||||
## Step 4 — Check for existing GC work (idempotency)
|
||||
|
||||
```bash
|
||||
# Open gc-bot PRs
|
||||
gh pr list --label gc-bot --state open --json number,title,headRefName,body
|
||||
|
||||
# Existing gc/* remote branches
|
||||
git branch -r --list 'origin/gc/*'
|
||||
|
||||
# Open gc-bot Issues
|
||||
gh issue list --label gc-bot --state open --json number,title
|
||||
```
|
||||
|
||||
Build a mental map of already-handled concerns. For each finding, skip it if an open PR or Issue already covers the same file + pattern.
|
||||
|
||||
## Step 5 — Tier A: Create draft PRs (max 3 per run)
|
||||
|
||||
Group related Tier A findings by `patternId` or `type`. Process the highest-value group first (most findings → most cleanup per PR).
|
||||
|
||||
For each group (up to 3 total):
|
||||
|
||||
### 5a — Create a branch
|
||||
|
||||
```bash
|
||||
SHA=$(git rev-parse --short HEAD)
|
||||
BRANCH="gc/<patternId>-${SHA}"
|
||||
git checkout -b "${BRANCH}"
|
||||
```
|
||||
|
||||
### 5b — Apply the mechanical fix
|
||||
|
||||
Follow these per-type rules:
|
||||
|
||||
**stale-todo (issueClosed: true)**
|
||||
Delete the entire comment line. Do not change surrounding code.
|
||||
|
||||
**stale-todo (issueClosed: false, age > 90d)**
|
||||
Add `# STALE(gc-bot):` prefix to the comment so the human sees it needs resolution. Do not delete — the human decides. This makes it Tier A-lite (no code risk, just marks it).
|
||||
|
||||
**anti-pattern: mdc-ref**
|
||||
Replace `.mdc` with `.md` in the file content. Check that the referenced file actually exists with `.md` extension before renaming.
|
||||
|
||||
**anti-pattern: console-log**
|
||||
Delete the `console.log(...)` line entirely. If it's the only statement in a block, delete the block too (only if the block has no other statements).
|
||||
|
||||
**anti-pattern: ts-ignore**
|
||||
Delete the `// @ts-ignore` line. If the next line now has a type error that is trivially fixable (e.g., adding a missing cast), fix it. If the type error is non-trivial, revert to Tier B (create an Issue instead).
|
||||
|
||||
**anti-pattern: ts-nocheck**
|
||||
Delete the `// @ts-nocheck` line. Check if the file still compiles cleanly with `npx tsc --noEmit --skipLibCheck` — if not, revert the deletion and file a Tier B Issue instead.
|
||||
|
||||
### 5c — Verify the change is safe
|
||||
|
||||
```bash
|
||||
# Count changed lines — must be ≤150
|
||||
git diff --stat
|
||||
|
||||
# Quick type check on changed files only
|
||||
npx tsc --noEmit --skipLibCheck 2>&1 | head -20
|
||||
```
|
||||
|
||||
If changed lines exceed 150 or type errors are introduced, `git checkout .` and file a Tier B Issue for this group instead.
|
||||
|
||||
### 5d — Commit and push
|
||||
|
||||
```bash
|
||||
git add -p # stage only the GC changes
|
||||
git commit -m "chore: [gc] remove <N> stale <type> findings"
|
||||
git push origin "${BRANCH}"
|
||||
```
|
||||
|
||||
### 5e — Open a draft PR
|
||||
|
||||
```bash
|
||||
gh pr create --draft --label gc-bot \
|
||||
--title "chore: [gc] <short description (≤60 chars)>" \
|
||||
--body "$(cat <<'EOF'
|
||||
## What changed
|
||||
<bullet list of files and what was removed/changed>
|
||||
|
||||
## Why
|
||||
Detector: `<patternId>` in `scripts/gc-scan.mjs`
|
||||
Rule violated: `<rule from garbage-collection.md>`
|
||||
Age / evidence: <age in days, or closed issue number>
|
||||
|
||||
## How to verify
|
||||
1. <step>
|
||||
2. Run `pnpm test` — all tests should still pass
|
||||
3. Run `pnpm build` — build must be clean
|
||||
|
||||
> This PR was opened automatically by the GC bot. Review before merging.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
Return to main: `git checkout main`
|
||||
|
||||
## Step 6 — Tier B: Create GitHub Issues (max 5 per run)
|
||||
|
||||
Group related Tier B findings into one Issue per `type` (e.g., all oversized files in one Issue).
|
||||
|
||||
```bash
|
||||
gh issue create --label gc-bot \
|
||||
--title "[gc] <type>: <short description>" \
|
||||
--body "$(cat <<'EOF'
|
||||
## Summary
|
||||
<what was detected and why it matters>
|
||||
|
||||
## Files / packages affected
|
||||
<file list with line counts or versions>
|
||||
|
||||
## Suggested action
|
||||
<concrete next step — e.g., "split this file", "upgrade this dep", "fix this rule reference">
|
||||
|
||||
## How to close this
|
||||
Resolve the issue and close this ticket manually.
|
||||
|
||||
> Filed automatically by the GC bot on <date>.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
## Step 7 — Dry-run summary
|
||||
|
||||
Find or create the tracking Issue:
|
||||
|
||||
```bash
|
||||
gh issue list --label gc-bot --state open --search "[gc-bot] Daily Scan Reports" --json number,title
|
||||
```
|
||||
|
||||
If it does not exist:
|
||||
```bash
|
||||
gh issue create --label gc-bot \
|
||||
--title "[gc-bot] Daily Scan Reports" \
|
||||
--body "This issue collects daily dry-run scan summaries. Enable normal mode by setting DRY_RUN=false in the workflow."
|
||||
```
|
||||
|
||||
Then post a comment:
|
||||
```bash
|
||||
gh issue comment <number> --body "$(cat <<'EOF'
|
||||
## GC Dry-run Report — <date>
|
||||
|
||||
| Tier | Count | Types |
|
||||
|---|---|---|
|
||||
| A (would fix) | <n> | <comma-separated types> |
|
||||
| B (would file) | <n> | <comma-separated types> |
|
||||
|
||||
### Tier A findings
|
||||
<table: file | line | type | description>
|
||||
|
||||
### Tier B findings
|
||||
<table: file/package | type | description>
|
||||
|
||||
No PRs or Issues were created (dry-run mode).
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
## Step 8 — Output summary
|
||||
|
||||
Print a clean markdown summary:
|
||||
|
||||
```
|
||||
## GC Run Complete
|
||||
|
||||
### PRs opened (<n>/3)
|
||||
- #<number>: <title> (<branch>)
|
||||
|
||||
### Issues opened (<n>/5)
|
||||
- #<number>: <title>
|
||||
|
||||
### Skipped (already handled)
|
||||
- <n> findings skipped — covered by existing open work
|
||||
|
||||
### Not actioned
|
||||
- <n> Tier B findings below cap — will appear in next run
|
||||
```
|
||||
|
||||
If nothing was created: "No new findings requiring action."
|
||||
|
||||
## Important invariants
|
||||
|
||||
- Never touch the never-touch list in the charter.
|
||||
- Never create a PR with more than 150 changed lines.
|
||||
- Never mark a PR as ready-for-review.
|
||||
- Never push directly to `main`.
|
||||
- If a Tier A fix risks introducing a regression and you cannot verify it is safe, file a Tier B Issue instead — safety always beats throughput.
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
description: Strict guidelines for rendering geospatial entities, handling 3D terrain clipping, and applying dynamic animation properties against Cesium's runtime engine.
|
||||
paths:
|
||||
- "src/core/globe/**/*"
|
||||
- "src/plugins/**/*"
|
||||
- "packages/wwv-plugin-*/src/**/*"
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
## Sizing Conventions
|
||||
|
||||
| Entity type | Knob | Default | Typical band | Source |
|
||||
|-------------|--------------|------------------------------------|------------------|--------|
|
||||
| `point` | `size` | `8` desktop / `12` mobile | 5–12 | `src/core/globe/primitiveOps.ts` (`defaultPointSize`) |
|
||||
| `billboard` | `iconScale` | `0.7` (`DEFAULT_BILLBOARD_SCALE`) | 0.6–0.9 | `src/core/globe/primitiveOps.ts` (`DEFAULT_BILLBOARD_SCALE`) |
|
||||
| `model` | `modelScale` | `1.0` + `modelMinPixelSize` | varies per asset | `src/core/globe/ModelManager.ts`, `src/core/globe/hooks/useModelRendering.ts` |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Cross-plugin parity rule.** If your plugin renders alongside maritime / aviation / military-aviation on the globe, **leave `iconScale` unset** (or pick a value inside 0.6–0.9). A value below 0.5 will look visibly broken next to peer plugins. A value above 1.0 will dominate the globe.
|
||||
|
||||
> [!CAUTION]
|
||||
> **Silent-ignore footgun.** `size` is a `PointPrimitive` property. If you set `size` on a `billboard` entity it is **silently dropped** — Cesium does not error and the billboard simply renders at `DEFAULT_BILLBOARD_SCALE`. When converting a point plugin to a billboard plugin, replace `size: N` with `iconScale: ~N/16` (the canvas base is `getBaseSize() = 48px` desktop) — do not delete it and do not translate it literally as `iconScale: N/10`. This footgun has shipped at least once (see commit history on `local-plugins/wwv-plugin-satellite`).
|
||||
|
||||
> [!NOTE]
|
||||
> **Backdrop stack.** `createSvgIconUrl` (in the SDK) already wraps the icon in a 44×44 SVG with a dark backdrop circle. `src/core/globe/iconUpscaler.ts` then redraws onto a 48px canvas with **another** backdrop circle (`DEFAULT_BG = "rgba(15, 23, 42, 0.55)"`). Pass `background: false` to `createSvgIconUrl` when you want only the host's circle. Don't add a third backdrop in your own SVG.
|
||||
|
||||
## Performance Culling
|
||||
|
||||
> [!TIP]
|
||||
> 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,244 @@
|
||||
---
|
||||
description: Cloud edition implementation details, PostgreSQL Row-Level Security (RLS) isolation, cross-subdomain auth, and cryptographic license keys.
|
||||
paths:
|
||||
- "src/lib/auth*"
|
||||
- "src/app/api/auth/**/*"
|
||||
- "src/core/auth.ts"
|
||||
- "src/core/storage.ts"
|
||||
- "src/core/tenant.ts"
|
||||
---
|
||||
|
||||
> **SUPERSEDED by ADR-003** (`docs/architecture/decisions/adr-0003-shared-identity-and-ecosystem-auth-host.md`).
|
||||
> The auth host is `worldwideview.dev` (worldwideview-web repo), not `app.worldwideview.dev`. Read ADR-003 first.
|
||||
|
||||
# WorldWideView — Cloud & Auth Architecture
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
> **This file contains the master plan and advanced implementation details for the future Cloud edition.**
|
||||
> It covers single-container multi-tenancy, PostgreSQL Row-Level Security (RLS) isolation, cross-subdomain auth, and cryptographic license keys. It is intended for AI reference when building multi-tenant or auth-related features.
|
||||
|
||||
---
|
||||
|
||||
## Auth Strategy
|
||||
|
||||
> [!WARNING]
|
||||
> **This section is superseded by [ADR-003](../../docs/architecture/decisions/adr-0003-shared-identity-and-ecosystem-auth-host.md) (2026-05-22).**
|
||||
> The decisions below describing `app.worldwideview.dev` as the auth owner and NextAuth as the ecosystem IdP are no longer current. The new architecture is:
|
||||
> - **`worldwideview.dev`** (the `worldwideview-web` repo) owns all login, signup, and account management UI
|
||||
> - **Supabase Auth** (single shared project) is the identity provider for all products
|
||||
> - Session cookies are scoped to `.worldwideview.dev` and shared across all subdomains
|
||||
> - The Marketplace never owns auth UI and never redirects to `app.worldwideview.dev`
|
||||
>
|
||||
> The multi-tenant RLS, tier matrix, license key, and CI/CD sections below remain valid.
|
||||
|
||||
**Auth.js (NextAuth)** is the single auth API across all editions. `app.worldwideview.dev` owns **all auth UI** — login, registration, password reset. No other subdomain ever shows a login or registration form.
|
||||
|
||||
```typescript
|
||||
// src/lib/auth.ts
|
||||
const providers = isCloud
|
||||
? [SupabaseProvider({ /* delegates to Supabase Auth (GoTrue) */ })]
|
||||
: [Credentials({ /* local bcrypt + PostgreSQL */ })];
|
||||
|
||||
export const { auth, signIn, signOut } = NextAuth({ providers });
|
||||
```
|
||||
|
||||
Application code is **identical** across editions — always calls `auth()`, `signIn()`, `signOut()`.
|
||||
|
||||
**One account for the entire ecosystem:**
|
||||
- Cloud instance (`[user].app.worldwideview.dev`)
|
||||
- Marketplace (browse, install, publish) — via SSO redirect
|
||||
- Local instance Bridge API connection
|
||||
|
||||
**Marketplace never owns auth UI** — it redirects to `app.worldwideview.dev/login?redirect_to=marketplace...` for all sign-in.
|
||||
|
||||
---
|
||||
|
||||
## Decentralized Plugin Authentication (Token Exchange)
|
||||
|
||||
For cross-domain plugin communication (Local App connecting to Marketplace or Data Engines), WWV uses an **Asymmetric JWT Token Exchange (PKCE)** model.
|
||||
- **PKCE Flow**: The Local App uses standard OAuth 2.0 PKCE to exchange a `code` for a long-lived API key from the Marketplace.
|
||||
- **Token Exchange**: The Local App exchanges its long-lived API key for a short-lived, audience-bound JWT before connecting to a decentralized Data Engine.
|
||||
- **WebSocket First-Message Auth**: Data Engines enforce a "First-Message Auth" pattern over WebSockets. The client MUST immediately send a `{ type: "auth", v: 1, token: "..." }` message upon opening the connection to prevent SSRF vulnerabilities and credential leakage.
|
||||
|
||||
---
|
||||
|
||||
## Registration & Auto-Provisioning
|
||||
|
||||
Registration: `app.worldwideview.dev/register`
|
||||
|
||||
```
|
||||
1. User fills: email, password, username (= subdomain)
|
||||
2. Account created (Supabase Auth)
|
||||
3. Tenant row inserted instantly → [username].app.worldwideview.dev is live
|
||||
4. User lands on their instance → Setup Wizard (Cesium token)
|
||||
```
|
||||
|
||||
**Subdomain validation:** alphanumeric + hyphens, min 3 chars, not already taken.
|
||||
**Reserved names:** `www`, `app`, `api`, `demo`, `marketplace`, `docs`, `status`, `admin`, `cdn`, `blog`, `changelog`
|
||||
|
||||
"Provisioning" is just inserting a database row — no container to spin up (multi-tenant shared app).
|
||||
|
||||
---
|
||||
|
||||
## Multi-Tenant Architecture
|
||||
|
||||
**One Docker container, RLS isolation.** All cloud tenants share one Next.js deployment. Data isolation enforced at the **PostgreSQL database level** via Row-Level Security:
|
||||
|
||||
```
|
||||
nginx (wildcard *.app.worldwideview.dev)
|
||||
→ reads subdomain → passes X-Tenant-ID header
|
||||
→ single WWV Docker container (Next.js)
|
||||
→ middleware reads X-Tenant-ID
|
||||
→ sets app.tenant_id in DB connection
|
||||
→ RLS scopes ALL queries to that tenant
|
||||
```
|
||||
|
||||
```sql
|
||||
ALTER TABLE installed_plugins ENABLE ROW LEVEL SECURITY;
|
||||
CREATE POLICY tenant_isolation ON installed_plugins
|
||||
USING (tenant_id = current_setting('app.tenant_id')::uuid);
|
||||
```
|
||||
|
||||
PostgreSQL **physically refuses** to return other tenants' rows — even application bugs cannot leak data.
|
||||
|
||||
> Schema-per-tenant (stronger isolation) can be offered later for enterprise. The `tenant_id` design makes migration straightforward.
|
||||
|
||||
### Security Analysis
|
||||
|
||||
| Concern | Risk | Mitigation |
|
||||
|---|---|---|
|
||||
| Data bleed between tenants | 🔴 Critical | RLS enforced at PostgreSQL level |
|
||||
| One tenant crashes the app | 🟡 Medium | Next.js request isolation. Rate limit per tenant at nginx |
|
||||
| One tenant hammers CPU | 🟡 Medium | Rate limiting at nginx (req/min per subdomain) |
|
||||
| Plugin code between tenants | 🟢 Low | Plugins run in the user's **browser**, not the server |
|
||||
| Server crash from users | 🟢 Low | Users can't run arbitrary server code. Rate limits handle abuse |
|
||||
|
||||
---
|
||||
|
||||
## Storage & Database
|
||||
|
||||
| Feature | Local | Cloud |
|
||||
|---|---|---|
|
||||
| **Database queries** | Prisma → PostgreSQL | Prisma → PostgreSQL (Supabase) |
|
||||
| **Auth** | None (single owner) | Supabase Auth (GoTrue) |
|
||||
| **File storage** | Local filesystem (`data/`) | Supabase Storage |
|
||||
| **Storage limit** | ∞ (your disk) | Quota enforced per tier |
|
||||
|
||||
**Prisma is write-once, deploy-anywhere** — the same queries and schema work on both databases. `DATABASE_URL` in `.env` is the only difference.
|
||||
|
||||
---
|
||||
|
||||
## Tier Matrix
|
||||
|
||||
| Deployment | `NEXT_PUBLIC_WWV_EDITION` | License Key | Users | Storage |
|
||||
|---|---|---|---|---|
|
||||
| **Demo** | `demo` | none | ∞ (anonymous, read-only) | N/A |
|
||||
| Local Free | `local` | none | 1 (owner) | ∞ |
|
||||
| Local Pro | `local` | Pro key | 1 (owner) | ∞ |
|
||||
| Local Team | `local` | Team key | Unlimited | ∞ |
|
||||
| Cloud Free | `cloud` | none | 3 | 500 MB |
|
||||
| Cloud Pro | `cloud` | Pro key | 20 | 5 GB |
|
||||
| Cloud Enterprise | `cloud` | Enterprise key | Unlimited | 50 GB+ |
|
||||
|
||||
### Cryptographic License Keys
|
||||
|
||||
Paid features gated by **RSA-signed JWTs** — users cannot forge them by flipping flags:
|
||||
|
||||
```typescript
|
||||
// Marketplace signs (PRIVATE key — only you have this):
|
||||
const licenseKey = jwt.sign(
|
||||
{ tier: "pro", exp: "2027-01-01", org: "acme-corp" },
|
||||
PRIVATE_KEY, { algorithm: "RS256" }
|
||||
);
|
||||
|
||||
// WWV verifies (PUBLIC key — hardcoded in codebase):
|
||||
const license = jwt.verify(process.env.WWV_LICENSE_KEY, PUBLIC_KEY);
|
||||
// license.tier = "free" | "pro" | "team"
|
||||
```
|
||||
|
||||
### Storage Quota (Cloud Only)
|
||||
|
||||
- **Counts:** Imported GeoJSON, plugin data history, uploaded assets
|
||||
- **NOT counted:** Built-in plugin real-time data (transient)
|
||||
- **Quota exceeded:** Upgrade prompt, reject new imports, allow read access
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Local `.env`
|
||||
```env
|
||||
NEXT_PUBLIC_WWV_EDITION=local
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/wwv?schema=public
|
||||
```
|
||||
|
||||
### Cloud `.env`
|
||||
```env
|
||||
NEXT_PUBLIC_WWV_EDITION=cloud
|
||||
DATABASE_URL=postgresql://...
|
||||
NEXT_PUBLIC_SUPABASE_URL=https://[project].supabase.co
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
|
||||
SUPABASE_SERVICE_ROLE_KEY=eyJ...
|
||||
WWV_TENANT_MODE=rls
|
||||
WWV_STORAGE_PROVIDER=supabase
|
||||
```
|
||||
|
||||
### Demo `.env`
|
||||
```env
|
||||
NEXT_PUBLIC_WWV_EDITION=demo
|
||||
DATABASE_URL=postgresql://...
|
||||
```
|
||||
|
||||
`.env` is **infrastructure only** — things the operator sets once. Everything user-configurable lives in the `settings` DB table.
|
||||
|
||||
---
|
||||
|
||||
## Edition Adapters
|
||||
|
||||
Three thin files are all that differs between editions — everything else is edition-unaware:
|
||||
|
||||
| Adapter | Local | Cloud | Demo |
|
||||
|---|---|---|---|
|
||||
| `src/core/auth.ts` | Auth.js `Credentials` (bcrypt + PostgreSQL) | Auth.js `@auth/supabase-adapter` | Disabled |
|
||||
| `src/core/storage.ts` | `fs.writeFile()` to `data/` | Supabase Storage SDK | Read-only |
|
||||
| `src/core/tenant.ts` | No-op (single tenant) | Sets `app.tenant_id` for RLS | No-op |
|
||||
|
||||
---
|
||||
|
||||
## Bot Prevention (Layered)
|
||||
|
||||
| Layer | What | Cost |
|
||||
|---|---|---|
|
||||
| **Email verification** | Supabase Auth built-in | Free |
|
||||
| **Rate limiting** | 3 signups per IP per hour (nginx) | Free |
|
||||
| **Cloudflare Turnstile** | Invisible CAPTCHA on signup | Free |
|
||||
| **Cloudflare Bot Fight Mode** | Auto-enabled on free tier | Free |
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
```
|
||||
Push to silvertakana/worldwideview
|
||||
→ GitHub Actions: build Docker image
|
||||
→ Push to ghcr.io/silvertakana/worldwideview:latest
|
||||
→ Coolify webhook triggers
|
||||
→ Rolling restart (zero downtime)
|
||||
```
|
||||
|
||||
### `worldwideview-cloud/docker-compose.yml` (concept)
|
||||
```yaml
|
||||
services:
|
||||
wwv-cloud:
|
||||
image: ghcr.io/silvertakana/worldwideview:latest
|
||||
environment:
|
||||
NEXT_PUBLIC_WWV_EDITION: cloud
|
||||
DATABASE_URL: ${SUPABASE_PG_URL}
|
||||
SUPABASE_URL: ${SUPABASE_URL}
|
||||
SUPABASE_ANON_KEY: ${SUPABASE_ANON_KEY}
|
||||
labels:
|
||||
- "traefik.http.routers.wwv.rule=HostRegexp(`{user:[a-z0-9-]+}.app.worldwideview.dev`)"
|
||||
```
|
||||
|
||||
The cloud repo (`worldwideview-cloud`) holds **no application logic** — it is purely a thin deployment configuration layer that pulls versioned Docker images.
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
description: Architecture rules and dependency management guidelines for wwv-data-engine seeders, pnpm workspace dependency loading, and WebSocket payload contracts.
|
||||
paths:
|
||||
- "packages/**/*"
|
||||
- "local-seeders/**/*"
|
||||
- "docker-compose.yml"
|
||||
---
|
||||
|
||||
# Data Engine V2 Architecture & Dependency Loading
|
||||
|
||||
## 1. Engine Versions: V2 vs Legacy
|
||||
The current and only active engine is **`wwv-data-engine-v2`**.
|
||||
- **Legacy Engine**: Previously, data sources ran as isolated, standalone microservices running their own Node environments.
|
||||
- **V2 Engine**: Acts as a unified **"Host Environment" runner**. It is a single Node.js process that dynamically downloads and executes multiple independent seeder bundles (both public community seeders and private seeders).
|
||||
|
||||
## 2. Deployment Architecture
|
||||
- **Single Docker Image**: V2 is deployed via Coolify as a single Docker image, natively mapping environment variables continuously into the container shell.
|
||||
- **Automated Restarts**: Code pushes to the `wwv-data-engine-public` repository automatically trigger a service restart via a secure `COOLIFY_API_TOKEN` configured in the CI/CD pipeline (replacing unreliable generic webhooks).
|
||||
- **Dual-Output Engine**: Seeders in V2 expose both a WebSocket stream (`/stream`) for real-time instantaneous updates, and a REST API endpoint (`/api/:id`) for fetching live data snapshots directly from Redis.
|
||||
|
||||
## 3. Pnpm Workspaces & Dynamic Dependency Loading
|
||||
To prevent seeders from ballooning in size by bundling a massive amount of dependencies, the system heavily relies on `pnpm` workspaces.
|
||||
- **Host Environment**: The V2 engine natively provides common geospatial and utility packages (e.g., `zod`, `ws`, `node-cron`, `undici`, `satellite.js`, `geoip-lite`). Seeders **MUST NOT** bundle these standard dependencies, and should leave them external in `tsup`.
|
||||
- **Dynamic Workspaces**: When V2 loads a compiled `dist/index.mjs` via `node`, it dynamically resolves imports by traversing up to the workspace `node_modules`.
|
||||
|
||||
## 4. Production Deployment & Downloader
|
||||
In production, the `wwv-data-engine-v2` does NOT mount the local file system. Instead:
|
||||
1. `download-seeders.ts` runs on container startup.
|
||||
2. It fetches the latest compiled `seeders.zip` from GitHub Releases for both community and private repositories.
|
||||
3. **CRITICAL STEP:** After unzipping the workspaces into a staging directory (`/app/seeders`), the script dynamically generates a root `package.json` and `pnpm-workspace.yaml`.
|
||||
4. It then runs a single **workspace-aware `pnpm install --prod`**. This ensures all custom unbundled dependencies declared by the extracted plugins are downloaded directly into the container and properly linked together.
|
||||
|
||||
## 5. Namespace Separation Rule
|
||||
To prevent collisions and `404` or `ERR_MODULE_NOT_FOUND` errors, seeders **MUST NOT** exist simultaneously in both the community (`wwv-seeders`, cloned to `local-seeders/community/`) and private (`wwv-seeders-private`, cloned to `local-seeders/private/`) repositories. Namespace overlaps will cause module resolution failures when the V2 engine attempts to load them. Private seeders have priority.
|
||||
|
||||
## 6. Plugin ID Contract — Single Source of Truth
|
||||
|
||||
> **See ADR-0002** (`docs/architecture/decisions/adr-0002-seeder-exported-name-as-canonical-plugin-id.md`) for full rationale and alternatives considered.
|
||||
|
||||
**Rule:** Every seeder MUST export a `name` field that exactly matches the corresponding frontend plugin's `id` field (kebab-case).
|
||||
|
||||
```typescript
|
||||
// ✅ Correct — seeder src/index.ts
|
||||
export default {
|
||||
name: "gps-jamming", // MUST equal the frontend plugin id
|
||||
cron: "0 0 * * *",
|
||||
fn: seedGpsJam,
|
||||
};
|
||||
|
||||
// ❌ Wrong — do not use folder names, camelCase, or abbreviations
|
||||
export default {
|
||||
name: "gpsjam", // mismatch — frontend plugin is "gps-jamming"
|
||||
...
|
||||
};
|
||||
```
|
||||
|
||||
**How the engine uses it:** `seeder-loader.ts` reads each seeder's exported `name` as the canonical plugin ID. This ID is used for:
|
||||
- The `/manifest` endpoint's `plugins` array (what the frontend checks for local routing)
|
||||
- WebSocket data messages (`pluginId` field)
|
||||
- Redis keys (`data:<name>:live`)
|
||||
- Scheduler logs
|
||||
|
||||
**Folder names are organizational only.** The engine warns at startup if `toKebabCase(folderName) !== seeder.name`, but this is cosmetic — the seeder's exported `name` always wins. Folder renames are a future cleanup, not a functional requirement.
|
||||
|
||||
**Frontend side:** `resolveEngineUrl(pluginId)` checks `localEngineHasPlugin(pluginId)` against the manifest. If the names match, the plugin routes to `ws://localhost:5000/stream`. No alias maps or translation layers are needed.
|
||||
|
||||
## 7. WebSocket Payload Format Contract
|
||||
|
||||
When a seeder calls `setLiveSnapshot(pluginId, payload, ttl)`, the engine broadcasts:
|
||||
```json
|
||||
{ "type": "data", "pluginId": "my-plugin", "payload": <whatever you passed> }
|
||||
```
|
||||
|
||||
**`WsClient` payload handling rules (in order):**
|
||||
|
||||
1. Plugin has `mapWebsocketPayload(payload, existingEntities)` → called with raw payload → must return `GeoEntity[]`
|
||||
2. No handler + payload **is** a flat `GeoEntity[]` array → used directly (timestamp normalized)
|
||||
3. No handler + payload is **any other object** → **silently dropped** with a console warning
|
||||
|
||||
This means:
|
||||
|
||||
| Seeder sends | Frontend needs | Notes |
|
||||
|---|---|---|
|
||||
| `[{id, latitude, longitude, ...}]` | Nothing (WsClient handles) | ✅ Simplest for basic point data |
|
||||
| `{ items: [{...}] }` | `mapWebsocketPayload` | Standard engine snapshot format |
|
||||
| `{ satellites: [{...}] }` | `mapWebsocketPayload` | Named-collection format |
|
||||
|
||||
**Recommendation:** If the seeder and frontend plugin are developed together, use a **flat `GeoEntity[]` array** — no `mapWebsocketPayload` needed. Use named objects (e.g. `{ satellites: [...] }`) only when the seeder data has a domain-specific shape worth preserving; in that case you **must** implement `mapWebsocketPayload` on the frontend plugin.
|
||||
|
||||
> [!CAUTION]
|
||||
> The most common silent bug: seeder sends `{ items: [...] }` (an object), frontend plugin omits `mapWebsocketPayload`. Data arrives but WsClient drops it with a console warning. The globe stays empty. Always implement `mapWebsocketPayload` for any plugin whose seeder sends an object payload.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
description: Rules for safe Prisma schema changes, defensive migrations, and PostgreSQL DDL operations.
|
||||
paths:
|
||||
- "prisma/**/*"
|
||||
---
|
||||
|
||||
# Database Migrations & Schema Modification Rules
|
||||
|
||||
## 1. Defensive Migrations
|
||||
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**: 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. P3005 Auto-Baseline (Handled in `docker-entrypoint.sh`)
|
||||
|
||||
`docker-entrypoint.sh` automatically recovers from Prisma **P3005** ("schema not empty, no migration history"). This happens when `pnpm dev` (which runs `prisma db push`) populates the database before the Docker stack is started.
|
||||
|
||||
The entrypoint only auto-baselines when **both** conditions hold:
|
||||
1. The error is exactly P3005.
|
||||
2. `prisma migrate diff` reports zero schema drift between the live DB and `prisma/schema.prisma`.
|
||||
|
||||
If drift is detected the container exits with a clear error message directing you to `pnpm db:reset`.
|
||||
|
||||
> **Never add manual `migrate resolve --applied` calls** unless you are outside the container and have independently verified the above two conditions. The entrypoint already handles the common case.
|
||||
|
||||
## 3. Managing Failed Migrations
|
||||
If a migration fails in production:
|
||||
- **Never blindly mark as resolved**: Do not run `prisma migrate resolve --applied <migration_name>` unless you have explicitly verified that the database schema precisely matches the expected state.
|
||||
- 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.
|
||||
|
||||
## 4. Backups Before DDL
|
||||
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,329 @@
|
||||
---
|
||||
description: Docker build patterns, pnpm dev commands, Vitest strategy, Coolify deployment rules, and security headers.
|
||||
paths:
|
||||
- "Dockerfile"
|
||||
- "docker-compose.yml"
|
||||
- ".github/**/*"
|
||||
- "next.config.ts"
|
||||
---
|
||||
|
||||
# Deployment, Testing, and Operations
|
||||
|
||||
## Development Commands
|
||||
|
||||
```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 db push + copy-cesium)
|
||||
pnpm dev:all # Frontend + wwv-data-engine (via Docker Compose) concurrently
|
||||
pnpm dev:backends # Starts the local data engine + Redis via Docker Compose
|
||||
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 database (destructive)
|
||||
pnpm start:backends # Legacy command for standalone Fastify backends
|
||||
pnpm clean:backends # Wipe all plugin database records
|
||||
pnpm run scaffold-osm-plugin <name> # Generate a new plugin from scaffold
|
||||
pnpm dev:plugins # File watcher for local-plugins/ directory (runs automatically in dev)
|
||||
node packages/wwv-cli/dist/index.js create <name> --local # Scaffold a new local plugin
|
||||
node packages/wwv-cli/dist/index.js link <name> # Promote a local plugin to packages/
|
||||
```
|
||||
|
||||
Frontend runs at `http://localhost:3000`.
|
||||
|
||||
## Deployment
|
||||
|
||||
- **Docker**: Multi-stage Dockerfile using the Extractor Pattern (`deps` → `builder` → `runner`). The `node_modules` folders must be explicitly untracked in from `git` across the workspace to prevent corrupted BuildKit contextual cache overlaps during the `COPY . .` stage.
|
||||
- **Standalone output**: `next.config.ts` uses `output: "standalone"`.
|
||||
- **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.
|
||||
- **Data Engine**: The single runner container 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.
|
||||
- **Docker volumes**: Ensure PostgreSQL data and Redis volumes are mounted for persistence.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- **Framework**: Vitest with jsdom environment
|
||||
- **Coverage**: `src/lib/**`, `src/core/**`, `src/plugins/**`
|
||||
- **Run**: `pnpm test` (or `vitest run`)
|
||||
- **Type-Level Contract Testing**: When defining shared TypeScript interfaces/contracts (e.g., in `wwv-plugin-sdk`), you MUST use `expectTypeOf` from `vitest` to assert the actual contract shapes at compile-time instead of writing literal-value identity runtime assertions. You must also enforce `@ts-expect-error` negative type tests to ensure missing or invalid fields trigger compilation errors.
|
||||
- **Key test files**: `rateLimit.test.ts`, `edition.test.ts`, `demoAdmin.test.ts`, `DeclarativePlugin.test.ts`, `cors.test.ts`, `repository.test.ts`, `marketplaceToken.test.ts`
|
||||
|
||||
### E2E Testing (Playwright)
|
||||
|
||||
WorldWideView uses Playwright for End-to-End browser testing to verify the complete UI integration including NextAuth.
|
||||
|
||||
- **Run**: `pnpm run test:e2e` (Ensure your database is running before executing)
|
||||
- **Auth Bypass**: Playwright uses a `global.setup.ts` to directly insert a test user into the database and simulate a UI login to capture a `storageState.json` cookie file. This allows all tests to run pre-authenticated without bypassing production security logic.
|
||||
- **Database Access in Setup**: Because Playwright setup scripts run in a vanilla Node context, importing Next.js backend utilities like `src/lib/db.ts` will crash with `next/headers` resolution errors. You MUST instantiate `PrismaClient` directly using `@prisma/adapter-pg` in any Playwright `setup` or `teardown` scripts.
|
||||
- **Component Synchronization**: Do not use arbitrary timeouts. Tests MUST wait for the application boot sequence to finish by waiting for the `[data-testid="app-ready"]` marker on the `AppShell` to be attached.
|
||||
- **Stable Selectors**: Always use `data-testid` properties (e.g. `data-testid="panel-toggle-left"`) for interacting with UI components in E2E tests rather than fragile CSS classes or dynamic text.
|
||||
- **Worktree Port Conflicts**: If you are testing in a git worktree, configure `playwright.config.ts` to spawn the `webServer` on an alternative port (e.g. `3001`) to avoid colliding with other running worktrees.
|
||||
|
||||
## Security Headers
|
||||
|
||||
Configured in `next.config.ts` `headers()`:
|
||||
- **CSP**: Restrictive with exceptions for CesiumJS (`unsafe-eval`, `unsafe-inline`), camera streams (`http: https:`), and analytics
|
||||
- **X-Frame-Options**: DENY
|
||||
- **X-Content-Type-Options**: nosniff
|
||||
- **Referrer-Policy**: strict-origin-when-cross-origin
|
||||
- **Permissions-Policy**: camera/microphone disabled, geolocation self-only
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Package Manager
|
||||
|
||||
The project uses **pnpm workspaces**. All `npm` commands in older docs/scripts should be treated as `pnpm`.
|
||||
|
||||
```bash
|
||||
pnpm install # install all workspace deps
|
||||
pnpm run dev # start dev server ONLY (worldwideview/)
|
||||
pnpm run dev:all # start ALL services concurrently (worldwideview, data-engine, marketplace)
|
||||
pnpm run build # production build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Local Dev Setup
|
||||
|
||||
```
|
||||
1. Clone repo
|
||||
2. pnpm install
|
||||
3. pnpm run setup # generates .env.local with AUTH_SECRET, copies .env.example
|
||||
4. pnpm run dev:all # predev: prisma migrate deploy + copy-cesium.mjs → then starts all services
|
||||
5. Open http://localhost:3000
|
||||
```
|
||||
|
||||
**Marketplace:** `cd worldwideview-marketplace && pnpm run dev` → http://localhost:3001
|
||||
|
||||
**Database auto-creates** on first run via `predev` script — no manual DB setup required.
|
||||
|
||||
---
|
||||
|
||||
## Database Operations
|
||||
|
||||
**All SQL from `c:\dev\worldwideview`:**
|
||||
|
||||
```powershell
|
||||
npx prisma db execute --sql "<SQL>"
|
||||
```
|
||||
|
||||
> Stop the dev server first to avoid "database is locked" errors.
|
||||
|
||||
### Common Commands
|
||||
|
||||
```powershell
|
||||
# View row counts (all tables)
|
||||
npx prisma db execute --sql "SELECT 'users' AS t, COUNT(*) AS n FROM users UNION ALL SELECT 'aviation_history', COUNT(*) FROM aviation_history UNION ALL SELECT 'installed_plugins', COUNT(*) FROM installed_plugins UNION ALL SELECT 'settings', COUNT(*) FROM settings;"
|
||||
|
||||
# List installed plugins
|
||||
npx prisma db execute --sql "SELECT pluginId, version, installedAt FROM installed_plugins ORDER BY installedAt DESC;"
|
||||
|
||||
# Clear all installed plugins
|
||||
npx prisma db execute --sql "DELETE FROM installed_plugins;"
|
||||
|
||||
# List settings
|
||||
npx prisma db execute --sql "SELECT key, value FROM settings;"
|
||||
|
||||
# Set/update a setting
|
||||
npx prisma db execute --sql "INSERT INTO settings (key, value) VALUES ('<key>', '<value>') ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value;"
|
||||
|
||||
# Prune aviation history older than 7 days
|
||||
npx prisma db execute --sql "DELETE FROM aviation_history WHERE timestamp < NOW() - INTERVAL '7 days';"
|
||||
|
||||
# Vacuum (reclaim disk space after pruning)
|
||||
npx prisma db execute --sql "VACUUM FULL;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Engine & Data Recovery
|
||||
|
||||
The secondary backend (Data Engine) handles high-volume API ingestion and pushes active snapshots to Upstash Redis. Because its PostgreSQL database is completely wiped on fresh Coolify deployments if volumes aren't preserved, it uses **Self-Healing Architecture**.
|
||||
|
||||
**How Recovery Works:**
|
||||
1. Upon startup, or during the 60-second cron cycle, the seeder checks if the target table (e.g., `iranwar_events`) is empty.
|
||||
2. If empty, the engine instantly hydrates the PostgreSQL database and the Upstash Redis cache from the committed fallback payload (e.g., `data/fallback/iranwar_seed.json`).
|
||||
3. To **force a rapid recovery** locally (such as when testing new scraper data), simply wipe the table and let the minute-tick refill it via `npx prisma db execute --sql "DELETE FROM iranwar_events;"`.
|
||||
|
||||
**OSINT Scraping & Hydration Best Practices:**
|
||||
Utility scripts (like `hydrate.ts`) exist to repair or enrich the fallback seed block offline. Important takeaways from building these scrapers:
|
||||
- **Location Mapping:** Always append structured `_osint_meta.coordinates: {lat, lng}`. Without exact coordinates, the SDK defaults to Null Island or scatters points uniformly across the globe (declutter grid effect).
|
||||
- **Tracking URL Resolution:** News aggregators (like Bing News RSS) wrap URLs in tracking redirect pages (`apiclick.aspx`). Never serve these directly to the frontend. Use `cheerio` to fetch the tracking page, parse the `<noscript><meta refresh="URL=..."></noscript>` node, extract the *actual* news URL, and then scrape the destination article for `og:image` and `og:video` tags.
|
||||
- **Frontend Sync:** Ensure Next.js schema mapping in the plugin (`wwv-plugin-xyz/src/index.ts`) perfectly mirrors the enriched fields so they render correctly in the UI.
|
||||
|
||||
### Schema Changes
|
||||
|
||||
```powershell
|
||||
npx prisma db push # sync schema changes to DB (non-destructive)
|
||||
npx prisma migrate dev --name "<description>" # create + apply a migration
|
||||
npx prisma generate # regenerate Prisma client types after schema change
|
||||
npx prisma studio # visual DB browser at http://localhost:5555
|
||||
```
|
||||
|
||||
### Full Reset
|
||||
|
||||
```powershell
|
||||
# Stop dev server first
|
||||
Remove-Item c:\dev\worldwideview\data\wwv.db
|
||||
npx prisma db push
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
### Browser Cache Clearing
|
||||
|
||||
```javascript
|
||||
// Clear IndexedDB entity cache
|
||||
indexedDB.deleteDatabase("worldwideview-cache");
|
||||
|
||||
// Clear localStorage user API keys
|
||||
Object.keys(localStorage)
|
||||
.filter(k => k.startsWith("wwv_"))
|
||||
.forEach(k => localStorage.removeItem(k));
|
||||
```
|
||||
|
||||
Known `wwv_*` localStorage keys (defined in `src/lib/userApiKeys.ts`):
|
||||
- `wwv_key_google_maps`
|
||||
- `wwv_key_nasa_firms`
|
||||
|
||||
Hard refresh: `Ctrl+Shift+R`
|
||||
|
||||
---
|
||||
|
||||
## DB Troubleshooting
|
||||
|
||||
| Error | Fix |
|
||||
|---|---|
|
||||
| "Database is locked" | Stop the dev server first |
|
||||
| "Table does not exist" | Run `npx prisma db push` |
|
||||
| "Plugin still shows after clearing" | Hard-refresh (`Ctrl+Shift+R`) or clear IndexedDB |
|
||||
| DB file is very large | Prune aviation history + run `VACUUM` |
|
||||
| Prisma client types are stale | Run `npx prisma generate` |
|
||||
|
||||
---
|
||||
|
||||
## Creating Static OSM Plugins
|
||||
|
||||
See full guide: `.agents/skills/osm-static-plugin-creation.md`
|
||||
|
||||
**Quick start:**
|
||||
```bash
|
||||
node scripts/scaffold-osm-plugin.mjs '{
|
||||
"name": "volcanoes",
|
||||
"displayName": "Volcanoes",
|
||||
"osmTag": "natural=volcano",
|
||||
"icon": "Mountain",
|
||||
"color": "#ef4444",
|
||||
"category": "Natural Disaster"
|
||||
}'
|
||||
```
|
||||
|
||||
**Manual Overpass API query (PowerShell):**
|
||||
```powershell
|
||||
$tag = '"natural"="volcano"'
|
||||
$body = "data=[out:json][timeout:300];(node[$tag];way[$tag];relation[$tag];);out center;"
|
||||
Invoke-RestMethod -Uri 'https://overpass-api.de/api/interpreter' -Method Post -Body $body -OutFile 'tmp/raw_data.json'
|
||||
```
|
||||
|
||||
**Note:** OSM data is licensed under **ODbL** — include attribution in plugin READMEs.
|
||||
|
||||
---
|
||||
|
||||
## npm Plugin Publishing
|
||||
|
||||
See full guide: `.agents/skills/version-control/npm-plugin-publishing.md`
|
||||
|
||||
```bash
|
||||
# First-time publish
|
||||
pnpm publish --workspace=packages/wwv-plugin-<name> --access public
|
||||
|
||||
# Future versions — via Trusted Publishing (GitHub Actions CI/CD)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git / Version Control
|
||||
|
||||
See full guide: `.agents/skills/version-control/git-version-control.md`
|
||||
|
||||
**Commit convention:** `feat:`, `fix:`, `chore:`, `docs:` prefixes.
|
||||
**Commit when:** A new feature is completed (per project rules).
|
||||
|
||||
---
|
||||
|
||||
## Security Checks
|
||||
|
||||
See full guide: `.agents/skills/security/security-check.md`
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
**Host Server:**
|
||||
The production Coolify instance runs on a local server at `192.168.68.64`. Direct SSH access: `ssh [email protected]`.
|
||||
|
||||
**CI/CD Flow:**
|
||||
1. Push to `silvertakana/worldwideview`
|
||||
2. Coolify webhook triggers → automated BuildKit deployment on the host server.
|
||||
|
||||
**GitHub Actions Workflows:**
|
||||
- **Minimal Permissions:** CodeQL and GitHub security best practices dictate that `GITHUB_TOKEN` permissions should always be explicitly constrained. When creating or modifying `.github/workflows/*.yml` files, you MUST always include an explicit `permissions` block (e.g., `permissions: { contents: read }` or similar required scopes) at the top level or job level to adhere to the principle of least privilege.
|
||||
|
||||
**Coolify Deployment Rules & Gotchas (The "Redis 500k" Rule):**
|
||||
- **Coolify Pulls from GitHub:** Coolify does *not* deploy your local workspace files. It strictly clones the repository from GitHub.
|
||||
- **Push Before You Deploy:** If you make a critical infrastructure or optimization fix locally (e.g., swapping a massive `HSET` pipeline for a compressed 5-min throttled `setLiveSnapshot`), you **must** `git commit` and `git push` those changes to the `main` branch before triggering a Coolify deployment.
|
||||
- **The "Rollback DDOS" Risk:** If you update environmental variables (like a new Upstash Redis URL) inside Coolify and deploy *without* pushing your local optimized code to GitHub, Coolify will pull the *older, unoptimized* repository code and aim it at your new endpoints. This will immediately exhaust the 500,000 requests/month Upstash free limit.
|
||||
- **Redis Connection Errors:** If the data engine crashes on startup with `MaxRetriesPerRequestError: Reached the max retries per request limit (which is 3)` and `ECONNRESET`, the `REDIS_URL` in your Coolify environment variables is incorrectly using `redis://` instead of the TLS-required `rediss://`.
|
||||
- **Immediate Rollback on Failure:** Whenever a Coolify deployment fails or introduces a critical bug (such as rate-limit exhaustion), **immediately select the last known working deployment in the Coolify dashboard and redeploy it.** Do not leave a broken deployment hanging while trying to debug directly in production. Roll back to stability first, debug locally, commit the verified fix, and then deploy forward.
|
||||
- **Public Port Binding:** Both the `wwv` (Next.js frontend) and `wwv-data-engine` containers are meant to be directly exposed to the internet, rather than relying on Traefik internal network routing. They MUST use `ports: - "3000:3000"` and `ports: - "5000:5000"` respectively in `docker-compose.yml`. Using `expose` hides them behind internal Docker routing. Only backend infrastructure like `db` and `wwv-redis` should use `expose`.
|
||||
|
||||
**Local verification:**
|
||||
Before pushing infrastructure changes, run `docker build -t wwv-test .` to verify that the Next.js `standalone` isolated multi-stage build works correctly.
|
||||
|
||||
**Critical Docker/BuildKit Patterns:**
|
||||
- **No Tracked `node_modules`:** Never track `node_modules` in git. It will severely break the Docker `COPY . .` BuildKit cache stage, as it attempts to overwrite the internally symlinked modules from the `deps` stage with the non-symlinked folders from git, causing cryptic `cannot copy to non-directory` errors.
|
||||
- **Prisma 7 in Standalone:** Prisma v7 strictly forbids `url = env("DATABASE_URL")` in `schema.prisma` if `prisma.config.ts` exists. You *must* provide the `url` property in `prisma.config.ts`.
|
||||
- **The `dotenv` Paradox:** Next.js `standalone` output does NOT automatically trace CLI tool devDependencies (like `dotenv`). If you import `dotenv` in `prisma.config.ts`, the production runner container will crash in a reboot loop. *Solution:* `prisma.config.ts` must use native Node `fs` and `path` to gracefully read from `.env` as a fallback, exporting a plain Javascript object without CLI wrappers.
|
||||
- **Standalone Scripts & Next.js Typechecking:** Next.js `pnpm build` triggers `tsc`. By default, this will aggressively typecheck the `scripts/` directory. One-off migration scripts that import backend-only dependencies (like `pg`) will fail the global build. Always ensure `"scripts"` is added to the `"exclude"` array in `tsconfig.json`.
|
||||
- **WSL2 / Docker Memory Bloat:** Next.js `standalone` + `pnpm workspaces` caching takes roughly 7GB to 10GB of virtual disk space and maxes out WSL2 memory during `docker-compose build`. Avoid building complex monorepos locally unless necessary. To reclaim local BuildKit disk space: `docker builder prune -a -f`. To reclaim WSL RAM: `wsl --shutdown`.
|
||||
- **TypeScript NodeNext ESM Extensions:** By default in strict NodeNext ESM, backend scripts compiled via TypeScript (like `server.ts`) require dynamic imports to explicitly list the extension. You MUST write `await import('./routes/index.js')`, even if the underlying code is a `.ts` file, or the Docker compilation will fail with `TS2834`.
|
||||
- **Git vs Docker Context Bloat:** Ensure `.dockerignore` ruthlessly excludes generated artifacts (e.g., `artifacts/`, `performance/`). Ensure `.gitignore` strips large binary caches like heavy database seed files inside `packages/*/data/` to prevent GitHub from bouncing commits exceeding the 100MB chunk limit.
|
||||
- **Host Resource Exhaustion & Implicit Failures:** Complex multi-stage pnpm builds generate massive amounts of intermediate layer cache. If the Coolify host server reaches 100% disk capacity during an active deployment, the build logs will silently truncate and die abruptly with no explicit `pnpm` error. Worse, services like PostgreSQL (`coolify-db`) will instantly crash because they cannot write lock files, causing total system outages. Always maintain at least 30-40GB of free space on deployment hosts before auto-deploying via Coolify.
|
||||
|
||||
|
||||
**Local update:** `git pull && pnpm install && pnpm run dev`
|
||||
|
||||
---
|
||||
|
||||
## Disk Space Management & Monitoring
|
||||
|
||||
The Docker build uses `standalone` output to minimize image size. The `copy-cesium.mjs` script copies only the required Cesium assets into `public/` — avoids shipping the entire Cesium package (300MB+) in the build.
|
||||
|
||||
**Host Server Maintenance:**
|
||||
On Coolify deployment targets (e.g., `192.168.68.64`), dangling BuildKit caches and orphaned images will eventually consume 100% of the disk.
|
||||
- To recover a crashed server: SSH into the host and run `docker system prune -a -f`.
|
||||
- **Proactive Monitoring:** Use the `netdata-remote` MCP server to poll or setup alerts for the host disk space. It is highly recommended to set a warning alert when disk usage exceeds 80%.
|
||||
|
||||
**Application Database Growth:**
|
||||
Aviation history can grow large. Prune regularly:
|
||||
```powershell
|
||||
npx prisma db execute --sql "DELETE FROM aviation_history WHERE timestamp < datetime('now', '-7 days');"
|
||||
npx prisma db execute --sql "VACUUM;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Terminology Quick Reference
|
||||
|
||||
| Term | Definition |
|
||||
|---|---|
|
||||
| **Edition** | `local`, `cloud`, or `demo` — set via `NEXT_PUBLIC_WWV_EDITION`. Drives auth/storage/tenant adapters |
|
||||
| **Bridge API** | Routes in WWV (`/api/marketplace/*`) that the marketplace calls to install/manage plugins |
|
||||
| **Setup Wizard** | First-run config UI — app-level (Cesium token) and plugin-level (plugin API keys) |
|
||||
| **Runtime Settings Store** | `settings` DB table — replaces `.env` for everything user-facing |
|
||||
| **RLS** | Row-Level Security — PostgreSQL feature enforcing tenant data isolation at the DB level |
|
||||
| **Snapshot Capture** | WWV periodically stores plugin data per tenant for history/timeline. Pro/Local only |
|
||||
| **Trust Stamping** | WWV always overwrites `manifest.trust` server-side — no client claims are accepted |
|
||||
| **NpmCache** | DB table caching NPM registry metadata to decouple from live NPM polling |
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
description: Guidelines and architecture for the Playwright End-to-End (E2E) testing infrastructure.
|
||||
paths:
|
||||
- "tests/**"
|
||||
- "public/e2e-fixtures/**"
|
||||
- "playwright.config.ts"
|
||||
---
|
||||
|
||||
# E2E Testing Infrastructure
|
||||
|
||||
The WorldWideView project uses **Playwright** for end-to-end (E2E) testing. This document outlines the boundaries, architectural decisions, and conventions required when authoring or modifying E2E tests.
|
||||
|
||||
## 1. Resource Constraints & Parallelism
|
||||
- **Worker Limits:** The Playwright configuration (`playwright.config.ts`) is strictly limited to a maximum of **2 workers**.
|
||||
- **Reasoning:** Running Next.js compilation alongside a heavy Prisma connection pool inside multiple parallel test workers will lead to database connection exhaustion and resource contention on CI and local environments. Do not increase the worker count beyond 2 without careful consideration of the database pool limits.
|
||||
|
||||
## 2. Test User Lifecycle
|
||||
E2E tests require an authenticated user to access core application features. We manage this test user securely to ensure the environment stays pristine:
|
||||
|
||||
- **Setup (`tests/global.setup.ts`):** Before tests run, the global setup script defensively deletes any existing test user (`[email protected]`) and creates a fresh instance with the `ADMIN` role. It then performs a UI login to capture the authentication state, which is shared across all test files.
|
||||
- **Teardown (`tests/global.teardown.ts`):** After the entire test suite completes (regardless of success or failure), the global teardown script runs and completely purges the test user from the database.
|
||||
- **Safety:** Do not use `[email protected]` for manual testing. It is volatile and intended exclusively for the CI test runner.
|
||||
|
||||
## 3. UI Interaction Conventions
|
||||
- **Strict Selector Usage**: ALWAYS use `data-testid` selectors (e.g., `getByTestId('panel-toggle-left')`) for DOM interactions. **NEVER rely on CSS classes** (like `.layer-item__toggle` or `.dock-btn`) or deep DOM structures, as these are brittle and break during design refactors. If a `data-testid` is missing from an element you need to test, you MUST add it to the React component source code first.
|
||||
- **Dialog Interception:** WorldWideView relies on heavy frontend plugin discovery and dynamic rendering. For example, the `UnverifiedPluginBatchDialog` may unexpectedly appear and block UI interactions in a fresh browser context.
|
||||
- *Mitigation:* Ensure your test suites either explicitly handle these dialogs (e.g., in a `beforeEach` block) or inject mock plugins that bypass the verification flow entirely.
|
||||
|
||||
## 4. Mock Plugins
|
||||
- **Data Interface Strictness**: WorldWideView's `PluginManager` is extremely strict. **ALL mock plugins MUST implement `getPollingInterval`, `fetch`, and `renderEntity`**, even if they are purely UI-focused (like a bottom-panel plugin). Failure to implement these will crash the renderer.
|
||||
- **Capabilities**: If your mock UI plugin needs to be manually activated by the user, ensure its manifest includes the `"ui:sidebar"` capability so it appears in the layer list.
|
||||
- **Injection:** We inject safe, deterministic mock plugins into the database during the `global.setup.ts` phase to test the core rendering pipeline without relying on external APIs. Ensure your mock plugin is registered in the setup and teardown cleanup arrays.
|
||||
- **Location:** Mock plugin configurations and manifests are stored in `public/e2e-fixtures/`. When modifying the rendering engine, ensure you also update the mock plugin (`public/e2e-fixtures/mock-plugin.js`) to reflect any changes in the Plugin SDK capabilities.
|
||||
|
||||
## 5. Security Permissions
|
||||
- When integrating Playwright tests into GitHub Actions (e.g., `.github/workflows/playwright.yml`), you MUST include an explicit permissions block (e.g., `permissions: { contents: read }`) to adhere to CodeQL and least-privilege scoping rules.
|
||||
|
||||
> [!WARNING]
|
||||
> If you encounter flaky tests or `ECONNREFUSED` errors during Playwright runs, check if the local Next.js dev server or the Docker engine stack is competing for ports (e.g., port 5432 or 3000). Ensure `pnpm run dev:backends` is running and stable before launching the test suite.
|
||||
|
||||
## 6. Execution Environment & Tooling Limitations
|
||||
The development environment operates on **Windows PowerShell**. Agents MUST adhere to the following strict execution rules when running commands or interacting with the testing infrastructure:
|
||||
- **No Double Ampersands (`&&`)**: Standard Windows PowerShell (prior to v7) does not support the `&&` operator. Use the semicolon (`;`) to chain commands, or rely on `pnpm` package.json scripts which manage cross-platform execution properly.
|
||||
- **Avoid Non-existent Database CLI Commands**: Do not attempt to use raw `pg` or `psql` commands unless explicitly verified to exist in the path. Instead, use Prisma (`npx prisma studio`, `npx prisma migrate`) or Docker executions (`docker exec -it wwv-db psql ...`) for database interactions.
|
||||
- **Creating Test Plugins**: You will repeatedly need to create mock test plugins for verifying different platform features (e.g. bottom-panel resizing, new UI widgets). When doing so, you MUST review this `e2e-testing.md` file to ensure compliance with the `PluginManager` strict interface rules (implementing `getPollingInterval`, `fetch`, and `renderEntity`).
|
||||
@@ -0,0 +1,74 @@
|
||||
# Garbage Collection Policy
|
||||
|
||||
## Purpose
|
||||
|
||||
The Garbage Collector (GC) is a daily Haiku-model agent that keeps the codebase clean. It detects stale TODOs, deprecated patterns, and architectural drift, then either applies a small mechanical fix (Tier A → draft PR) or files a report for human decision (Tier B → GitHub Issue). The GC **never makes architectural decisions** and **never auto-merges** anything.
|
||||
|
||||
## Two-tier output model
|
||||
|
||||
| Tier | Criteria | Output |
|
||||
|---|---|---|
|
||||
| **A — Mechanical** | Safe, codemod-like, no architectural judgement required | Draft PR with code change |
|
||||
| **B — Judgement** | Requires human architectural decision or context | GitHub Issue, no code |
|
||||
|
||||
When unsure of the tier, escalate to Tier B. Never attempt a refactor that requires understanding business intent.
|
||||
|
||||
## How the GC works
|
||||
|
||||
1. `scripts/gc-scan.mjs` runs first — deterministic shell-based detectors, zero cost, emits `gc-findings.json`.
|
||||
2. The Haiku agent reads `gc-findings.json` and the policy below. It **does not free-scan the codebase** — it only triages the pre-computed findings list.
|
||||
3. The agent creates draft PRs and Issues per the caps and guard rails below.
|
||||
|
||||
## Approved finding types (from gc-scan.mjs)
|
||||
|
||||
| Type | Tier | Description |
|
||||
|---|---|---|
|
||||
| `stale-todo` | A | TODO/FIXME/HACK/XXX comment older than 90 days, or referencing a closed issue |
|
||||
| `anti-pattern` (mdc-ref) | A | `.mdc` file reference — must be `.md` |
|
||||
| `anti-pattern` (console-log) | A | Stray `console.log(` in `.ts`/`.tsx` files |
|
||||
| `anti-pattern` (ts-ignore) | A | `@ts-ignore` suppressing a real type error |
|
||||
| `anti-pattern` (ts-nocheck) | A | `@ts-nocheck` disabling all type checking |
|
||||
| `anti-pattern` (hardcoded-url) | B | Hardcoded `localhost:5001`/`5000` engine URL |
|
||||
| `anti-pattern` (deprecated) | B | `@deprecated` symbol still active in production code |
|
||||
| `oversized-file` | B | Source file exceeding ~350 lines |
|
||||
| `orphaned-rule-ref` | B | Rule file references a path that no longer exists |
|
||||
| `outdated-dep` | B | Dependency behind latest version |
|
||||
|
||||
## PR guard rails (mandatory — no exceptions)
|
||||
|
||||
- All PRs are **DRAFT**. Never mark ready-for-review. Never auto-merge.
|
||||
- Label every PR and Issue `gc-bot`.
|
||||
- **Max 3 PRs per run. Max 5 Issues per run.**
|
||||
- **Max ~150 changed lines per PR.** One concern per PR.
|
||||
- Branch naming: `gc/<patternId-or-type>-<git-short-sha>` (e.g. `gc/console-log-a3f1b2c`)
|
||||
- Before creating anything: check open `gc-bot` PRs and Issues for the same concern — skip if already covered.
|
||||
- Commit prefix: `chore:` for removal/cleanup, `refactor:` for structural fixes. Both are patch-level per the project `/commit` rule.
|
||||
- Every PR description must include: what changed · which detector flagged it · which rule it violates · how to verify the fix is correct.
|
||||
|
||||
## Never-touch list (absolute — the agent must refuse)
|
||||
|
||||
- `prisma/migrations/**` — migrations are irreversible
|
||||
- `pnpm-lock.yaml` — lockfile integrity
|
||||
- `.env`, `.env.local`, `.env.*`, any file containing secrets or tokens
|
||||
- Generated assets: `public/cesium/**`, `.next/**`, `node_modules/**`
|
||||
- Large seed files: `packages/*/data/**`, `local-seeders/**`
|
||||
- Binary assets: images, videos, fonts, `.db` files
|
||||
- `local-scripts/` — scratch / one-off scripts, not subject to conventions
|
||||
|
||||
## Dry-run mode
|
||||
|
||||
When `DRY_RUN=true` (set in the workflow dispatch input):
|
||||
|
||||
- Post one summary comment on the tracking Issue (`[gc-bot] Daily Scan Reports`). Create that Issue if it does not exist (label: `gc-bot`).
|
||||
- List every finding with tier, file, line, description.
|
||||
- **Do not create any PRs or Issues.**
|
||||
- Use dry-run for the first 3–5 days after deployment to validate finding quality before enabling normal mode.
|
||||
|
||||
## Idempotency rules
|
||||
|
||||
A finding is already handled if **either** of these is true:
|
||||
|
||||
1. A remote branch matching `gc/<same-patternId-or-type>-*` exists (`git branch -r --list 'origin/gc/<type>-*'`).
|
||||
2. An open PR or Issue labelled `gc-bot` already covers the same file + concern.
|
||||
|
||||
Skip handled findings without error or noise.
|
||||
@@ -0,0 +1,237 @@
|
||||
---
|
||||
description: Guidelines for the WorldWideView plugin marketplace, database interactions, PKCE auth flow, and dynamic plugin installation.
|
||||
paths:
|
||||
- "src/lib/marketplace/**/*"
|
||||
- "src/app/api/marketplace/**/*"
|
||||
---
|
||||
|
||||
# Marketplace Architecture
|
||||
|
||||
## 1. InstalledPluginsLoader
|
||||
Marketplace plugins are dynamically loaded via `InstalledPluginsLoader`. At startup, this service queries the PostgreSQL database (`installed_plugins` table) for dynamically installed manifests.
|
||||
|
||||
## 2. Dynamic Bundle Loading
|
||||
Plugins from the marketplace use the `bundle` format and are imported at runtime from CDN endpoints (e.g., unpkg) via `loadPluginFromManifest()`.
|
||||
|
||||
## 3. Database Sync
|
||||
- Marketplace installations mutate the Prisma database.
|
||||
- `pluginManager.loadFromManifest()` validates and registers these plugins.
|
||||
- Ensure any schema changes to the marketplace tables follow the `database-migrations.md` rule.
|
||||
|
||||
## 4. Fresh-Install Seeding
|
||||
|
||||
Fresh installs (no rows in `InstalledPlugin`) auto-seed a starter set so the globe isn't empty on day one. The source of truth is the **signed verified registry** (`marketplace.worldwideview.dev/api/registry`, loaded by `registryClient.getVerifiedPluginIds()`).
|
||||
|
||||
- **No hard-coded plugin lists.** Publishing a plugin to the verified registry is what makes it part of the fresh-install starter set.
|
||||
- **Idempotent**: a `defaults_seeded` row in the `Setting` table prevents re-runs. If the registry is unreachable on first attempt, the guard is NOT set — the next request retries.
|
||||
- **Existing instances** with `defaults_seeded=true` are untouched. To pull in newly-verified plugins, users install via the marketplace UI.
|
||||
- **Demo edition** uses an independent path (`NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS` env var, handled in `AppShell.tsx` and `useMarketplaceSync.ts`) — not this seeder.
|
||||
|
||||
> [!CAUTION]
|
||||
> Do not reintroduce a static `DEFAULT_PLUGIN_IDS` constant or any other hard-coded plugin list. That drifted from npm reality, caused 404s for unpublished IDs, and conflated "verified" with "auto-installed."
|
||||
|
||||
## Current Implementation State
|
||||
|
||||
|
||||
- **Stage 4 (Bridge API + One-Click Install)** ✅ COMPLETE
|
||||
- Plugin data currently served from a volume-backed **PostgreSQL database** — plugins are submitted by entering an NPM package name in the Admin UI
|
||||
- The marketplace auto-fetches metadata from the NPM registry and parses the `"worldwideview"` block in `package.json`
|
||||
- A background `NpmCache` table caches NPM registry metadata to decouple from live NPM dependency
|
||||
- Future: Supabase DB for full publisher workflow (Stage 5)
|
||||
|
||||
---
|
||||
|
||||
## Plugin Submission Flow (Current)
|
||||
|
||||
1. Developer publishes their plugin to npm with a `"worldwideview"` block in `package.json`
|
||||
2. Admin opens the Marketplace Admin UI
|
||||
3. Admin enters the npm package name (e.g. `@worldwideview/wwv-plugin-my-data`)
|
||||
4. Marketplace fetches metadata from NPM registry, parses the manifest block, stores in PostgreSQL DB
|
||||
5. Plugin appears in the browse catalog
|
||||
|
||||
> Static plugins still need their GeoJSON files placed in the host application's `public/data/` directory.
|
||||
|
||||
---
|
||||
|
||||
## Token Exchange Authentication (PKCE)
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **See ADR-0001 (Decentralized Plugin Authentication & SSRF Mitigation)**
|
||||
> The PKCE flow and API key proxying MUST adhere to ADR-0001. This mandates AES-256-GCM encryption with 100,000 PBKDF2 iterations for all credentials stored in the `MarketplaceCredential` model, and DNS IP Pinning / stream chunking on all proxy requests to mitigate SSRF.
|
||||
|
||||
Auth is governed by an **Asymmetric JWT Token Exchange (PKCE)** model to eliminate static, long-lived, and un-rotatable tokens. The Marketplace acts as the OAuth Authorization Server.
|
||||
|
||||
```
|
||||
Local App initiates connection
|
||||
↓
|
||||
Local App generates PKCE `code_verifier` and `code_challenge` (S256)
|
||||
↓
|
||||
Local App redirects to Marketplace: /oauth/authorize?response_type=code&...
|
||||
↓
|
||||
User authenticates on Marketplace and grants access
|
||||
↓
|
||||
Marketplace redirects back to Local App: /api/marketplace/callback?code=...
|
||||
↓
|
||||
Local App exchanges `code` + `code_verifier` for a long-lived API Key from Marketplace
|
||||
↓
|
||||
Local App securely stores API Key (encrypted via AES-256-GCM)
|
||||
```
|
||||
|
||||
### Data Engine Connections
|
||||
|
||||
Once connected, the Local App uses the long-lived API Key to fetch short-lived entitlements for specific data engines:
|
||||
1. **Request JWT**: Local App requests a short-lived JWT for a specific Data Engine audience.
|
||||
2. **Issue JWT**: Marketplace signs an EdDSA JWT containing the user's entitlements and the specific audience.
|
||||
3. **Connect**: Local App connects to the decentralized Data Engine via WebSocket and performs "First-Message Auth" by sending the JWT.
|
||||
4. **Verify**: Data Engine verifies the EdDSA signature using the Marketplace's public JWKS. No central DB lookup is required.
|
||||
|
||||
`validateMarketplaceAuth` accepts auth in priority order:
|
||||
1. Active Auth.js session (same-origin browser)
|
||||
2. EdDSA JWT Bearer token (cross-origin, audience-bound)
|
||||
3. Legacy static `WWV_BRIDGE_TOKEN` (backward compat)
|
||||
|
||||
---
|
||||
|
||||
## WWV Bridge API Routes (Implemented)
|
||||
|
||||
| Route | Method | Purpose |
|
||||
|---|---|---|
|
||||
| `/api/marketplace/install-redirect` | GET | Browser redirect install — checks session, installs plugin, issues JWT |
|
||||
| `/api/marketplace/grant-token` | GET | Issues marketplace JWT without install (for Manage page) |
|
||||
| `/api/marketplace/status` | GET | Returns all installed plugins (session or JWT auth) |
|
||||
| `/api/marketplace/uninstall` | POST | Deletes an installed plugin record |
|
||||
| `/api/marketplace/load` | GET | Returns valid non-built-in manifests for client startup (no auth) |
|
||||
| `/api/auth/setup-status` | GET | CORS-enabled connection test endpoint |
|
||||
|
||||
### Auth Module: `src/lib/marketplace/`
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
| `auth.ts` | `validateMarketplaceAuth()` — session → JWT → legacy token |
|
||||
| `marketplaceToken.ts` | `issueMarketplaceToken()` / `verifyMarketplaceToken()` — HS256 JWT via jose |
|
||||
| `cors.ts` | CORS headers for marketplace bridge routes |
|
||||
| `repository.ts` | `upsertPlugin()`, `uninstallPlugin()`, `getInstalledPlugins()` |
|
||||
| `registryClient.ts` | Fetches and Ed25519-verifies the signed plugin registry. 5-min in-memory cache. Stamps trust at install time |
|
||||
| `trustedPlugins.ts` | `localStorage` helpers for tracking user-approved unverified plugins |
|
||||
|
||||
---
|
||||
|
||||
## Marketplace API Endpoints (Target State)
|
||||
|
||||
### Public
|
||||
| Method | Path | Description |
|
||||
|---|---|---|
|
||||
| GET | `/api/plugins` | List/search plugins |
|
||||
| GET | `/api/plugins/:id` | Plugin detail |
|
||||
| GET | `/api/plugins/:id/bundle` | Download plugin bundle |
|
||||
| GET | `/api/categories` | List categories |
|
||||
| GET | `/api/registry` | Ed25519-signed verified-plugins registry — fetched by WWV at install time |
|
||||
|
||||
### Authenticated (Consumer)
|
||||
| Method | Path | Description |
|
||||
|---|---|---|
|
||||
| POST | `/api/instances` | Register a WWV instance |
|
||||
| PUT | `/api/instances/:id/default` | Set default instance |
|
||||
| POST | `/api/plugins/:id/install` | Trigger install to default instance |
|
||||
| GET | `/api/me/plugins` | List user's installed plugins |
|
||||
|
||||
### Authenticated (Publisher)
|
||||
| Method | Path | Description |
|
||||
|---|---|---|
|
||||
| POST | `/api/publisher/plugins` | Submit a new plugin |
|
||||
| PUT | `/api/publisher/plugins/:id` | Update plugin |
|
||||
| POST | `/api/publisher/plugins/:id/versions` | Publish new version |
|
||||
| GET | `/api/publisher/analytics` | Publisher analytics |
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
### WWV Local DB (Prisma — current)
|
||||
|
||||
```prisma
|
||||
model InstalledPlugin {
|
||||
id String @id @default(uuid())
|
||||
pluginId String
|
||||
version String
|
||||
config String // Full manifest JSON
|
||||
installedAt DateTime @default(now())
|
||||
}
|
||||
|
||||
model NpmCache {
|
||||
id String @id @default(uuid())
|
||||
packageName String @unique
|
||||
metadata String // JSON — cached NPM registry response
|
||||
lastFetched DateTime @default(now())
|
||||
}
|
||||
```
|
||||
|
||||
### Marketplace DB (Supabase — target, Stage 5+)
|
||||
|
||||
```
|
||||
users ─── published_plugins ─── plugin_versions
|
||||
│
|
||||
reviews
|
||||
```
|
||||
|
||||
Key fields on `published_plugins`: `slug`, `publisher_namespace` (`publisher.plugin-name`), `status` (`draft | review | published | rejected`), `manifest` (jsonb).
|
||||
|
||||
### Cloud DB (Supabase PostgreSQL — RLS-scoped)
|
||||
|
||||
```
|
||||
tenants ─── installed_plugins
|
||||
└── settings
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
| Concern | Mitigation |
|
||||
|---|---|
|
||||
| No static API keys | Install flow uses session redirects — no token to leak |
|
||||
| Marketplace JWT | 30-day HS256, scope-locked, verified via `jose` |
|
||||
| CSRF | Install/grant-token are GET redirects — user explicitly navigates |
|
||||
| Open redirect | `redirectTo` validated against allowlist |
|
||||
| Manifest tampering | Base64 only — no code execution. Validated via `validateManifest()` |
|
||||
| Malicious plugins | Sandboxed in Web Workers (unverified). CSP headers. Code review (verified) |
|
||||
| Supply chain | Plugin bundles checksummed (SHA-256), integrity verified |
|
||||
| Plugin API keys | Stored encrypted (AES-256-GCM) in `MarketplaceCredential` model, never exposed to browser |
|
||||
| Trust forgery | Registry signed with Ed25519 — `verified` cannot be claimed for unlisted plugins |
|
||||
| Trust stamping | WWV always overwrites `manifest.trust` server-side — client/marketplace input ignored |
|
||||
| Unverified consent | Warning dialog before any unverified plugin loads; approval stored per-plugin in `localStorage` |
|
||||
|
||||
---
|
||||
|
||||
## API Key Proxy & Rate Limiting (For `apikey` plugins)
|
||||
|
||||
Response caching makes server-as-proxy viable at scale:
|
||||
|
||||
```
|
||||
1000 users viewing earthquake plugin:
|
||||
→ 1000 requests hit your proxy
|
||||
→ Proxy: "I fetched this URL 3s ago, cache still valid"
|
||||
→ Returns cached response to all 1000
|
||||
→ 1 actual upstream request to USGS
|
||||
```
|
||||
|
||||
| Tier | Proxy req/min | Cache TTL |
|
||||
|---|---|---|
|
||||
| Free | 60 | 30s |
|
||||
| Pro | 300 | 10s |
|
||||
| Enterprise | Unlimited | 5s |
|
||||
|
||||
---
|
||||
|
||||
## History & Timeline
|
||||
|
||||
**Third-party history (`historyUrl`):** Plugin manifest declares a history URL with `%t` placeholder. WWV replaces it with the scrubber timestamp — third-party provides the endpoint. No storage on your side. Available on all tiers.
|
||||
|
||||
**WWV Snapshot Capture:** Your server periodically stores plugin data per tenant. Counts toward storage quota. Pro/Local only.
|
||||
|
||||
| Feature | Free (cloud) | Pro / Local |
|
||||
|---|---|---|
|
||||
| Live data (declarative `url`) | ✅ | ✅ |
|
||||
| Third-party history (`historyUrl`) | ✅ If supported by API | ✅ |
|
||||
| WWV snapshot capture | ❌ | ✅ Counts toward quota |
|
||||
| Built-in aviation/maritime history | ✅ Limited (24h) | ✅ Full |
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
description: Strict rules for operating within the pnpm monorepo workspace environment structure across frontend and backend services.
|
||||
paths:
|
||||
- "packages/**/*"
|
||||
- "pnpm-workspace.yaml"
|
||||
- "local-plugins/**/*"
|
||||
---
|
||||
|
||||
# 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, data engine seeders are located at `local-seeders/community/[name]` or `local-seeders/private/[name]`. **These are separate git clones** (`github.com/silvertakana/wwv-seeders` and `wwv-seeders-private` respectively) — `pnpm install` from the main repo does NOT pull seeder code. Run `git pull` inside each clone to get upstream changes.
|
||||
|
||||
## 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 dev:all` from the project root employs `docker-compose` to spin up the data engine runner and your local seeders alongside the Next.js frontend.
|
||||
|
||||
## 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,488 @@
|
||||
---
|
||||
description: The standard operating procedure for instantiating, modifying, and registering a new data source plugin within the engine.
|
||||
paths:
|
||||
- "src/core/plugins/**/*"
|
||||
- "packages/wwv-plugin-*/src/**/*"
|
||||
- "local-plugins/**/*"
|
||||
- "packages/wwv-plugin-sdk/src/**/*"
|
||||
---
|
||||
|
||||
# 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 Data Delivery Types
|
||||
|
||||
Plugins receive entity data in one of three modes. Choose the right mode before writing code — mixing them causes silent data loss.
|
||||
|
||||
| Mode | `getPollingInterval()` | `fetch()` | `mapWebsocketPayload()` | When to use |
|
||||
|---|---|---|---|---|
|
||||
| **REST-only** | `> 0` (ms) | Returns `GeoEntity[]` | Not needed | Static or slow-changing data (< every 30s). No seeder required. |
|
||||
| **WebSocket-only** | `0` | Return `[]` immediately | **Required** if seeder sends object payload | Live-streaming data from a seeder (satellites, AIS, flights) |
|
||||
| **Hybrid** | `> 0` | Returns initial snapshot | **Required** if seeder sends object payload | Needs both immediate data on load AND live updates |
|
||||
|
||||
### WebSocket-Only Pattern (most live-data plugins)
|
||||
|
||||
```typescript
|
||||
getPollingInterval(): number {
|
||||
return 0; // WS-only — do NOT call REST on enable
|
||||
}
|
||||
|
||||
async fetch(_timeRange: TimeRange): Promise<GeoEntity[]> {
|
||||
return []; // Initial data arrives via mapWebsocketPayload within seconds
|
||||
}
|
||||
|
||||
mapWebsocketPayload(payload: any, _existingEntities: GeoEntity[]): GeoEntity[] {
|
||||
// Transform raw engine payload → GeoEntity[]
|
||||
// payload shape depends on what the seeder calls setLiveSnapshot() with
|
||||
const items = payload?.items ?? (Array.isArray(payload) ? payload : []);
|
||||
return items.map((item: any): GeoEntity => ({
|
||||
id: `my-plugin-${item.id}`,
|
||||
pluginId: "my-plugin",
|
||||
latitude: item.lat,
|
||||
longitude: item.lon,
|
||||
altitude: item.alt ?? 0,
|
||||
timestamp: new Date(),
|
||||
label: item.name,
|
||||
properties: item,
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> If `getPollingInterval()` returns `0` but the seeder sends an object payload, you **MUST** implement `mapWebsocketPayload`. Without it, `WsClient` drops the data silently. See `data-engine-architecture.md §7` for the exact rule.
|
||||
|
||||
### `mapWebsocketPayload` Signature
|
||||
|
||||
```typescript
|
||||
mapWebsocketPayload(payload: any, existingEntities: GeoEntity[]): GeoEntity[]
|
||||
```
|
||||
|
||||
- `payload` — raw value from `setLiveSnapshot()` in the seeder (whatever shape the seeder stores)
|
||||
- `existingEntities` — current entities in the store for this plugin (use for incremental updates)
|
||||
- Must return a **complete replacement** `GeoEntity[]` (not a diff)
|
||||
|
||||
---
|
||||
|
||||
## Plugin Architectures (Manifest Formats)
|
||||
|
||||
Plugins are defined via `PluginManifest` and operate on an **All-Bundle** architecture.
|
||||
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"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `peerDependencies` Rule for npm-Published Plugins
|
||||
|
||||
Plugins published to npm **MUST** declare the following as `peerDependencies`, not `dependencies`:
|
||||
|
||||
```json
|
||||
{
|
||||
"peerDependencies": {
|
||||
"@worldwideview/wwv-plugin-sdk": "*",
|
||||
"react": ">=19",
|
||||
"lucide-react": "*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Also peer (never bundle): `react-dom`, `cesium`, `resium`, `zustand`.
|
||||
|
||||
Bundling these causes multiple React instances in the host app, breaking hooks (`Invalid hook call` at runtime).
|
||||
|
||||
### File Extension Rule
|
||||
|
||||
- Files containing **JSX** (any `<Component />` syntax, `return (<div>...)`) → must use `.tsx`
|
||||
- Files with no JSX (pure TypeScript, even importing React types) → use `.ts`
|
||||
|
||||
This is enforced by the TypeScript compiler. A `.ts` file with JSX will fail to build.
|
||||
|
||||
---
|
||||
|
||||
## The Registration Pipeline
|
||||
|
||||
> [!NOTE]
|
||||
> 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
|
||||
});
|
||||
```
|
||||
|
||||
## Local Plugin Development
|
||||
|
||||
`local-plugins/` is a **git clone of the canonical community plugin repo** (`github.com/silvertakana/wwv-plugins`), gitignored from the main `worldwideview` repo. It has its own remote — commits and pushes go upstream to that public repo, not to `worldwideview`. Run `cd local-plugins && git pull` before working to get the latest community plugins.
|
||||
|
||||
1. **Create**: Run `node packages/wwv-cli/dist/index.js create <name> --local` to scaffold a full plugin structure inside the `local-plugins/` directory.
|
||||
2. **Develop**: Running `pnpm dev` or `pnpm dev:all` automatically spawns the `dev:plugins` watcher. Any changes made to plugins in `local-plugins/` will be instantly rebuilt using Vite (externalizing large globals) and synced to `public/plugins-local/` for hot-reloading.
|
||||
3. **Publish**: The `dev:plugins` script natively supports hot-reloading local plugins within the workspace. Once the plugin is ready, you can simply use `node packages/wwv-cli/dist/index.js publish <name> [--org <your-org>]` from the project root to publish it.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## Capability Declarations
|
||||
|
||||
|
||||
Every plugin declares what it can access. Undeclared capabilities are **blocked at runtime**.
|
||||
|
||||
```typescript
|
||||
type PluginCapability =
|
||||
| "data:own" // Fetch and render its own data layer
|
||||
| "data:read:<id>" // Read entities from another plugin
|
||||
| "ui:detail-panel" // Inject UI into entity detail panel
|
||||
| "ui:sidebar" // Add a sidebar section
|
||||
| "ui:toolbar" // Add toolbar buttons
|
||||
| "ui:settings" // Add a settings page
|
||||
| "globe:overlay" // Draw on the globe (polylines, polygons, heatmaps)
|
||||
| "globe:camera" // Control camera movement
|
||||
| "storage:read" // Read from local/cloud storage
|
||||
| "storage:write" // Write to local/cloud storage
|
||||
| "network:fetch" // Make external HTTP requests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Trust Tiers
|
||||
|
||||
| Trust Tier | Who | Capabilities Allowed | How Determined |
|
||||
|---|---|---|---|
|
||||
| **Built-in** | Ships with WWV | All | Hardcoded in `AppShell` at build time |
|
||||
| **Verified** | WorldWideView-reviewed | Any declared capability | Plugin ID in the **signed registry** |
|
||||
| **Unverified** | Community / 3rd-party | `data:own`, `ui:settings` only | Plugin ID NOT in the registry |
|
||||
|
||||
### Signed Plugin Registry
|
||||
|
||||
Trust is determined by a cryptographically signed JSON file:
|
||||
|
||||
```
|
||||
GET marketplace.worldwideview.dev/api/registry
|
||||
→ { plugins: ["aviation", "maritime", ...], issuedAt, signature }
|
||||
```
|
||||
|
||||
- Signed with **Ed25519** private key (held only by registry maintainer)
|
||||
- WWV instances have the **public key hardcoded** — nobody can forge a fake verified list
|
||||
- WWV fetches and **verifies signature server-side** at install time
|
||||
- Trust is **always stamped server-side** — no client-side trust claims accepted
|
||||
- Registry response cached for **5 minutes** (in-memory on each WWV instance)
|
||||
- If registry unreachable, last cached result used; new unknowns default to `unverified`
|
||||
- **Managing:** Edit `src/data/verifiedPlugins.ts` in marketplace repo and redeploy
|
||||
- **Revoking:** Remove plugin ID and redeploy — WWV instances drop trust on next cache refresh
|
||||
|
||||
### Unverified Plugin Warning
|
||||
|
||||
When an unverified manifest is encountered:
|
||||
1. Plugin held in pending queue (not loaded)
|
||||
2. `UnverifiedPluginDialog` shown: "This plugin is unverified. Install at your own risk."
|
||||
3. User can Allow (stores approval in `localStorage`) or Deny
|
||||
4. Once approved, dialog won't reappear for that plugin ID
|
||||
|
||||
---
|
||||
|
||||
## VS Code Design Patterns Applied
|
||||
|
||||
**Activation events** — plugins declare when they activate, not at startup:
|
||||
```json
|
||||
"activationEvents": ["onView:aviationLayer", "onCommand:wwv.showCockpit"]
|
||||
```
|
||||
|
||||
**Contribution points** — declarative UI, no code needed for sidebar/menu entries:
|
||||
```json
|
||||
"contributes": {
|
||||
"commands": [{ "command": "wwv.enterCockpit", "title": "Enter Cockpit View" }],
|
||||
"settings": [{ "key": "refreshInterval", "type": "number", "default": 10 }]
|
||||
}
|
||||
```
|
||||
|
||||
**Extension dependencies** — plugins can require other plugins (auto-installed if missing):
|
||||
```json
|
||||
"extensionDependencies": ["worldwideview.aviation"]
|
||||
```
|
||||
|
||||
**Publisher namespaces** — `publisher.plugin-name` (e.g., `silvertakana.aviation`). Prevents naming conflicts.
|
||||
|
||||
**Extension packs** — bundles of related plugins:
|
||||
```json
|
||||
{ "id": "worldwideview.military-suite", "extensionPack": ["aviation", "military-bases", "radar-overlay"] }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plugin Auth Types
|
||||
|
||||
Plugins declare auth type in the manifest:
|
||||
|
||||
| Auth Type | Who Calls the API | Server Role |
|
||||
|---|---|---|
|
||||
| `none` | Browser, directly | Nothing |
|
||||
| `apikey` | Server proxy | Injects key from DB, caches response |
|
||||
| `token-exchange` | Browser, directly (after exchange) | One-time key→token swap |
|
||||
| `oauth` | Browser, directly (after OAuth) | OAuth callback handler, stores token |
|
||||
|
||||
**Recommended for scale:** `token-exchange` — your server is never in the hot path for data requests.
|
||||
|
||||
### Shared Auth Contracts & Security Branding
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **See ADR-0001 (Decentralized Plugin Authentication & SSRF Mitigation)**
|
||||
> All proxy and token-exchange implementations must strictly adhere to ADR-0001. This includes enforcing DNS IP Pinning and stream size limits via `undici.Agent` on all proxy routes to prevent SSRF, and encrypting all long-lived credentials (API keys) using AES-256-GCM with 100k PBKDF2 iterations before storing them in the `MarketplaceCredential` model.
|
||||
|
||||
When implementing the `token-exchange` flow or communicating across domains, all plugins and endpoints MUST use the strictly defined shared auth contracts from `@worldwideview/wwv-plugin-sdk/src/auth-contracts.ts` (e.g., `TokenExchangeRequest`, `WebSocketAuthMessage`).
|
||||
|
||||
**Sensitive Credentials**: All long-lived secrets (like API keys and tokens) MUST use the `SensitiveString` branded type and be instantiated via the `sensitive(str)` factory function. This prevents accidental logging/serialization and creates a single grep target for security audits.
|
||||
|
||||
---
|
||||
|
||||
## Plugin Development Workflows
|
||||
|
||||
Starting in 2026, WorldWideView adopted the **Architect and Toolbox** paradigm using NPM global tools, ensuring a fully decoupled developer experience. Plugin repositories contain *pure code* with absolutely no platform hosting boilerplate (e.g. no embedded docker-compose files).
|
||||
|
||||
### The Developer Experience
|
||||
1. **Scaffold**: `node packages/wwv-cli/dist/index.js create <name> --local` (Creates plugin inside `local-plugins/` — the community plugin repo clone)
|
||||
2. **Install**: `pnpm install` (Links dependencies via workspace)
|
||||
3. **Develop**: `pnpm dev:all` (Starts frontend, data engine, and plugin watcher dynamically)
|
||||
|
||||
### Local vs Docker Development
|
||||
The marketplace API natively supports hot-reloading for local plugins without rebuilding the core.
|
||||
|
||||
**Docker-Hosted Mode (Recommended for external devs):**
|
||||
If a developer wants to build a plugin without cloning the 1GB+ WorldWideView monorepo, they can pull the official WWV Docker image and mount their compiled plugin code:
|
||||
1. Run WWV with the development flag: `WWV_PLUGIN_DEV=true`
|
||||
2. Mount the local plugin's `dist/` folder into the container's `/app/local-plugins/` directory.
|
||||
3. Because the plugin is strictly code, Vite rebuilds in <100ms, and a browser refresh instantly loads the new plugin from the Docker volume.
|
||||
|
||||
**Core Contributor Mode:**
|
||||
If working inside a cloned `worldwideview` directory, scaffolding the plugin into `local-plugins/` makes it a pnpm workspace member. Running `pnpm dev:all` automatically spawns `pnpm dev:plugins`, which continuously transpiles local plugins so the Next.js frontend can hot-reload them without complex linking.
|
||||
|
||||
---
|
||||
|
||||
DB stores **references only** — never plugin files:
|
||||
|
||||
```prisma
|
||||
model InstalledPlugin {
|
||||
pluginId String
|
||||
version String
|
||||
manifestUrl String // "https://marketplace.../api/plugins/aviation/manifest"
|
||||
bundleUrl String? // local path or CDN URL (differs by edition)
|
||||
}
|
||||
```
|
||||
|
||||
| Edition | `bundleUrl` | How served |
|
||||
|---|---|---|
|
||||
| **Local** | `file:./plugins/cockpit-view/bundle.js` | Local filesystem (downloaded at install) |
|
||||
| **Cloud** | `https://cdn.worldwideview.dev/plugins/cockpit-view/bundle.js` | CDN at runtime |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables & Execution Agnosticism
|
||||
|
||||
WWV enforces a strictly decoupled execution context, allowing plugins to function reliably whether they are loading locally (`plugins-local`) or from a public CDN (`unpkg.com`).
|
||||
|
||||
### Dynamic Assets (`import.meta.url`)
|
||||
For file-based assets bundled alongside the plugin (such as JSON datasets or 3D GLTF models), the runtime relies on native ECMAScript relative resolution instead of hardcoded framework paths.
|
||||
- Plugins securely fetch their assets using `new URL('data/data.json', import.meta.url).href`.
|
||||
- **Impact:** Assets resolve properly directly from the domain they were executed on. No CORS bypasses or CDN fallbacks required.
|
||||
|
||||
### .env Passthrough Injection
|
||||
The WorldWideView core engine functions as a "blind pipe" for developer environment variables, allowing organizations to securely route plugins to custom backend microservices (local or cloud) without modifying the platform.
|
||||
1. The developer adds `NEXT_PUBLIC_WWV_PLUGIN_EXAMPLE_URL="http://localhost:5001"` to their `.env.local`.
|
||||
2. The engine detects the `NEXT_PUBLIC_WWV_PLUGIN_` prefix, strips it, and dynamically hydrates the `PluginContext`.
|
||||
3. The plugin natively retrieves `ctx.env.EXAMPLE_URL`.
|
||||
4. *Security Clause:* Variables accessible via `ctx.env` are exposed directly to the **client-side bundle**. Core secrets/API tokens must never be used here; they must exclusively use the server-side `ctx.getSecret()` workflow.
|
||||
|
||||
---
|
||||
|
||||
## Lazy Loading
|
||||
|
||||
Plugins load their code **only when activated**, not at startup:
|
||||
|
||||
```
|
||||
Startup: load manifests from DB (one query) → globe with built-in plugins only
|
||||
Toggle on "Aviation" → import() aviation bundle → register → fetch data
|
||||
Toggle on "Cockpit View" → import() cockpit bundle → register
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Stack
|
||||
|
||||
| Piece | Library |
|
||||
|---|---|
|
||||
| Bundle loading | Native `import()` or `@module-federation/enhanced/runtime` |
|
||||
| Manifest validation | `zod` |
|
||||
| Sandboxing (unverified plugins) | `comlink` + Web Workers |
|
||||
| Dependency resolution | `toposort` |
|
||||
| Event system | `mitt` (200 bytes) |
|
||||
| Plugin registry | Custom `PluginManager` class |
|
||||
|
||||
---
|
||||
|
||||
## Built-In Plugins (Current)
|
||||
|
||||
| Plugin | Format | Data Source |
|
||||
|---|---|---|
|
||||
| Aviation | bundle | OpenSky Network (ADS-B) |
|
||||
| Maritime | bundle | AIS (maritime tracking) |
|
||||
| Borders | bundle | GeoJSON from public API |
|
||||
| Wildfire | bundle | NASA FIRMS |
|
||||
| Military Bases | bundle (compiled) | OpenStreetMap (via Overpass) |
|
||||
| Nuclear Facilities | bundle (compiled) | OpenStreetMap |
|
||||
| Camera/CCTV | bundle | IP camera streams |
|
||||
| GeoJSON | bundle | User-supplied GeoJSON files |
|
||||
|
||||
Future direction: Aviation and maritime redesigned as **declarative plugins** pointing to `api.worldwideview.dev` — your own API server handles polling, persistence, and history for all tenants.
|
||||
|
||||
---
|
||||
|
||||
## Creating Static OSM Plugins
|
||||
|
||||
For static plugins built from OpenStreetMap data, use the scaffold script:
|
||||
|
||||
```bash
|
||||
node scripts/scaffold-osm-plugin.mjs '{
|
||||
"name": "volcanoes",
|
||||
"displayName": "Volcanoes",
|
||||
"description": "Active and dormant volcanoes worldwide from OSM",
|
||||
"osmTag": "natural=volcano",
|
||||
"icon": "Mountain",
|
||||
"color": "#ef4444",
|
||||
"category": "Natural Disaster"
|
||||
}'
|
||||
```
|
||||
|
||||
This queries Overpass API, converts to GeoJSON, scaffolds the package, and prints marketplace snippets.
|
||||
|
||||
**Common OSM tags:**
|
||||
|
||||
| Dataset | OSM Tag | ~Count |
|
||||
|---------|---------|--------|
|
||||
| Airports | `aeroway=aerodrome` | 40k |
|
||||
| Seaports | `harbour=yes` | 15k |
|
||||
| Nuclear facilities | `generator:source=nuclear` | 758 |
|
||||
| Volcanoes | `natural=volcano` | 1.5k |
|
||||
| Lighthouses | `man_made=lighthouse` | 20k |
|
||||
| Embassies | `amenity=embassy` | 10k |
|
||||
| Helipads | `aeroway=helipad` | 25k |
|
||||
| Power plants | `power=plant` | 15k |
|
||||
| Wind farms | `generator:source=wind` | 50k |
|
||||
|
||||
See skill: `.agents/skills/osm-static-plugin-creation.md`
|
||||
|
||||
---
|
||||
|
||||
## The Data Engine (Backend & Seeders)
|
||||
|
||||
When a plugin requires 24/7 background polling, long-term history (PostgreSQL), or high-frequency caching (Redis), it should leverage the **Data Engine**. The WWV architecture splits the frontend UI package and the backend data collection into two distinct tiers.
|
||||
|
||||
### 1. First-Party / Built-In Plugins
|
||||
For plugins developed directly inside the WWV monorepo:
|
||||
- **Seeder Module**: Developers write a single seeder (e.g. `seeders/aviation.ts`) inside the `wwv-data-engine` package.
|
||||
- **Unified Container**: All first-party seeders run inside one singular `wwv-data-engine` Docker container. This prevents background polling from being destroyed by Next.js edge isolation or HMR.
|
||||
|
||||
### 2. Third-Party / Community Plugins (The VPS Problem)
|
||||
Currently, **there is a high DX friction for third-party developers hosting their own heavy plugins.**
|
||||
- The `wwv-data-engine` is deeply coupled to the WWV host. Third-party developers cannot push their backend seeders into WWV's actual servers.
|
||||
- The `wwv-plugin-sdk` only assists with the frontend `WorldPlugin` interface.
|
||||
- Consequently, a sole developer with a VPS must write their own Node.js backend entirely from scratch to serve their custom data feeds, handle their own caching, and manage multiple Node instances if they create multiple plugins.
|
||||
|
||||
### 3. The Future: Distributable Data Engine Image
|
||||
To solve this friction and make third-party plugin hosting highly intuitive, the WWV roadmap includes publishing a **WWV Mini-Engine** as a standalone Docker image:
|
||||
1. **Lightweight Deployment:** Developers run `docker run worldwideview/mini-engine` on their VPS.
|
||||
2. **Backend SDK:** They write simple `.ts` fetch scripts returning `GeoEntity[]` and drop them into a mounted `/seeders` volume.
|
||||
3. **Zero Configuration:** The Docker engine hot-reloads these seeders, handles the Redis caching, and exposes standardized REST or WebSocket endpoints automatically. The developer focuses only on fetching data, avoiding all backend infrastructure setup.
|
||||
|
||||
See skill: `.agents/skills/data-engine-seeder-creation.md`
|
||||
|
||||
---
|
||||
|
||||
## Architectural Differences: WorldWideView (WWV) vs WorldMonitor (WM)
|
||||
|
||||
While WorldWideView draws UI/UX and feature inspiration from WorldMonitor as a baseline, the underlying plugin architectures are fundamentally different.
|
||||
|
||||
### WorldMonitor (The Inspiration)
|
||||
- **Monolithic Frontend**: Layers and datasets are typically hardcoded directly into the application's core logic.
|
||||
- **Custom Implementations**: Each data source usually requires its own bespoke API fetching, state management, and map rendering logic (e.g., raw Mapbox/Cesium objects).
|
||||
- **Coupled Backend**: Data ingestion is often tightly coupled to the monolithic application or spread across scattered, heterogeneous microservices without a unified cache.
|
||||
|
||||
### WorldWideView (The Reality)
|
||||
- **Extensible VS Code-Style Runtime**: Plugins are wholly independent, sandboxable modules loaded dynamically via activation events. The core map knows nothing about aviation or wildfires.
|
||||
- **Unified Data Contract (`GeoEntity`)**: All data layers map their bespoke formats into a strict, unified `GeoEntity` system. The core engine handles clustering, filtering, and timeline playback generically—no custom rendering trickery needed per dataset.
|
||||
- **Shared Data Engine**: WWV enforces a strict separation of concerns. All 24/7 API polling, data normalizations, and history retention happen off-thread in the singular `wwv-data-engine` (utilizing Redis hot cache + PostgreSQL history retention), providing a clean, unified REST interface for the plugin frontend.
|
||||
- **Cryptographic Trust**: WWV incorporates a signed marketplace registry and fine-grained capability declarations (`data:read`, `ui:sidebar`), establishing an enterprise-ready security posture for third-party extensions.
|
||||
|
||||
### Planned Features (Inspired by Monolithic Systems / WM)
|
||||
While avoiding monolithic coupling, WWV plans to implement the following high-UX features natively or via generic plugin capabilities:
|
||||
|
||||
1. **Decentralized Plugin Connections (Agnostic Client)**: WorldWideView is entirely agnostic to the backend. It does NOT enforce a single unified pipeline. If a user activates 30 different plugins hosted on 30 different custom servers, the frontend will happily open 30 separate WebSocket connections. The client application knows absolutely nothing about the Data Engine—it only reads the `streamUrl` provided by each individual plugin's manifest.
|
||||
2. **Cross-Layer Geofencing & Alerts**: A new `User Alert System` designed explicitly as a **plugin**. Utilizing the unified `GeoEntity` outputs, users can draw a polygon on the map and trigger webhooks/notifications if *any* entity from *any* active plugin crosses the boundary.
|
||||
3. **Advanced Dead-Reckoning Hooks**: Building a `useDeadReckoning()` hook directly into the `@worldwideview/wwv-plugin-sdk`. It will automatically use standard `speed` and `heading` props to smoothly glide vehicle entities across the Cesium globe at 60 FPS between data pings, preventing plugin authors from rewriting complex math logic.
|
||||
4. **Curated Workspaces / Scenarios**: The ability for users to save their current state as a "Workspace URL." This generates a shareable link that encodes the exact camera position, timeline bounds, activated plugins, and their respective layer configurations/filters.
|
||||
|
||||
|
||||
## Local Plugins & Seeders
|
||||
|
||||
### 1. Local Plugin Workflow (`local-plugins/` — community plugin repo clone)
|
||||
`local-plugins/` is a git clone of `github.com/silvertakana/wwv-plugins` with its own remote. Pull latest before starting: `cd local-plugins && git pull`.
|
||||
- **Scaffold**: `node packages/wwv-cli/dist/index.js create` (creates inside `local-plugins/wwv-plugin-<name>` by default, or `packages/` if `--core` is used).
|
||||
- **Develop**: `pnpm dev` triggers hot-reloading via `dev:plugins` watch script.
|
||||
- **Publish**: `node packages/wwv-cli/dist/index.js publish <name> [--org <your-org>]` publishes the plugin from the project root. Commit and push from inside `local-plugins/` to contribute back to the community repo.
|
||||
|
||||
### 2. Data Engine Seeders
|
||||
Seeders in `wwv-data-engine/src/seeders/` provide the backend data.
|
||||
- **Cron Seeder**: Uses `registerSeeder({ name: "plugin-id", cron: "..." })` and pushes to Redis via `setLiveSnapshot()`.
|
||||
- **Init Seeder**: High-frequency or persistent websockets via `init: () => void`.
|
||||
- **Constraint**: Seeder `name` MUST exactly match the frontend plugin `id`. Do not bundle workspace dependencies like `ws` or `zod` into the seeder `dist`.
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
description: Guidelines on managing the single source of truth across WorldWideView using Zustand, avoiding prop-drilling, and isolating UI rerenders.
|
||||
paths:
|
||||
- "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.
|
||||
@@ -0,0 +1,125 @@
|
||||
param (
|
||||
[Parameter(Mandatory=$true, HelpMessage="Base Git SHA")]
|
||||
[string]$BaseSha,
|
||||
|
||||
[Parameter(Mandatory=$true, HelpMessage="Head Git SHA")]
|
||||
[string]$HeadSha,
|
||||
|
||||
[Parameter(Mandatory=$false, HelpMessage="Path to ADR or Requirements File")]
|
||||
[string]$RequirementsFile = "",
|
||||
|
||||
[Parameter(Mandatory=$false, HelpMessage="Brief description of the implemented changes")]
|
||||
[string]$Description = "Implemented recent changes as per requirements.",
|
||||
|
||||
[Parameter(Mandatory=$false, HelpMessage="Model to use")]
|
||||
[string]$Model = "gemini-2.5-flash"
|
||||
)
|
||||
|
||||
# Set strict error handling
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
Write-Host "Gathering Code Review Context..." -ForegroundColor Cyan
|
||||
|
||||
# Ensure local-scripts directory exists
|
||||
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
|
||||
$WorkspaceRoot = Split-Path -Parent $ScriptDir
|
||||
$TempPromptFile = Join-Path $ScriptDir "pr-review-prompt.txt"
|
||||
|
||||
# 1. Fetch Requirements text if provided
|
||||
$RequirementsText = "No specific requirements provided."
|
||||
if ($RequirementsFile -ne "") {
|
||||
if (Test-Path $RequirementsFile) {
|
||||
$RequirementsText = Get-Content $RequirementsFile -Raw
|
||||
} else {
|
||||
Write-Warning "Requirements file not found at $RequirementsFile"
|
||||
}
|
||||
}
|
||||
|
||||
# 2. Extract git diff
|
||||
Write-Host "Extracting diff between $BaseSha and $HeadSha..." -ForegroundColor DarkGray
|
||||
try {
|
||||
$DiffOutput = git diff $BaseSha..$HeadSha
|
||||
if ([string]::IsNullOrWhiteSpace($DiffOutput)) {
|
||||
Write-Host "No changes found between $BaseSha and $HeadSha." -ForegroundColor Yellow
|
||||
exit 0
|
||||
}
|
||||
} catch {
|
||||
Write-Error "Failed to execute git diff. Ensure you are in a git repository and the SHAs are valid."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# 3. Construct the Reviewer Prompt
|
||||
$ReviewerPrompt = @"
|
||||
You are a Senior Code Reviewer with expertise in software architecture, design patterns, and best practices. Your job is to review completed work against its plan or requirements and identify issues before they cascade. You are a sub-agent for Antigravity. Output ONLY the review format below. DO NOT use tools.
|
||||
|
||||
## What Was Implemented
|
||||
$Description
|
||||
|
||||
## Requirements / Plan
|
||||
$RequirementsText
|
||||
|
||||
## Git Range to Review
|
||||
**Base:** $BaseSha
|
||||
**Head:** $HeadSha
|
||||
|
||||
```diff
|
||||
$DiffOutput
|
||||
```
|
||||
|
||||
## What to Check
|
||||
- **Plan alignment:** Does the implementation match the requirements? Are deviations justified?
|
||||
- **Code quality:** Clean separation of concerns? Proper error handling?
|
||||
- **Architecture:** Sound design decisions? Security concerns?
|
||||
- **Testing:** Edge cases covered? Integration tests?
|
||||
- **Production readiness:** Backward compatibility? Obvious bugs?
|
||||
|
||||
## Output Format
|
||||
### Strengths
|
||||
[What's well done? Be specific.]
|
||||
|
||||
### Issues
|
||||
#### Critical (Must Fix)
|
||||
[Bugs, security issues, data loss risks, broken functionality]
|
||||
#### Important (Should Fix)
|
||||
[Architecture problems, missing features, poor error handling, test gaps]
|
||||
#### Minor (Nice to Have)
|
||||
[Code style, optimization opportunities, documentation polish]
|
||||
|
||||
For each issue:
|
||||
- File:line reference
|
||||
- What's wrong
|
||||
- Why it matters
|
||||
- How to fix (if not obvious)
|
||||
|
||||
### Recommendations
|
||||
[Improvements for code quality, architecture, or process]
|
||||
|
||||
### Assessment
|
||||
**Ready to merge?** [Yes | No | With fixes]
|
||||
**Reasoning:** [1-2 sentence technical assessment]
|
||||
"@
|
||||
|
||||
# 4. Save to temporary file
|
||||
$ReviewerPrompt | Set-Content $TempPromptFile -Encoding UTF8
|
||||
|
||||
# 5. Dispatch to Gemini CLI
|
||||
Write-Host "Dispatching to Gemini CLI ($Model)..." -ForegroundColor Cyan
|
||||
Write-Host "Depending on the diff size, this may take 30-60 seconds." -ForegroundColor DarkGray
|
||||
|
||||
$GeminiCmd = "$env:APPDATA\npm\gemini.cmd"
|
||||
if (-Not (Test-Path $GeminiCmd)) {
|
||||
Write-Error "Gemini CLI not found at $GeminiCmd. Ensure it is installed globally via npm."
|
||||
exit 1
|
||||
}
|
||||
|
||||
try {
|
||||
Get-Content $TempPromptFile -Raw | & $GeminiCmd -m $Model
|
||||
Write-Host "`nCode Review Complete." -ForegroundColor Green
|
||||
} catch {
|
||||
Write-Error "Failed to execute Gemini CLI. If you received a 429 RESOURCE_EXHAUSTED error, try changing the model (e.g. -Model gemini-1.5-pro)."
|
||||
} finally {
|
||||
# Clean up temp file
|
||||
if (Test-Path $TempPromptFile) {
|
||||
Remove-Item $TempPromptFile -Force
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"env": {
|
||||
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
|
||||
},
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Read(src/**)",
|
||||
"Bash(npm test)"
|
||||
],
|
||||
"deny": [
|
||||
"Read(.env)",
|
||||
"Write(config.json)"
|
||||
],
|
||||
"defaultMode": "bypassPermissions"
|
||||
},
|
||||
"prefersReducedMotion": false
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
name: architectural-decision-records
|
||||
description: Use when making significant architectural decisions, adding new patterns, or altering core workflows. This skill ensures that all major technical choices are documented via ADRs.
|
||||
---
|
||||
|
||||
# Architectural Decision Records (ADRs)
|
||||
|
||||
## When to use this skill
|
||||
Trigger this skill whenever you are about to introduce a new architectural pattern, make a load-bearing contract change, or bypass an established standard for a necessary reason.
|
||||
|
||||
## Guidelines
|
||||
1. **Never make a major architectural change without an ADR**.
|
||||
2. Store ADRs in `docs/architecture/decisions/` (create this directory if it doesn't exist).
|
||||
3. Name ADR files using the pattern `adr-00##-name.md` (e.g., `adr-0001-use-postgresql.md`).
|
||||
4. An ADR must follow this exact structure:
|
||||
- **Title**: Short, descriptive noun phrase.
|
||||
- **Context**: What is the problem we are solving? What forces are at play? (Be objective).
|
||||
- **Decision**: What is the specific change or pattern we are adopting?
|
||||
- **Consequences**: What becomes easier because of this change? What becomes harder? (There are always trade-offs).
|
||||
|
||||
## Actionable Steps
|
||||
When tasked with a major architecture change, pause and explicitly state: *"This requires an Architectural Decision Record."* Draft the ADR and ask the user to approve the reasoning *before* writing the implementation code.
|
||||
@@ -0,0 +1,256 @@
|
||||
---
|
||||
name: migrate-legacy-plugin
|
||||
description: Use when moving a WorldWideView plugin from packages/ to local-plugins/ (the wwv-plugins community repo clone), converting legacy plugins to the new Engine & Payload architecture, or when a plugin hardcodes engine URLs, bundles Node.js built-ins, or uses import.meta.url for file paths inside Docker containers
|
||||
---
|
||||
|
||||
# Migrate Legacy Plugin to Modern Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
Moves a WorldWideView plugin from the old `packages/` monorepo location into the `local-plugins/` directory (which is a git clone of `github.com/silvertakana/wwv-plugins` — the canonical community plugin repo). Simultaneously fixes two **independent** concerns that legacy plugins always have:
|
||||
|
||||
1. **Frontend routing** — hardcoded engine URLs must be replaced with `resolveEngineUrl()`
|
||||
2. **Backend seeder build** — ESM bundling and container-aware file paths
|
||||
|
||||
**Core principle:** These are two separate problems in two separate codebases. Never fix one and forget the other.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Moving a plugin from `packages/wwv-plugin-<name>/` to `local-plugins/wwv-plugin-<name>/`
|
||||
- Plugin's `fetch()` hardcodes a URL like `https://dataengine.worldwideview.dev`
|
||||
- Plugin uses `this.context?.apiBaseUrl` instead of `resolveEngineUrl()`
|
||||
- Backend seeder crashes with `Dynamic require` or `ERR_INVALID_FILE_URL_PATH` in Docker
|
||||
- Seeder uses `fileURLToPath(import.meta.url)` for locating seed data files
|
||||
- Plugin builds with `tsc` instead of `tsup`/`vite`
|
||||
|
||||
**Do NOT use for:**
|
||||
- Creating a brand-new plugin from scratch → use `worldwideview-plugin-creation` skill
|
||||
- Modifying rendering or Cesium primitives → see `cesium-rendering` rule
|
||||
- Debugging state management → see `state-management` rule
|
||||
|
||||
## The Two Independent Concerns
|
||||
|
||||
> [!TIP]
|
||||
> **Automated Migration Script**
|
||||
> A new automation script is available! Before doing this manually, simply run:
|
||||
> ```bash
|
||||
> node scripts/migrate-plugin.mjs <plugin-name>
|
||||
> ```
|
||||
> Example: `node scripts/migrate-plugin.mjs gps-jamming`
|
||||
>
|
||||
> The script will automatically copy the frontend plugin, inject peerDependencies, refactor `index.tsx` routing, and fix the backend seeder's build settings and `SEEDERS_DIR` paths. (Fresh-install seeding no longer involves a hard-coded list — once published to npm with a valid `worldwideview` block, the plugin is registered via the signed verified registry.)
|
||||
> **You still need to run `pnpm install` and verify the builds manually as described below.**
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Legacy plugins always have BOTH of these problems. They are independent — you can fix one without the other, but you MUST fix both. Do not get tunnel-visioned into only fixing one.
|
||||
|
||||
| Concern | Where | Symptom | Fix |
|
||||
|---|---|---|---|
|
||||
| **Frontend routing** | `local-plugins/wwv-plugin-<name>/src/index.ts` | Plugin always hits cloud engine, ignores local dev engine | Use `context.getEngineUrl()` |
|
||||
| **Backend build** | `local-seeders/<namespace>/packages/<name>/` | Container crashes on startup with ESM errors | `tsup --format esm --target es2022`, use `SEEDERS_DIR` |
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Move the Plugin Directory
|
||||
|
||||
Copy the plugin from `packages/` (or the external plugins repo) to `local-plugins/`:
|
||||
|
||||
```bash
|
||||
# From project root (if in local packages/)
|
||||
cp -r packages/wwv-plugin-<name> local-plugins/wwv-plugin-<name>
|
||||
|
||||
```
|
||||
|
||||
The `local-plugins/` directory is:
|
||||
- Part of the pnpm workspace (`pnpm-workspace.yaml` includes `local-plugins/*`)
|
||||
- Gitignored from the main worldwideview repo — it IS its own git repo (`github.com/silvertakana/wwv-plugins`, the canonical community plugin repo)
|
||||
- Auto-discovered by the `dev:plugins` watcher during `pnpm dev`
|
||||
- Run `cd local-plugins && git pull` before working to fetch the latest community plugins
|
||||
|
||||
## Step 2: Fix Frontend Routing (getEngineUrl)
|
||||
|
||||
This is the fix that gets missed most often. Legacy plugins typically hardcode their engine URL or use messy dynamic imports.
|
||||
|
||||
```typescript
|
||||
// ❌ LEGACY — always hits cloud, ignores local engine
|
||||
const baseUrl = this.context?.apiBaseUrl || "https://dataengine.worldwideview.dev";
|
||||
const res = await fetch(`${baseUrl}/api/myplugin`);
|
||||
|
||||
// ❌ BAD (Previous Workaround) — creates bundling chunks and causes 404s
|
||||
const { resolveEngineUrl } = await import("@/core/data/resolveEngineUrl");
|
||||
const wsUrl = resolveEngineUrl(this.id);
|
||||
const engineBase = wsUrl.replace(/^ws/, 'http').replace(/\/stream$/, '');
|
||||
const res = await fetch(`${engineBase}/api/myplugin`);
|
||||
```
|
||||
|
||||
The correct approach uses `this.context.getEngineUrl()` provided by the Host when the plugin is initialized. The Host automatically handles checking `localhost:5000/manifest`, applying `getServerConfig().streamUrl`, reading `plugin.json`, or falling back to the cloud.
|
||||
|
||||
```typescript
|
||||
// ✅ MODERN — resolves local-first, respects split-routing, clean code
|
||||
async fetch(_timeRange: TimeRange): Promise<GeoEntity[]> {
|
||||
try {
|
||||
const engineBase = this.context!.getEngineUrl();
|
||||
const res = await globalThis.fetch(`${engineBase}/api/${this.id}`);
|
||||
if (!res.ok) throw new Error(`Backend returned ${res.status}`);
|
||||
|
||||
const data = await res.json();
|
||||
return this.mapPayloadToEntities(data);
|
||||
} catch (err) {
|
||||
console.error(`[${this.id}] Fetch error:`, err);
|
||||
return [];
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If the plugin is WebSocket-only (`getPollingInterval()` returns 0 and `fetch()` returns `[]`), the frontend routing is handled automatically by `DataBusSubscriber` and `WsClient`. No changes needed to the plugin class — but verify the seeder ID matches.
|
||||
|
||||
### Why This Matters
|
||||
|
||||
Without this fix, running `pnpm dev:all` starts a local engine at `localhost:5000` with your seeder, but the frontend plugin ignores it and hits the cloud. You'll see stale or missing data and waste time debugging the wrong layer.
|
||||
|
||||
## Step 3: Update package.json
|
||||
|
||||
Ensure the plugin's `package.json` follows the modern format:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@worldwideview/wwv-plugin-<name>",
|
||||
"version": "1.0.0",
|
||||
"main": "dist/frontend.mjs",
|
||||
"types": "src/index.ts",
|
||||
"type": "module",
|
||||
"module": "dist/frontend.mjs",
|
||||
"files": ["src"],
|
||||
"worldwideview": {
|
||||
"id": "<name>",
|
||||
"icon": "IconName",
|
||||
"category": "category-name",
|
||||
"format": "bundle",
|
||||
"capabilities": ["layer"]
|
||||
},
|
||||
"peerDependencies": {
|
||||
"@worldwideview/wwv-plugin-sdk": "^1.4.10"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "vite build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Key differences from legacy:
|
||||
- `"main"` points to `dist/frontend.mjs` (not `src/index.ts`)
|
||||
- Has `"type": "module"` and `"module"` field
|
||||
- Uses `peerDependencies` (not `dependencies`) for SDK
|
||||
- Uses `"workspace:*"` only for libraries that must be linked locally (e.g., `wwv-lib-incidents`)
|
||||
|
||||
## Step 4: Ensure Vite Build Config
|
||||
|
||||
Every `local-plugins/` plugin needs this `vite.config.ts`:
|
||||
|
||||
```typescript
|
||||
import { defineConfig } from "vite";
|
||||
import { wwvPluginGlobals } from "@worldwideview/wwv-plugin-sdk";
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [wwvPluginGlobals()],
|
||||
build: {
|
||||
lib: {
|
||||
entry: "src/index.ts",
|
||||
formats: ["es"],
|
||||
fileName: () => "frontend.mjs",
|
||||
},
|
||||
minify: true,
|
||||
sourcemap: false,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
`wwvPluginGlobals()` externalizes React, Cesium, Resium, zustand, and the SDK so the plugin doesn't bundle its own copies.
|
||||
|
||||
## Step 5: Fix Backend Seeder (if applicable)
|
||||
|
||||
If the plugin has a corresponding seeder in `local-seeders/`, fix two things:
|
||||
|
||||
### 5a. ESM Build
|
||||
|
||||
Legacy seeders built with `tsc` or bundled Node built-ins. Fix:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"build": "tsup src/index.ts --format esm --target es2022 --clean"
|
||||
}
|
||||
```
|
||||
|
||||
This produces clean ESM that the data engine can `import()` without `Dynamic require` errors.
|
||||
|
||||
### 5b. Container-Aware File Paths
|
||||
|
||||
Legacy seeders used `fileURLToPath(import.meta.url)` to locate seed data. This breaks inside Docker because the transpiled path doesn't match the container filesystem.
|
||||
|
||||
```typescript
|
||||
// ❌ LEGACY — breaks in Docker container
|
||||
import { fileURLToPath } from "url";
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const dataPath = path.join(__dirname, "data", "seed.json");
|
||||
|
||||
// ✅ MODERN — works everywhere
|
||||
const dataPath = process.env.SEEDERS_DIR
|
||||
? path.join(process.env.SEEDERS_DIR, "community", "packages", "<name>", "data", "seed.json")
|
||||
: path.resolve(process.cwd(), "data", "seed.json");
|
||||
```
|
||||
|
||||
`SEEDERS_DIR` is set by the Docker container to `/app/seeders`. When running locally outside Docker, the fallback uses `process.cwd()`.
|
||||
|
||||
### 5c. Seeder Directory Naming
|
||||
|
||||
The folder name inside `local-seeders/community/packages/` or `local-seeders/private/packages/` **must exactly match** the plugin's string ID (`this.id` in `index.tsx`).
|
||||
|
||||
The `wwv-data-engine`'s auto-discovery logic (`seeder-loader.ts`) derives the internal plugin ID from the directory name. If the folder is named `gpsjam` but the frontend plugin expects `gps-jamming`, the frontend will not find it in the `/manifest` and will silently fall back to the cloud engine, breaking local testing.
|
||||
|
||||
```bash
|
||||
# ❌ INCORRECT (Frontend expects "gps-jamming")
|
||||
local-seeders/community/packages/gpsjam/
|
||||
|
||||
# ✅ CORRECT
|
||||
local-seeders/community/packages/gps-jamming/
|
||||
```
|
||||
|
||||
## Step 6: Clean Up packages/ References
|
||||
|
||||
After moving to `local-plugins/`, remove the old references:
|
||||
|
||||
- [ ] Delete `packages/wwv-plugin-<name>/` directory
|
||||
- [ ] Remove from `transpilePackages` in `next.config.ts` (if present)
|
||||
- [ ] Remove path alias from `tsconfig.json` `paths` (if present)
|
||||
- [ ] Remove any registration in `AppShell.tsx` (now loaded dynamically)
|
||||
- [ ] Run `pnpm install` from project root
|
||||
|
||||
## Step 7: Verify
|
||||
|
||||
```bash
|
||||
# 1. Start everything
|
||||
pnpm dev:all
|
||||
|
||||
# 2. Check engine discovered the seeder (if applicable)
|
||||
curl http://localhost:5000/manifest
|
||||
# Should include your plugin ID
|
||||
|
||||
# 3. Check frontend console — should show:
|
||||
# [EngineManifest] Local engine detected: N seeders ["your-plugin", ...]
|
||||
# NOT: fetching from https://dataengine.worldwideview.dev
|
||||
|
||||
# 4. Toggle the layer on the globe — entities should render
|
||||
```
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
- [ ] Plugin copied from `packages/` (or external repo) to `local-plugins/`
|
||||
- [ ] Frontend `fetch()` uses `this.context.getEngineUrl()` (not hardcoded URLs or dynamic imports)
|
||||
- [ ] `package.json` has `"type": "module"`, `"main": "dist/frontend.mjs"`
|
||||
- [ ] `vite.config.ts` uses `wwvPluginGlobals()` externalization
|
||||
- [ ] Backend seeder builds with `tsup --format esm --target es2022` (if applicable)
|
||||
- [ ] Backend seeder uses `process.env.SEEDERS_DIR` for file paths (if applicable)
|
||||
- [ ] Old source directory deleted
|
||||
- [ ] Old `transpilePackages`/`tsconfig paths` entries removed
|
||||
- [ ] `pnpm install` run from root
|
||||
- [ ] `pnpm dev:all` → local engine detected → data renders on globe
|
||||
@@ -0,0 +1,72 @@
|
||||
---
|
||||
name: playwright-testing
|
||||
description: Use when creating or modifying Playwright end-to-end tests, especially when injecting mock plugins to test platform features.
|
||||
---
|
||||
|
||||
# Playwright E2E Testing & Mock Plugin Guide
|
||||
|
||||
When you are tasked with testing a new feature or plugin in WorldWideView using Playwright, you must use this skill to ensure you follow the strict architecture rules of the platform.
|
||||
|
||||
## 1. Mock Plugin Requirements
|
||||
When creating a mock plugin (e.g., `public/e2e-fixtures/my-mock-plugin.js`) to test a specific UI feature, **you MUST implement the full Data Plugin interface**.
|
||||
|
||||
WorldWideView's `PluginManager` throws fatal runtime errors if a plugin is missing core data fetching methods, even if your plugin only tests a UI component like a bottom panel.
|
||||
|
||||
**Required Methods for EVERY Mock Plugin:**
|
||||
```javascript
|
||||
export default {
|
||||
id: "my-mock-plugin",
|
||||
name: "My Mock Plugin",
|
||||
// ...
|
||||
// MUST BE INCLUDED:
|
||||
fetch: async (timeRange) => { return []; },
|
||||
getPollingInterval: () => { return 60000; },
|
||||
getLayerConfig: () => { return { color: "#FFF", clusterEnabled: false, clusterDistance: 50 }; },
|
||||
renderEntity: (entity) => { return { type: "point", color: "#FFF", size: 5 }; },
|
||||
|
||||
// Your UI testing component (e.g., Sidebar, Bottom Panel)
|
||||
getBottomPanelComponent: () => { ... }
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Mock Plugin Manifest Capabilities
|
||||
If your mock plugin needs to be toggled by the user in the Layers list, you MUST include the `"ui:sidebar"` capability in its `manifest.json`.
|
||||
```json
|
||||
{
|
||||
"capabilities": ["ui:bottom-panel", "ui:sidebar"],
|
||||
"extends": ["sidebar"]
|
||||
}
|
||||
```
|
||||
|
||||
## 3. Database Injection
|
||||
The frontend reads plugins from the database. You MUST inject your mock plugin during `tests/global.setup.ts` using Prisma:
|
||||
|
||||
```typescript
|
||||
const manifestPath = path.join(process.cwd(), 'public', 'e2e-fixtures', 'my-mock-plugin-manifest.json');
|
||||
const manifestStr = fs.readFileSync(manifestPath, 'utf-8');
|
||||
await prisma.installedPlugin.create({
|
||||
data: {
|
||||
pluginId: 'my-mock-plugin',
|
||||
version: '1.0.0',
|
||||
config: manifestStr,
|
||||
enabled: true
|
||||
}
|
||||
});
|
||||
```
|
||||
Make sure to add your new mock plugin ID to the cleanup logic in `global.setup.ts` as well:
|
||||
```typescript
|
||||
await prisma.installedPlugin.deleteMany({
|
||||
where: { pluginId: { in: ['e2e-mock-plugin', 'my-mock-plugin'] } }
|
||||
});
|
||||
```
|
||||
|
||||
## 4. UI Selectors
|
||||
**DO NOT use CSS classes for your locators.** CSS classes change frequently (e.g., `.dock-btn`, `.layer-item__toggle`).
|
||||
You MUST either:
|
||||
1. Add explicit `data-testid` attributes to the React components you are testing.
|
||||
2. Use stable accessibility locators (e.g., `getByRole('button', { name: /Text/ })`).
|
||||
|
||||
## 5. Execution Environment
|
||||
- Ensure `pnpm run dev:backends` is running before you execute tests locally.
|
||||
- Run tests using `pnpm run test:e2e` or `npx playwright test tests/your-test.spec.ts`.
|
||||
- **PowerShell Warning**: Remember you are running in Windows PowerShell. Do NOT chain commands with `&&`. Use `;` instead.
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
name: using-git-worktrees
|
||||
description: Use when tasked with creating a new git worktree, building features in isolation, setting up parallel branches, or provisioning a safe sandbox environment to test architectural changes.
|
||||
---
|
||||
|
||||
# Using Git Worktrees (Worktrunk)
|
||||
|
||||
## Overview
|
||||
Git worktrees allow you to check out multiple branches of a repository simultaneously without cloning the entire repository from scratch. However, creating worktrees in nested subdirectories breaks relative path resolutions to peer monorepo packages. We use **Worktrunk** (`git-wt`) to automatically provision sibling worktrees and handle environment setup.
|
||||
|
||||
## When to Use
|
||||
- When asked to create an isolated environment for a feature or branch.
|
||||
- When you need a safe sandbox to test destructive or complex architectural changes.
|
||||
- When working on multiple GitHub issues in parallel.
|
||||
|
||||
## Core Directives
|
||||
|
||||
### 1. NEVER Nest Worktrees
|
||||
If you create a worktree inside a subdirectory of the current repo (e.g., `.agents/worktrees/feature`), all relative paths going UP and OUT of the repository (like `../../wwv-data-engine`) will immediately break due to the altered directory depth.
|
||||
|
||||
**Worktrees MUST be siblings of the main repository root.**
|
||||
|
||||
### 2. ALWAYS Use Worktrunk
|
||||
Do not use raw `git worktree add`. Always use the `git-wt` alias provided by Worktrunk. It is pre-configured via `.config/wt.toml` to:
|
||||
- Automatically place the worktree in the correct sibling path.
|
||||
- Automatically run `pnpm install`.
|
||||
- Automatically copy `.env` files so the environment works immediately.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **For AI Agents:** You MUST append the `--yes` flag when creating worktrees to bypass the interactive approval prompt for these hooks, otherwise the command will fail in your non-interactive shell.
|
||||
|
||||
### 3. Database Lifecycle & Port Assignment
|
||||
Each worktree gets a deterministic PostgreSQL port assigned automatically based on its directory hash (to avoid collisions between multiple running worktrees).
|
||||
|
||||
> [!CAUTION]
|
||||
> **Orphaned Volumes:** You MUST use `git-wt remove` to delete worktrees. This triggers a `pre-remove` hook that cleanly tears down the Docker database. If you manually delete the folder (`rm -rf`), the Docker volume is orphaned. If this happens, run `pnpm run db:prune` in the main repository to garbage collect orphaned database volumes.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Action | Command | Details |
|
||||
| :--- | :--- | :--- |
|
||||
| **Create Worktree** | `git-wt switch --create <branch> --yes` | Provisions the sibling directory, branch, env files, and dependencies. |
|
||||
| **Delete Worktree** | `git-wt remove` | Deletes the worktree and the associated branch cleanly. Run from within the worktree. |
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Run the create command from the main repository (always include `--yes`):
|
||||
```bash
|
||||
git-wt switch --create feature/my-new-idea --yes
|
||||
```
|
||||
2. **CRITICAL:** Change your working directory to the newly created worktree before editing files. Worktrunk creates it as a sibling.
|
||||
```bash
|
||||
# Example if the main repo is c:\dev\worldwideview
|
||||
cd ../worldwideview.feature-my-new-idea
|
||||
```
|
||||
3. Do your work, run tests, and commit.
|
||||
4. When completely finished and merged, clean up by running `git-wt remove` from inside the worktree directory.
|
||||
|
||||
## Common Mistakes & Red Flags
|
||||
|
||||
| Excuse / Rationalization | Reality & Fix |
|
||||
| :--- | :--- |
|
||||
| "I'll just put the worktree in `.agents/worktrees` to keep the project folder clean." | **Red Flag:** This breaks relative paths to other monorepo packages. Delete the worktree and use `git-wt` to create a sibling worktree instead. |
|
||||
| "I'll use `git worktree add` instead of `git-wt` because it's standard." | **Red Flag:** Raw git won't copy `.env` files or run the `pre-start` hooks for `pnpm install`, leaving you with a broken environment. Delete and use `git-wt`. |
|
||||
| "I ran the command, but my file edits are applying to the main branch." | You forgot to `cd` into the newly created sibling directory. |
|
||||
@@ -0,0 +1,17 @@
|
||||
# TSDoc Review Log
|
||||
|
||||
This document tracks the progress of the codebase-wide TSDoc update.
|
||||
|
||||
## Ambiguous Functions Requiring 3.1 Pro Review
|
||||
If a function's purpose cannot be deduced from its signature or body, it is listed here along with its file path and the specific confusion.
|
||||
|
||||
| File Path | Function/Interface Name | Reason for Ambiguity |
|
||||
| :--- | :--- | :--- |
|
||||
<!-- Flash: Append rows here as you work -->
|
||||
|
||||
## Completed Directories
|
||||
- [/] `src/core/plugins` (In Progress: PluginRegistry.ts documented)
|
||||
- [ ] `src/core/state`
|
||||
- [x] `src/components` (Completed: Layout, Panels, Marketplace, Timeline, UI)
|
||||
- [x] `packages/wwv-plugin-sdk`
|
||||
- [x] `scripts`
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
name: researching-plugins
|
||||
description: Use when evaluating new data sources, researching APIs, or planning a new plugin structure, before writing any implementation code
|
||||
---
|
||||
|
||||
# Researching Plugins
|
||||
|
||||
## Overview
|
||||
This skill defines the rigorous process for researching, evaluating, and planning new data source plugins for WorldWideView. It combines data source validation (evaluating free tiers, rate limits, and comprehensiveness) with the generation of a placeholder-free, TDD-focused implementation plan.
|
||||
|
||||
## When to Use
|
||||
- The user requests a new data source or layer (e.g., "add weather data", "track global earthquakes")
|
||||
- You need to evaluate an API or dataset for continuous polling and 3D globe visualization
|
||||
- You are formulating the implementation steps for a new plugin
|
||||
- *Do not use* if the plugin is already fully planned and you are just executing tasks
|
||||
|
||||
## 1. Research & Evaluation Process
|
||||
|
||||
### Step 1: Take Inspiration from WorldMonitor
|
||||
Before searching the web blindly, check if the `koala73/worldmonitor` repository already implements a similar feature.
|
||||
- Review their data sources, API endpoints, and polling intervals.
|
||||
- Analyze which data fields they map for visualization.
|
||||
- Use this as a baseline for what is possible and expected.
|
||||
|
||||
### Step 2: Validate Data Sources
|
||||
Search for APIs that meet the following strict criteria. If an API fails these, keep searching or ask the user for guidance:
|
||||
- **Cost**: Prioritize highly robust free tiers or completely open data.
|
||||
- **Comprehensiveness**: Does it provide global coverage? Does it return coordinates (lat/lon) and identifying metadata?
|
||||
- **Rate Limits**: Can it support the required polling interval? (Real-time data needs high rate limits).
|
||||
- **Format**: JSON or GeoJSON is preferred.
|
||||
|
||||
## 2. Draft the Implementation Plan
|
||||
|
||||
Once the data source and API are validated, you MUST write a comprehensive implementation plan using the standards from the `writing-plans` skill.
|
||||
|
||||
Save the research and plan to `.agents/context/YYYY-MM-DD-<plugin-name>-research.md`.
|
||||
|
||||
### Required Plan Header
|
||||
```markdown
|
||||
# [Plugin Name] Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** [One sentence describing what this plugin does]
|
||||
**Data Source:** [API Name, API URL, Auth Method, Rate Limits]
|
||||
**Architecture:** [Proxy route, Static Data, or Microservice?]
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### Bite-Sized Task Structure
|
||||
Each task in the plan MUST follow a strict TDD, action-by-action sequence.
|
||||
|
||||
**Required Task Format:**
|
||||
```markdown
|
||||
### Task N: [Component Name]
|
||||
|
||||
**Files:**
|
||||
- Create: `packages/wwv-plugin-[name]/src/index.ts`
|
||||
- Test: `packages/wwv-plugin-[name]/test/index.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
[Include full test code block here]
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
Run: `pnpm test`
|
||||
Expected: FAIL
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
[Include full implementation code block here]
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
Run: `pnpm test`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
[Include git commit command]
|
||||
```
|
||||
|
||||
## The Iron Law of Plan Writing
|
||||
|
||||
1. **No Placeholders:** You MUST provide the exact file paths and complete code blocks for every step. Do not write "TODO: Add error handling" or "Add validation here."
|
||||
2. **Exact File Paths Always:** Define exactly where files live (e.g., `src/app/api/...`).
|
||||
3. **DRY & YAGNI:** Do not add speculative features or abstract prematurely.
|
||||
4. **Define the Types First:** Ensure the API response interfaces and the plugin manifest types are defined early in the plan.
|
||||
|
||||
## Common Mistakes & Rationalizations
|
||||
|
||||
| Excuse / Rationalization | Reality / Fix |
|
||||
|--------------------------|---------------|
|
||||
| "I'll propose a paid API because the free ones are hard to find" | WorldWideView is a free tool; prioritize open data. Dig deeper into governmental or open-source datasets. |
|
||||
| "I left TODOs in the plan so the execution agent can fill them in" | Execution agents fail when given placeholders. The plan MUST contain the exact code to be written. |
|
||||
| "I skipped the test steps because it's just an API wrapper" | Every feature requires tests. Draft a test that mocks the API response. |
|
||||
| "I forgot to specify the architecture type" | You must decide if it's a Static, Proxy, or Microservice plugin during the research phase. |
|
||||
|
||||
## Red Flags - STOP and Start Over
|
||||
If you find yourself doing any of the following, delete your work and start over:
|
||||
- Proposing an API with a 50 requests/day limit for real-time tracking.
|
||||
- Writing a plan step that says "Implement similar to Task 2."
|
||||
- Omitting exact file paths or complete code blocks in your tasks.
|
||||
- Failing to verify if WorldMonitor has already solved this problem.
|
||||
@@ -0,0 +1,666 @@
|
||||
---
|
||||
name: worldwideview-plugin-creation
|
||||
description: Use when creating a new plugin, adding a new data source, or debugging missing plugin data in the WorldWideView project. Triggers on seeder creation, WebSocket streaming issues, plugin registration failures, manifest validation errors, GeoEntity rendering problems, or data engine integration
|
||||
---
|
||||
|
||||
# WorldWideView Plugin Creation
|
||||
|
||||
## Overview
|
||||
|
||||
A WorldWideView plugin is a self-contained data source that renders geospatial entities on a 3D Cesium globe. Every plugin implements the `WorldPlugin` interface from the SDK and connects to the **V2 Data Engine** (Fastify + Redis) that streams live data over WebSocket.
|
||||
|
||||
**Core principle:** Plugins are code bundles. The engine pushes data. The frontend renders it. There is no REST polling between frontend and engine — only WebSocket streaming.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Creating a new data layer plugin (any architecture)
|
||||
- Building a new seeder in the data engine
|
||||
- Plugin data doesn't appear on the globe
|
||||
- WebSocket subscription or split-routing issues
|
||||
- Build failures after adding a plugin package
|
||||
- Debugging `renderEntity` or entity clipping artifacts
|
||||
- Marketplace plugin installation/validation issues
|
||||
|
||||
**Do NOT use for:**
|
||||
- Modifying globe rendering primitives → see `cesium-rendering` rule
|
||||
- Zustand state management → see `state-management` rule
|
||||
- Prisma schema changes → see `database-migrations` rule
|
||||
- Monorepo/pnpm workspace issues → see `monorepo-workflow` rule
|
||||
|
||||
## Architecture Decision
|
||||
|
||||
```
|
||||
Does it need live external API data?
|
||||
├── NO → Static GeoJSON plugin (wwvStaticCompiler in vite.config.ts)
|
||||
│ No seeder needed. Place data in data/data.json.
|
||||
└── YES → Does it update more often than every 30s?
|
||||
├── NO → Cron Seeder (engine, registerSeeder with cron string)
|
||||
│ getPollingInterval() = 0, mapWebsocketPayload() required
|
||||
└── YES → Init Seeder (engine, registerSeeder with init function)
|
||||
getPollingInterval() = 0, mapWebsocketPayload() required
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Piece | Location | Purpose |
|
||||
|---|---|---|
|
||||
| Sandbox plugin | `local-plugins/wwv-plugin-<name>/` | Local development workspace for new plugins |
|
||||
| Plugin class | `packages/wwv-plugin-<name>/src/index.ts` | Implements `WorldPlugin` interface |
|
||||
| Package metadata | `packages/wwv-plugin-<name>/package.json` | `worldwideview` block with id, type, format, category |
|
||||
| Engine seeder | `wwv-seeders/src/seeders/<name>.ts` | Fetches external data → Redis → WS broadcast |
|
||||
| Build config | `next.config.ts` → `transpilePackages` | Required for monorepo packages |
|
||||
| TS alias | `tsconfig.json` → `paths` | Required for monorepo packages |
|
||||
| Registration | `src/core/plugins/PluginRegistry.ts` | Register plugin at boot |
|
||||
| WS client | `src/core/data/WsClient.ts` | Client-side WebSocket subscriptions |
|
||||
| URL resolution | `src/core/data/resolveEngineUrl.ts` | Per-plugin local vs cloud routing |
|
||||
| Manifest validation | `src/core/plugins/validateManifest.ts` | Checks required fields for CDN bundles |
|
||||
| Host globals | `src/core/plugins/hostGlobals.ts` | Injects shared deps for CDN plugins |
|
||||
|
||||
---
|
||||
|
||||
## Part 1: Frontend Plugin (WorldPlugin)
|
||||
|
||||
### 1.0 Development Workflow (Local Sandbox)
|
||||
|
||||
The standard way to develop a new plugin is using the **Local Sandbox** (`local-plugins/` directory). This keeps experimental code out of the main monorepo packages until it is ready for production.
|
||||
|
||||
1. **Scaffold**: Run `node packages/wwv-cli/dist/index.js create <name> --local` from the project root. This generates a boilerplate plugin in `local-plugins/wwv-plugin-<name>`.
|
||||
2. **Develop**: Run `pnpm dev`. The built-in file watcher (`pnpm dev:plugins`) automatically rebuilds and syncs your local plugin to `public/plugins-local/` whenever you save a file for instant hot-reloading.
|
||||
3. **Publish (Optional)**: When stable, you can use `node packages/wwv-cli/dist/index.js publish <name>` from the project root to publish the plugin to NPM (use the `--org <your-org>` flag to publish under your own NPM organization instead of `@worldwideview`). There is no need to 'link' plugins to the core monorepo manually, as the local sandbox runs natively inside the workspace.
|
||||
|
||||
### 1.1 Implement the Interface
|
||||
|
||||
Every plugin **must** implement `WorldPlugin` from `@worldwideview/wwv-plugin-sdk`:
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
WorldPlugin, PluginContext, GeoEntity,
|
||||
CesiumEntityOptions, TimeRange, LayerConfig, PluginCategory
|
||||
} from "@worldwideview/wwv-plugin-sdk";
|
||||
import { Flame } from "lucide-react";
|
||||
import pkg from "../package.json";
|
||||
|
||||
export default class WildfiresPlugin implements WorldPlugin {
|
||||
id = "wildfires";
|
||||
name = "Wildfires";
|
||||
description = "Live wildfire incidents from NASA FIRMS";
|
||||
icon = Flame;
|
||||
category: PluginCategory = "natural-disaster";
|
||||
version = pkg.version; // NEVER hardcode — always import from package.json
|
||||
|
||||
async initialize(ctx: PluginContext): Promise<void> {
|
||||
// Store context for later use (env vars, edition, callbacks)
|
||||
}
|
||||
|
||||
destroy(): void {
|
||||
// Cleanup timers, WebSocket connections, etc.
|
||||
}
|
||||
|
||||
async fetch(timeRange: TimeRange): Promise<GeoEntity[]> {
|
||||
// For WS-streamed plugins, return [] — data arrives via WsClient
|
||||
return [];
|
||||
}
|
||||
|
||||
getPollingInterval(): number {
|
||||
return 0; // 0 = no REST polling (WS-only)
|
||||
}
|
||||
|
||||
getLayerConfig(): LayerConfig {
|
||||
return {
|
||||
color: "#ef4444",
|
||||
clusterEnabled: true,
|
||||
clusterDistance: 50,
|
||||
maxEntities: 5000,
|
||||
};
|
||||
}
|
||||
|
||||
renderEntity(entity: GeoEntity): CesiumEntityOptions {
|
||||
return {
|
||||
type: "point",
|
||||
color: "#ef4444",
|
||||
size: 6,
|
||||
outlineColor: "#ffffff",
|
||||
outlineWidth: 1,
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 Required vs Optional Methods
|
||||
|
||||
**Required:**
|
||||
|
||||
| Method | Purpose |
|
||||
|---|---|
|
||||
| `initialize(ctx)` | Receive `PluginContext` (env, edition, callbacks) |
|
||||
| `destroy()` | Cleanup on shutdown |
|
||||
| `fetch(timeRange)` | Return entities (REST path). Return `[]` for WS-only |
|
||||
| `getPollingInterval()` | Polling frequency in ms. Return `0` for WS-only |
|
||||
| `getLayerConfig()` | Layer appearance (color, clustering, max entities) |
|
||||
| `renderEntity(entity)` | Per-entity Cesium rendering options |
|
||||
|
||||
**Optional (but `mapWebsocketPayload` is REQUIRED for WS-only plugins with object payloads):**
|
||||
|
||||
| Method | Purpose |
|
||||
|---|---|
|
||||
| `getServerConfig()` | REST/WS endpoint config (`apiBasePath`, `streamUrl`) |
|
||||
| `getSelectionBehavior(entity)` | Trail/fly-to on entity click |
|
||||
| `getFilterDefinitions()` | User-facing filter controls |
|
||||
| `getLegend()` | Legend entries for layer panel |
|
||||
| `getSidebarComponent()` | Custom sidebar React component |
|
||||
| `getDetailComponent()` | Custom detail panel for selected entity |
|
||||
| `getSettingsComponent()` | Plugin settings UI |
|
||||
| `getGlobeComponent()` | React component injected into globe view |
|
||||
| `mapWebsocketPayload(payload, existing)` | **Required if seeder payload is an object** (not a flat array). Transforms raw engine payload → `GeoEntity[]`. Without it, `WsClient` drops object payloads silently. |
|
||||
| `requiresConfiguration(settings)` | Return `true` if plugin needs setup first |
|
||||
|
||||
### 1.3 Package Metadata
|
||||
|
||||
The `package.json` **must** include a `worldwideview` block:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@worldwideview/wwv-plugin-wildfires",
|
||||
"version": "1.0.0",
|
||||
"main": "src/index.ts",
|
||||
"worldwideview": {
|
||||
"id": "wildfires",
|
||||
"type": "data-layer",
|
||||
"format": "bundle",
|
||||
"category": "natural-disaster",
|
||||
"icon": "Flame",
|
||||
"capabilities": ["data:own", "globe:overlay"]
|
||||
},
|
||||
"dependencies": {
|
||||
"@worldwideview/wwv-plugin-sdk": "workspace:*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Valid categories** (lowercase only): `aviation` · `maritime` · `military` · `conflict` · `natural-disaster` · `infrastructure` · `space` · `cyber` · `economic` · `intelligence` · `custom`
|
||||
|
||||
**Valid capabilities**: `data:own` · `data:read:{plugin}` · `ui:detail-panel` · `ui:sidebar` · `ui:toolbar` · `ui:settings` · `globe:overlay` · `globe:camera` · `storage:read` · `storage:write` · `network:fetch`
|
||||
|
||||
### 1.4 Rendering Rules
|
||||
|
||||
| Entity Type | Properties | Notes |
|
||||
|---|---|---|
|
||||
| `"point"` | `color`, `size`, `outlineColor`, `outlineWidth` | Simple colored dots |
|
||||
| `"billboard"` | `iconUrl`, `color`, `iconScale` | SVG/PNG icons |
|
||||
| `"model"` | `modelUrl`, `modelScale`, `modelMinPixelSize` | 3D glTF models |
|
||||
| `"label"` | `labelText`, `labelFont`, `color` | Text labels |
|
||||
|
||||
> **CRITICAL:** NEVER mix point and billboard properties. Using `size`/`outlineWidth` on a billboard entity causes GPU clipping artifacts. This is a hard rendering constraint.
|
||||
|
||||
Use `createSvgIconUrl()` from the SDK for billboard icons:
|
||||
|
||||
```typescript
|
||||
import { createSvgIconUrl } from "@worldwideview/wwv-plugin-sdk";
|
||||
import { Plane } from "lucide-react";
|
||||
const iconUrl = createSvgIconUrl(Plane, { color: "#3b82f6" });
|
||||
```
|
||||
|
||||
### 1.5 Registration (3 Paths)
|
||||
|
||||
**A. Built-in (monorepo package):**
|
||||
|
||||
```typescript
|
||||
import { pluginRegistry } from "@/core/plugins/PluginRegistry";
|
||||
import { pluginManager } from "@/core/plugins/PluginManager";
|
||||
import WildfiresPlugin from "@worldwideview/wwv-plugin-wildfires";
|
||||
|
||||
const plugin = new WildfiresPlugin();
|
||||
pluginRegistry.register(plugin);
|
||||
await pluginManager.registerPlugin(plugin);
|
||||
```
|
||||
|
||||
`AppShell.tsx` iterates `pluginRegistry.getAll()` at startup.
|
||||
|
||||
**B. Marketplace (database-installed):**
|
||||
`InstalledPluginsLoader` reads from the `installed_plugins` PostgreSQL table and calls `pluginManager.loadFromManifest()`. No code changes needed.
|
||||
|
||||
**C. Dynamic import (runtime):**
|
||||
For user-imported GeoJSON layers, call `pluginManager.loadFromManifest(manifest)` directly.
|
||||
|
||||
### 1.6 Build Configuration (Core Monorepo Packages Only)
|
||||
|
||||
If you decide to manually move a plugin from the local sandbox into the core `packages/` directory, you must manually add it to the build pipeline:
|
||||
|
||||
Add to `next.config.ts`:
|
||||
|
||||
```typescript
|
||||
transpilePackages: [
|
||||
"@worldwideview/wwv-plugin-sdk",
|
||||
"@worldwideview/wwv-plugin-wildfires", // ADD
|
||||
],
|
||||
```
|
||||
|
||||
Add to `tsconfig.json`:
|
||||
|
||||
```json
|
||||
"paths": {
|
||||
"@worldwideview/wwv-plugin-wildfires": ["./packages/wwv-plugin-wildfires/src"]
|
||||
}
|
||||
```
|
||||
|
||||
Run `pnpm install` from project root after creating the package.
|
||||
|
||||
---
|
||||
|
||||
## Part 2: Data Engine Seeder
|
||||
|
||||
The data engine is a **content-agnostic Host Environment runner** (`wwv-data-engine`, deployed via Docker). It runs Fastify on port 5000 with Redis caching and WebSocket streaming. Seeders are volume-mounted from `local-seeders/` (dev) or dynamically downloaded and linked via pnpm workspaces from GitHub Releases (`wwv-seeders` and `wwv-seeders-private`) in production.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> If you are **migrating** an existing plugin from `packages/` to `local-plugins/`, use the `migrate-legacy-plugin` skill instead. It covers both frontend routing fixes AND backend seeder build fixes as two independent concerns.
|
||||
|
||||
### 2.1 Engine Architecture
|
||||
|
||||
```
|
||||
External API → Seeder (fetch + transform)
|
||||
→ setLiveSnapshot(pluginId, payload, ttlSeconds)
|
||||
→ broadcastPluginData() → Active WS subscribers (immediate)
|
||||
→ Redis SET data:{pluginId}:live (throttled to every 5 min)
|
||||
→ SQLite history (optional, via better-sqlite3)
|
||||
```
|
||||
|
||||
**Key components:**
|
||||
- `src/scheduler.ts` — Seeder registry and cron scheduling
|
||||
- `src/redis.ts` — Redis client, `setLiveSnapshot()` and `getLiveSnapshot()`
|
||||
- `src/websocket.ts` — WS handler, `broadcastPluginData()`
|
||||
- `src/seed-utils.ts` — `withRetry()`, `fetchWithTimeout()`, `haversineKm()`
|
||||
- `src/db.ts` — SQLite (better-sqlite3) for local history storage
|
||||
- `src/seeders/index.ts` — Auto-discovery, dynamically requires all seeder files
|
||||
|
||||
### 2.2 Two Seeder Patterns
|
||||
|
||||
**Cron Seeder** (periodic polling — most common):
|
||||
|
||||
```typescript
|
||||
import { db } from "../db";
|
||||
import { setLiveSnapshot } from "../redis";
|
||||
import { fetchWithTimeout, withRetry } from "../seed-utils";
|
||||
import { registerSeeder } from "../scheduler";
|
||||
|
||||
// Optional: SQLite history table insert
|
||||
const insertRow = db.prepare(
|
||||
"INSERT OR IGNORE INTO my_data (id, payload, source_ts, fetched_at) VALUES (@id, @payload, @source_ts, @fetched_at)"
|
||||
);
|
||||
|
||||
async function seedMyPlugin() {
|
||||
console.log("[MyPlugin] Polling external API...");
|
||||
|
||||
const res = await withRetry(() =>
|
||||
fetchWithTimeout("https://api.example.com/data")
|
||||
);
|
||||
const data = await res.json();
|
||||
|
||||
const items = data.features.map((f: any) => ({
|
||||
id: f.id,
|
||||
lat: f.geometry.coordinates[1],
|
||||
lon: f.geometry.coordinates[0],
|
||||
name: f.properties.name,
|
||||
// ... transform to your schema
|
||||
}));
|
||||
|
||||
// Optional: save to SQLite
|
||||
for (const item of items) {
|
||||
insertRow.run({
|
||||
id: item.id,
|
||||
payload: JSON.stringify(item),
|
||||
source_ts: Date.now(),
|
||||
fetched_at: Date.now(),
|
||||
});
|
||||
}
|
||||
|
||||
// REQUIRED: Push to Redis + broadcast to WS subscribers
|
||||
await setLiveSnapshot("my-plugin", {
|
||||
source: "my-plugin",
|
||||
fetchedAt: new Date().toISOString(),
|
||||
items,
|
||||
totalCount: items.length,
|
||||
}, 3600); // TTL in seconds
|
||||
}
|
||||
|
||||
registerSeeder({
|
||||
name: "my-plugin", // MUST match the plugin's id on the frontend
|
||||
cron: "*/15 * * * *", // Every 15 minutes
|
||||
fn: seedMyPlugin,
|
||||
});
|
||||
```
|
||||
|
||||
**Init Seeder** (persistent/high-frequency — e.g., ISS every 5s):
|
||||
|
||||
```typescript
|
||||
import { setLiveSnapshot } from "../redis";
|
||||
import { registerSeeder } from "../scheduler";
|
||||
|
||||
function startMySeeder() {
|
||||
console.log("[MyPlugin] Starting persistent seeder...");
|
||||
|
||||
async function poll() {
|
||||
const res = await fetch("https://api.example.com/live");
|
||||
const data = await res.json();
|
||||
await setLiveSnapshot("my-plugin", data, 60);
|
||||
}
|
||||
|
||||
poll(); // Initial fetch
|
||||
setInterval(poll, 5000); // Every 5 seconds
|
||||
}
|
||||
|
||||
registerSeeder({
|
||||
name: "my-plugin",
|
||||
init: startMySeeder, // No cron — uses init for persistent polling
|
||||
});
|
||||
```
|
||||
|
||||
### 2.3 SeederDefinition Interface
|
||||
|
||||
```typescript
|
||||
interface SeederDefinition {
|
||||
name: string; // Plugin ID — MUST match frontend plugin id
|
||||
cron?: string; // Cron expression (e.g., "0 * * * *" = hourly)
|
||||
fn?: () => Promise<void>; // Function called on each cron tick
|
||||
init?: () => void; // Initialization for persistent seeders (websockets, intervals)
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 Auto-Discovery & Dependencies
|
||||
|
||||
The V2 engine dynamically `import()`s every compiled `.mjs` file in the extracted seeder workspaces. **You do not need to manually import your seeder** — just create the file and call `registerSeeder()` at module scope.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **V2 Engine Dependencies:** Seeders run in the unified V2 host environment which provides common packages (`zod`, `ws`, `undici`, etc.). **You MUST NOT bundle these dependencies** in your seeder's `dist` folder. Leave them externalized in your build config.
|
||||
|
||||
### 2.5 SQLite History (Optional)
|
||||
|
||||
For data that benefits from historical queries (playback mode), add a table in `src/db.ts`:
|
||||
|
||||
```typescript
|
||||
db.exec(`
|
||||
CREATE TABLE IF NOT EXISTS my_data (
|
||||
id TEXT PRIMARY KEY,
|
||||
payload JSON NOT NULL,
|
||||
source_ts INTEGER NOT NULL,
|
||||
fetched_at INTEGER NOT NULL
|
||||
)
|
||||
`);
|
||||
```
|
||||
|
||||
### 2.6 Utility Functions
|
||||
|
||||
| Function | Purpose |
|
||||
|---|---|
|
||||
| `withRetry(fn, maxRetries, delayMs)` | Exponential backoff retry wrapper |
|
||||
| `fetchWithTimeout(url, options, timeoutMs)` | Fetch with abort signal (default 15s) |
|
||||
| `haversineKm(lat1, lon1, lat2, lon2)` | Distance between coordinates in km |
|
||||
| `sleep(ms)` | Promise-based delay |
|
||||
| `CHROME_UA` | Chrome User-Agent string for scraping |
|
||||
|
||||
---
|
||||
|
||||
## Part 3: Data Pipeline (Frontend ↔ Engine)
|
||||
|
||||
### 3.1 WebSocket Protocol
|
||||
|
||||
**Client → Engine:**
|
||||
```json
|
||||
{ "action": "subscribe", "pluginId": "earthquakes" }
|
||||
{ "action": "unsubscribe", "pluginId": "earthquakes" }
|
||||
```
|
||||
|
||||
**Engine → Client:**
|
||||
```json
|
||||
{ "type": "welcome", "engine": "wwv-data-engine-v2", "plugins": ["earthquakes", "wildfires", ...] }
|
||||
{ "type": "data", "pluginId": "earthquakes", "payload": { "items": [...], "totalCount": 42 } }
|
||||
```
|
||||
|
||||
On subscribe, the engine immediately pushes the latest cached Redis snapshot — no waiting for the next cron tick.
|
||||
|
||||
### 3.2 Split-Routing (resolveEngineUrl)
|
||||
|
||||
`resolveEngineUrl(pluginId)` determines which engine serves each plugin:
|
||||
|
||||
1. **Local engine** (`localhost:5000`) if running and its `/manifest` includes this plugin ← **HIGHEST PRIORITY**
|
||||
2. Plugin's `getServerConfig().streamUrl` (code override)
|
||||
3. Plugin's `PluginManifest.dataSource.streamUrl` (manifest override)
|
||||
4. `NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL` env var
|
||||
5. Fallback: `wss://dataenginev2.worldwideview.dev/stream` (cloud)
|
||||
|
||||
### 3.3 Full Data Flow
|
||||
|
||||
```
|
||||
Engine seeder calls setLiveSnapshot(pluginId, payload, ttl)
|
||||
→ broadcastPluginData() fans out to subscribed WS connections
|
||||
→ WsClient receives { type: "data", pluginId, payload }
|
||||
→ WsClient calls plugin.mapWebsocketPayload() if defined
|
||||
→ DataBus.emit("dataUpdated", { pluginId, entities })
|
||||
→ DataBusSubscriber → Zustand store.entitiesByPlugin
|
||||
→ GlobeView (memoized visible entities)
|
||||
→ EntityRenderer (billboard/point/label primitives)
|
||||
```
|
||||
|
||||
### 3.4 Host Globals (CDN Plugins)
|
||||
|
||||
CDN-loaded plugins share the host app's dependencies via `globalThis.__WWV_HOST__`:
|
||||
- `react`, `react-dom`, `react/jsx-runtime`
|
||||
- `cesium`, `resium`
|
||||
- `zustand`
|
||||
- `@worldwideview/wwv-plugin-sdk`
|
||||
|
||||
Use `wwvPluginGlobals()` in your Vite config to externalize automatically:
|
||||
|
||||
```typescript
|
||||
import { defineConfig } from "vite";
|
||||
import { wwvPluginGlobals } from "@worldwideview/wwv-plugin-sdk";
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [wwvPluginGlobals()],
|
||||
build: {
|
||||
lib: { entry: "./src/index.ts", formats: ["es"], fileName: "frontend" },
|
||||
rollupOptions: { output: { entryFileNames: "frontend.mjs" } },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 4: Static GeoJSON Plugins
|
||||
|
||||
For plugins with static data (no live API), use `wwvStaticCompiler`:
|
||||
|
||||
```typescript
|
||||
import { defineConfig } from "vite";
|
||||
import { wwvPluginGlobals, wwvStaticCompiler } from "@worldwideview/wwv-plugin-sdk";
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [wwvStaticCompiler(), wwvPluginGlobals()],
|
||||
build: {
|
||||
lib: { entry: "./src/index.ts", formats: ["es"], fileName: "frontend" },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Place GeoJSON in `data/data.json`. The compiler auto-generates a `WorldPlugin` class from `package.json` metadata at build time. No `src/index.ts` needed.
|
||||
|
||||
---
|
||||
|
||||
## Part 5: Example - Simple ISS Tracker Plugin
|
||||
|
||||
Here is a minimal, complete example of a live ISS Tracker plugin utilizing both the frontend SDK and the V2 Engine.
|
||||
|
||||
### 1. Frontend Plugin (`local-plugins/wwv-plugin-iss/src/index.ts`)
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
WorldPlugin, PluginContext, GeoEntity,
|
||||
CesiumEntityOptions, TimeRange, LayerConfig, PluginCategory
|
||||
} from "@worldwideview/wwv-plugin-sdk";
|
||||
import { Satellite } from "lucide-react";
|
||||
import pkg from "../package.json";
|
||||
|
||||
export default class IssPlugin implements WorldPlugin {
|
||||
id = "iss";
|
||||
name = "ISS Tracker";
|
||||
description = "Real-time International Space Station tracking";
|
||||
icon = Satellite;
|
||||
category: PluginCategory = "space";
|
||||
version = pkg.version;
|
||||
|
||||
async initialize(ctx: PluginContext): Promise<void> {}
|
||||
|
||||
destroy(): void {}
|
||||
|
||||
async fetch(_timeRange: TimeRange): Promise<GeoEntity[]> {
|
||||
return []; // WS-only — data arrives via mapWebsocketPayload
|
||||
}
|
||||
|
||||
getPollingInterval(): number {
|
||||
return 0; // WS-only
|
||||
}
|
||||
|
||||
// REQUIRED: seeder sends { source, fetchedAt, items: [...], totalCount } (an object).
|
||||
// Without this, WsClient drops the payload silently — the globe stays empty.
|
||||
mapWebsocketPayload(payload: any, _existingEntities: GeoEntity[]): GeoEntity[] {
|
||||
const items: any[] = payload?.items ?? (Array.isArray(payload) ? payload : []);
|
||||
return items.map((item: any): GeoEntity => ({
|
||||
id: `iss-${item.id}`,
|
||||
pluginId: "iss",
|
||||
latitude: item.lat,
|
||||
longitude: item.lon,
|
||||
altitude: item.alt ?? 0,
|
||||
timestamp: new Date(),
|
||||
label: "International Space Station",
|
||||
properties: { speed: item.speed },
|
||||
}));
|
||||
}
|
||||
|
||||
getLayerConfig(): LayerConfig {
|
||||
return {
|
||||
color: "#ffffff",
|
||||
clusterEnabled: false,
|
||||
maxEntities: 1,
|
||||
};
|
||||
}
|
||||
|
||||
renderEntity(entity: GeoEntity): CesiumEntityOptions {
|
||||
return {
|
||||
type: "point",
|
||||
color: "#ffffff",
|
||||
size: 10,
|
||||
outlineColor: "#3b82f6",
|
||||
outlineWidth: 2,
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Backend Init Seeder (`wwv-seeders/src/seeders/iss.ts`)
|
||||
|
||||
```typescript
|
||||
import { setLiveSnapshot } from "../redis";
|
||||
import { registerSeeder } from "../scheduler";
|
||||
|
||||
function startIssSeeder() {
|
||||
console.log("[ISS] Starting live tracker...");
|
||||
|
||||
async function poll() {
|
||||
try {
|
||||
const res = await fetch("https://api.wheretheiss.at/v1/satellites/25544");
|
||||
const data = await res.json();
|
||||
|
||||
const item = {
|
||||
id: "iss",
|
||||
lat: data.latitude,
|
||||
lon: data.longitude,
|
||||
alt: data.altitude * 1000, // Convert km to meters
|
||||
name: "International Space Station",
|
||||
speed: data.velocity,
|
||||
};
|
||||
|
||||
await setLiveSnapshot("iss", {
|
||||
source: "iss",
|
||||
fetchedAt: new Date().toISOString(),
|
||||
items: [item],
|
||||
totalCount: 1,
|
||||
}, 10);
|
||||
} catch (err) {
|
||||
console.error("[ISS] Fetch failed", err);
|
||||
}
|
||||
}
|
||||
|
||||
poll(); // Initial fetch
|
||||
setInterval(poll, 5000); // Poll every 5 seconds
|
||||
}
|
||||
|
||||
registerSeeder({
|
||||
name: "iss",
|
||||
init: startIssSeeder,
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### "Sandbox Plugin Breaking Next.js Build"
|
||||
1. **Premature Configuration** — Modifying `next.config.ts` (`transpilePackages`) or `tsconfig.json` (`paths`) while a plugin is still in `local-plugins/`. The `local-plugins` sandbox relies on dynamic hot-loading in the browser via `pnpm dev:plugins`. Do **not** touch monorepo configs for local plugins.
|
||||
2. **Manual Registration** — Manually adding a sandbox plugin to `AppShell.tsx`. Let the local hot-loading manifest handle sandbox plugins dynamically.
|
||||
|
||||
### "Missing Boilerplate / Errors in package.json"
|
||||
1. **Bypassing the CLI** — Creating a plugin manually instead of using `node packages/wwv-cli/dist/index.js create <name> --local`. Always use the CLI to ensure the correct metadata, type definitions, and test scaffolding are generated.
|
||||
|
||||
### "No data on the globe"
|
||||
1. **Seeder name ≠ plugin id** — The `name` in `registerSeeder()` MUST match the `id` property of the frontend `WorldPlugin` class
|
||||
2. **Engine `/manifest` missing plugin** — Check `GET localhost:5000/manifest` → `plugins` array
|
||||
3. **WsClient not subscribing** — Add `console.log` in `resolveEngineUrl()` to verify URL resolution
|
||||
4. **Plugin hardcodes engine URL** — Legacy plugins use `this.context?.apiBaseUrl` instead of `resolveEngineUrl()`. See `migrate-legacy-plugin` skill
|
||||
4. **`mapWebsocketPayload` missing** — If the engine sends a non-standard payload shape, the plugin must implement `mapWebsocketPayload()` or data silently drops
|
||||
|
||||
### "Build crash / Module not found"
|
||||
1. Missing `transpilePackages` entry in `next.config.ts` → **immediate runtime crash**
|
||||
2. Missing `tsconfig.json` path alias → TypeScript compilation error
|
||||
3. Forgot `pnpm install` after creating package → dependency resolution failure
|
||||
|
||||
### "Invalid Hook Call" (CDN plugins)
|
||||
Plugin bundles its own React instead of using host globals. Fix: add `wwvPluginGlobals()` to Vite config.
|
||||
|
||||
### "Manifest validation failed"
|
||||
Required fields: `id`, `name`, `version`, `entry`, `trust`. Entry URL must be from allowed domains (CDN, localhost, `worldwideview.dev`, or relative path). `capabilities` must be non-empty array.
|
||||
|
||||
### "GPU clipping / entity disappearing"
|
||||
Using `size`/`outlineWidth`/`outlineColor` on a `"billboard"` entity. These properties are **point-only**. Billboard uses `iconUrl`/`iconScale`/`color`.
|
||||
|
||||
### "Redis snapshot not updating"
|
||||
`setLiveSnapshot()` throttles Redis writes to every 5 minutes to avoid exceeding Upstash request limits. WebSocket broadcasts are **not** throttled. Check WS delivery first.
|
||||
|
||||
### "Category type error"
|
||||
Categories are **lowercase**: `"aviation"` not `"Aviation"`, `"natural-disaster"` not `"NaturalDisaster"`. Must match the `PluginCategory` union in the SDK.
|
||||
|
||||
---
|
||||
|
||||
## End-to-End Checklist
|
||||
|
||||
- [ ] **Development:** Scaffolded via `node packages/wwv-cli/dist/index.js create` and developed in `local-plugins/`
|
||||
- [ ] **Publishing:** Published to NPM via `node packages/wwv-cli/dist/index.js publish <name> [--org <your-org>]` (if making public)
|
||||
- [ ] **Frontend:** Plugin class implements `WorldPlugin` with correct `id`
|
||||
- [ ] **Frontend:** `package.json` has `worldwideview` block with matching `id`
|
||||
- [ ] **Frontend:** Version imported from `package.json` (never hardcoded)
|
||||
- [ ] **Frontend:** Added to `transpilePackages` in `next.config.ts`
|
||||
- [ ] **Frontend:** Added path alias in `tsconfig.json`
|
||||
- [ ] **Frontend:** Registered via `pluginRegistry` + `pluginManager` in `AppShell.tsx`
|
||||
- [ ] **Frontend:** `renderEntity()` doesn't mix point/billboard properties
|
||||
- [ ] **Engine:** Seeder file in `wwv-seeders/src/seeders/<name>.ts` (or private repo)
|
||||
- [ ] **Engine:** `registerSeeder({ name })` matches frontend plugin `id`
|
||||
- [ ] **Engine:** Calls `setLiveSnapshot()` with correct plugin ID key
|
||||
- [ ] **Engine:** Seeder payload is either a flat `GeoEntity[]` array OR plugin implements `mapWebsocketPayload` (any other object is silently dropped by WsClient)
|
||||
- [ ] **Frontend (WS-only):** `getPollingInterval()` returns `0` and `fetch()` returns `[]`
|
||||
- [ ] **Frontend (WS-only):** `mapWebsocketPayload(payload, existingEntities)` implemented if seeder sends an object
|
||||
- [ ] **Engine:** SQLite table created in `db.ts` if historical data needed
|
||||
- [ ] **Verification:** `GET localhost:5000/manifest` includes the plugin ID
|
||||
- [ ] **Verification:** `GET localhost:5000/health` shows seeder last-run timestamp
|
||||
- [ ] **Verification:** WebSocket subscribe returns data snapshot
|
||||
- [ ] **Workspace:** Ran `pnpm install` from project root
|
||||
- [ ] **Workspace:** Version bump follows `/commit` workflow
|
||||
@@ -0,0 +1,50 @@
|
||||
node_modules
|
||||
**/node_modules
|
||||
**/dist
|
||||
**/.next
|
||||
.git
|
||||
|
||||
# Database files at ANY depth
|
||||
/data
|
||||
packages/*/data
|
||||
**/*.db
|
||||
**/*.sqlite
|
||||
**/*.sqlite3
|
||||
**/*-journal
|
||||
**/*.db-wal
|
||||
**/*.db-shm
|
||||
|
||||
# ============================================================
|
||||
# UNIGNORE FOR AI AGENT (FILTERED PATHS ONLY)
|
||||
# ============================================================
|
||||
|
||||
# Code Frameworks, Configurations & Typings
|
||||
!/out/
|
||||
!*.tsbuildinfo
|
||||
!next-env.d.ts
|
||||
!/build
|
||||
!*.code-workspace
|
||||
|
||||
# Generated Codebase Assets & Database Schemas (e.g., Prisma Client)
|
||||
!/src/generated/
|
||||
|
||||
# Permanent Local Automation and Scripts Shared in Project
|
||||
!/local-scripts/
|
||||
!/public/plugins-local/
|
||||
|
||||
# Local Structural Repositories & Workspaces
|
||||
!local-plugins/*
|
||||
!/worldmonitor/
|
||||
!local-seeders/*
|
||||
|
||||
# Complete Ecosystem Repositories (Allows Agent to Cross-Reference Layouts)
|
||||
!/packages/wwv-data-engine/
|
||||
!/worldwideview-marketplace/
|
||||
!/worldwideview-plugins/
|
||||
!/worldwideview-web/
|
||||
!/wwv-data-engine/
|
||||
!/wwv-data-engine-public/
|
||||
!/wwv-seeders/
|
||||
!/wwv-seeders-private/
|
||||
!/wwv-test/
|
||||
!worldwideview.code-workspace
|
||||
@@ -0,0 +1,14 @@
|
||||
[[pre-start]]
|
||||
install_deps = "pnpm install"
|
||||
|
||||
[[pre-start]]
|
||||
copy_env = """powershell -Command "if (Test-Path '../worldwideview/.env') { Copy-Item '../worldwideview/.env' '.env' -Force }""""
|
||||
|
||||
[[pre-start]]
|
||||
copy_local_plugins = """powershell -Command "if (Test-Path '../worldwideview/local-plugins') { robocopy '../worldwideview/local-plugins' 'local-plugins' /E /XD node_modules dist .next coverage /XF '*.log' /NFL /NDL /NJH /NJS | Out-Null }""""
|
||||
|
||||
[[pre-start]]
|
||||
copy_local_seeders = """powershell -Command "if (Test-Path '../worldwideview/local-seeders') { robocopy '../worldwideview/local-seeders' 'local-seeders' /E /XD .pnpm-store node_modules /NFL /NDL /NJH /NJS | Out-Null }""""
|
||||
|
||||
[[pre-remove]]
|
||||
docker_clean = "docker compose down -v"
|
||||
+24
-4
@@ -1,7 +1,27 @@
|
||||
node_modules
|
||||
.next
|
||||
**/node_modules
|
||||
**/dist
|
||||
**/.next
|
||||
.git
|
||||
*.md
|
||||
artifacts
|
||||
|
||||
# Database files at ANY depth
|
||||
/data
|
||||
packages/*/data
|
||||
**/*.db
|
||||
**/*.sqlite
|
||||
**/*.sqlite3
|
||||
**/*-journal
|
||||
**/*.db-wal
|
||||
**/*.db-shm
|
||||
|
||||
# Environment files
|
||||
.env*
|
||||
!.env.example
|
||||
!*.env.example
|
||||
|
||||
# Non-build directories
|
||||
artifacts/
|
||||
performance/
|
||||
tmp/
|
||||
*.geojson
|
||||
**/.pnpm-store
|
||||
local-seeders*
|
||||
@@ -1,4 +0,0 @@
|
||||
DATABASE_URL=file:./data/wwv.db
|
||||
|
||||
# Edition: "local" | "cloud" | "demo"
|
||||
NEXT_PUBLIC_WWV_EDITION=local
|
||||
+49
-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)
|
||||
@@ -13,6 +13,18 @@ DATABASE_URL=file:./data/wwv.db
|
||||
# Copy everything below into a new file called .env.local
|
||||
# .env.local is gitignored and overrides .env values.
|
||||
|
||||
# Auth Secret (REQUIRED — generate with: openssl rand -hex 32)
|
||||
# Must remain stable across restarts to preserve sessions and tokens.
|
||||
# For Docker: also set this in the host environment or a .env file
|
||||
# at the project root so docker-compose can inject it.
|
||||
AUTH_SECRET=
|
||||
|
||||
# Encryption Master Key (REQUIRED — generate with: openssl rand -hex 16)
|
||||
# Must be exactly 32 characters. Used to derive the AES-256-GCM key for credentials at rest.
|
||||
# PRE-DEPLOY GATE: verify this is set in Coolify for every environment before merging C1 changes.
|
||||
# If unset the server will refuse to start (enforced in src/instrumentation.ts).
|
||||
ENCRYPTION_MASTER_KEY=
|
||||
|
||||
# Cesium Ion Access Token (optional — get one free at https://ion.cesium.com/)
|
||||
NEXT_PUBLIC_CESIUM_ION_TOKEN=
|
||||
|
||||
@@ -25,19 +37,54 @@ NEXT_PUBLIC_BING_MAPS_KEY=
|
||||
NEXT_PUBLIC_SUPABASE_URL=
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=
|
||||
SUPABASE_SERVICE_ROLE_KEY=
|
||||
SUPABASE_DATABASE_URL=
|
||||
|
||||
# OpenSky Network — multi-account credential rotation
|
||||
# Comma-separated clientId:clientSecret pairs.
|
||||
# Example: OPENSKY_CREDENTIALS=acct1-id:acct1-secret,acct2-id:acct2-secret
|
||||
OPENSKY_CREDENTIALS=
|
||||
|
||||
# ACLED API — Civil Unrest & Conflict data (free for non-commercial use)
|
||||
# Register at https://developer.acleddata.com/ to obtain credentials.
|
||||
# Data is updated weekly (Mondays) with global protest, riot, and violence events.
|
||||
ACLED_EMAIL=
|
||||
ACLED_PASSWORD=
|
||||
|
||||
# Marketplace Bridge Token — shared secret for marketplace → WWV install requests
|
||||
# Generate any random string, then set the same value in the marketplace instance config.
|
||||
WWV_BRIDGE_TOKEN=
|
||||
|
||||
# Marketplace URL — used by ticketClient.ts for token exchange (server-side only)
|
||||
# Falls back to NEXT_PUBLIC_WWV_MARKETPLACE_URL then https://app.worldwideview.dev
|
||||
MARKETPLACE_URL=
|
||||
|
||||
# Marketplace URL — used for PKCE connect/callback and client-side links
|
||||
NEXT_PUBLIC_WWV_MARKETPLACE_URL=
|
||||
|
||||
# Plugin Ticket Auth — comma-separated plugin IDs that require WS first-message auth (ADR-001).
|
||||
# Empty (default) = ticket auth dormant for all plugins. Set AFTER Marketplace + Data Engine deploy.
|
||||
# Example: NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS=aviation,maritime
|
||||
NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS=
|
||||
|
||||
# SSRF Proxy Host Allowlist (REQUIRED in production)
|
||||
# "*" = permissive (logs WARN per request — use to observe traffic for one week, then tighten).
|
||||
# "" = deny all (safe default when not set).
|
||||
# Comma-separated list = only those hostnames allowed (e.g. "192.168.1.100,camera.example.com").
|
||||
# Ship with "*" in Coolify; replace with concrete list after one week of log observation.
|
||||
PROXY_HOST_ALLOWLIST=*
|
||||
|
||||
# Default plugins enabled on boot for demo edition
|
||||
# Comma-separated list of plugin IDs
|
||||
NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS=
|
||||
|
||||
# Edition: "local" | "cloud" | "demo"
|
||||
NEXT_PUBLIC_WWV_EDITION=local
|
||||
|
||||
# Optional Database Teardown
|
||||
# If set to true, terminating 'pnpm run dev' (Ctrl+C) will automatically
|
||||
# stop the local database container (freeing up port 5432).
|
||||
WWV_TEARDOWN_DB_ON_EXIT=false
|
||||
|
||||
# Demo Admin Secret (demo edition only)
|
||||
# Allows operator plugin management on the demo instance via x-wwv-admin-secret header.
|
||||
# Generate any random string. Only set this on the demo deployment.
|
||||
|
||||
@@ -1,37 +1,29 @@
|
||||
---
|
||||
name: Bug Report
|
||||
about: Report something that isn't working correctly
|
||||
about: Create a report to help us improve WorldWideView
|
||||
title: '[BUG] '
|
||||
labels: bug
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
## Describe the Bug
|
||||
|
||||
**Describe the bug**
|
||||
A clear and concise description of what the bug is.
|
||||
|
||||
## Steps to Reproduce
|
||||
|
||||
**To Reproduce**
|
||||
Steps to reproduce the behavior:
|
||||
1. Go to '...'
|
||||
2. Click on '...'
|
||||
3. See error
|
||||
2. Click on '....'
|
||||
3. Scroll down to '....'
|
||||
4. See error
|
||||
|
||||
## Expected Behaviour
|
||||
**Expected behavior**
|
||||
A clear and concise description of what you expected to happen.
|
||||
|
||||
What you expected to happen.
|
||||
**Screenshots/Logs**
|
||||
If applicable, add screenshots or console output to help explain your problem.
|
||||
|
||||
## Actual Behaviour
|
||||
|
||||
What actually happened. Include screenshots or console errors if applicable.
|
||||
|
||||
## Environment
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| OS | e.g. Windows 11 |
|
||||
| Browser | e.g. Chrome 122 |
|
||||
| Node.js | e.g. 20.x |
|
||||
| Plugin(s) affected | e.g. ADS-B, AIS |
|
||||
|
||||
## Additional Context
|
||||
|
||||
Any other context about the problem — relevant config, data source URLs, Cesium Ion token issues, etc.
|
||||
**Environment (please complete the following information):**
|
||||
- OS: [e.g. Windows, macOS]
|
||||
- Browser [e.g. chrome, safari, firefox]
|
||||
- WorldWideView Edition [e.g. local, demo, cloud]
|
||||
@@ -1,29 +1,19 @@
|
||||
---
|
||||
name: Feature Request
|
||||
about: Suggest a new feature or improvement
|
||||
name: Core Feature Request
|
||||
about: Suggest an idea for the core WorldWideView engine
|
||||
title: '[FEATURE] '
|
||||
labels: enhancement
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
**Is your feature request related to a problem? Please describe.**
|
||||
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
|
||||
|
||||
A brief, one-line description of the feature.
|
||||
**Describe the solution you'd like**
|
||||
A clear and concise description of what you want to happen.
|
||||
|
||||
## Motivation
|
||||
**Describe alternatives you've considered**
|
||||
A clear and concise description of any alternative solutions or features you've considered.
|
||||
|
||||
Why is this needed? What problem does it solve or what use case does it enable?
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Describe your suggested approach. If this is a new **plugin**, describe:
|
||||
- The data source (URL, format, update frequency)
|
||||
- What it would render on the globe (icons, paths, primitives)
|
||||
- Any external APIs or credentials required
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
Any other approaches you thought about and why you ruled them out.
|
||||
|
||||
## Additional Context
|
||||
|
||||
Screenshots, mockups, links to similar tools, or relevant documentation.
|
||||
**Note:** If this is about adding a new data source (like mapping vessels or plotting weather), please use the **Plugin Proposal** template instead! This template is for core engine features (like camera logic, filtering, or rendering pipeline upgrades).
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
name: Plugin Proposal
|
||||
about: Suggest a new real-time data source plugin
|
||||
title: '[PLUGIN] '
|
||||
labels: plugin-idea, help-wanted
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
**What data source do you want to add?**
|
||||
Please provide a brief description of the intelligence data (e.g., Global Earthquakes, Shipping Vessels, Weather Radar, Local Train Networks).
|
||||
|
||||
**Is there an available API?**
|
||||
Please link to any public or authenticated APIs that provide this data.
|
||||
*(e.g., USGS Earthquake API: https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php)*
|
||||
|
||||
**What should the plugin render?**
|
||||
- What kind of marker? (e.g., dots, icons, 3D models)
|
||||
- Does it require historical tracking (paths), or just current position?
|
||||
|
||||
**Would you be interested in building this?**
|
||||
- [ ] Yes, I'd like to try building it!
|
||||
- [ ] No, just putting the idea out there.
|
||||
|
||||
*(Looking to build it yourself? Check out the [Build a Plugin in 5 Minutes](https://github.com/silvertakana/worldwideview#build-a-plugin-in-5-minutes) guide in the README!)*
|
||||
@@ -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
|
||||
@@ -0,0 +1,12 @@
|
||||
# Garbage Collector — Daily Sweep Prompt
|
||||
|
||||
You are the WorldWideView Garbage Collector agent running headless in GitHub Actions.
|
||||
|
||||
Run the garbage-collector agent sweep:
|
||||
|
||||
1. Read `.agents/rules/garbage-collection.md` for your charter and all guard rails.
|
||||
2. Read `gc-findings.json` for the pre-scanned findings produced by `scripts/gc-scan.mjs`.
|
||||
3. Check the `DRY_RUN` environment variable — if `true`, post a dry-run summary only (no PRs or Issues).
|
||||
4. Execute the full sweep procedure described in `.agents/agents/garbage-collector.md`.
|
||||
|
||||
Do not scan the codebase yourself. Work only from `gc-findings.json`.
|
||||
@@ -0,0 +1,85 @@
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
# Non-blocking dependency audit. Surfaces high / critical vulnerabilities
|
||||
# in the CI output without failing the build. Flip `continue-on-error` to
|
||||
# `false` once the current transitive vulns (see #97) are resolved.
|
||||
audit:
|
||||
name: Dependency Audit
|
||||
runs-on: ubuntu-latest
|
||||
continue-on-error: true
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: pnpm/action-setup@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
- run: pnpm install --frozen-lockfile
|
||||
- run: pnpm audit --audit-level high
|
||||
|
||||
typecheck:
|
||||
name: Type Check
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: pnpm/action-setup@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
- run: pnpm install --frozen-lockfile
|
||||
- run: npx prisma generate
|
||||
- run: pnpm exec tsc --noEmit
|
||||
|
||||
lint:
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: pnpm/action-setup@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
- run: pnpm install --frozen-lockfile
|
||||
- run: pnpm lint
|
||||
|
||||
test:
|
||||
name: Unit Tests
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: pnpm/action-setup@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
- run: pnpm install --frozen-lockfile
|
||||
- run: npx prisma generate
|
||||
- run: pnpm test
|
||||
|
||||
build:
|
||||
name: Build
|
||||
runs-on: ubuntu-latest
|
||||
needs: [typecheck, test]
|
||||
env:
|
||||
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@v6
|
||||
- uses: pnpm/action-setup@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
- run: pnpm install --frozen-lockfile
|
||||
- run: npx prisma generate
|
||||
- run: pnpm build
|
||||
@@ -0,0 +1,44 @@
|
||||
name: Claude Code Review
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, synchronize, ready_for_review, reopened]
|
||||
# Optional: Only run on specific file changes
|
||||
# paths:
|
||||
# - "src/**/*.ts"
|
||||
# - "src/**/*.tsx"
|
||||
# - "src/**/*.js"
|
||||
# - "src/**/*.jsx"
|
||||
|
||||
jobs:
|
||||
claude-review:
|
||||
# Optional: Filter by PR author
|
||||
# if: |
|
||||
# github.event.pull_request.user.login == 'external-contributor' ||
|
||||
# github.event.pull_request.user.login == 'new-developer' ||
|
||||
# github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: read
|
||||
issues: read
|
||||
id-token: write
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
fetch-depth: 1
|
||||
|
||||
- name: Run Claude Code Review
|
||||
id: claude-review
|
||||
uses: anthropics/claude-code-action@v1
|
||||
with:
|
||||
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
|
||||
plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
|
||||
plugins: 'code-review@claude-code-plugins'
|
||||
prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
|
||||
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
|
||||
# or https://code.claude.com/docs/en/cli-reference for available options
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
name: Claude Code
|
||||
|
||||
on:
|
||||
issue_comment:
|
||||
types: [created]
|
||||
pull_request_review_comment:
|
||||
types: [created]
|
||||
issues:
|
||||
types: [opened, assigned]
|
||||
pull_request_review:
|
||||
types: [submitted]
|
||||
|
||||
jobs:
|
||||
claude:
|
||||
if: |
|
||||
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
|
||||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
|
||||
(github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
|
||||
(github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: read
|
||||
issues: read
|
||||
id-token: write
|
||||
actions: read # Required for Claude to read CI results on PRs
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
fetch-depth: 1
|
||||
|
||||
- name: Run Claude Code
|
||||
id: claude
|
||||
uses: anthropics/claude-code-action@v1
|
||||
with:
|
||||
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
|
||||
|
||||
# This is an optional setting that allows Claude to read CI results on PRs
|
||||
additional_permissions: |
|
||||
actions: read
|
||||
|
||||
# Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
|
||||
# prompt: 'Update the pull request description to include a summary of changes.'
|
||||
|
||||
# Optional: Add claude_args to customize behavior and configuration
|
||||
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
|
||||
# or https://code.claude.com/docs/en/cli-reference for available options
|
||||
# claude_args: '--allowed-tools Bash(gh pr *)'
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
name: Docker Image CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ "main" ]
|
||||
pull_request:
|
||||
branches: [ "main" ]
|
||||
|
||||
env:
|
||||
REGISTRY: ghcr.io
|
||||
IMAGE_NAME: ${{ github.repository }}
|
||||
|
||||
jobs:
|
||||
build-and-push-image:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
packages: write
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Log in to the Container registry
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
registry: ${{ env.REGISTRY }}
|
||||
username: ${{ github.actor }}
|
||||
password: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Extract metadata (tags, labels) for Docker
|
||||
id: meta
|
||||
uses: docker/metadata-action@v5
|
||||
with:
|
||||
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
|
||||
tags: |
|
||||
type=raw,value=latest,enable={{is_default_branch}}
|
||||
type=ref,event=branch
|
||||
type=sha,format=short
|
||||
|
||||
- name: Build and push Docker image
|
||||
uses: docker/build-push-action@v5
|
||||
with:
|
||||
context: .
|
||||
push: ${{ github.event_name != 'pull_request' }}
|
||||
tags: ${{ steps.meta.outputs.tags }}
|
||||
labels: ${{ steps.meta.outputs.labels }}
|
||||
cache-from: type=gha
|
||||
cache-to: type=gha,mode=max
|
||||
build-args: |
|
||||
NEXT_PUBLIC_CESIUM_ION_TOKEN=${{ secrets.NEXT_PUBLIC_CESIUM_ION_TOKEN }}
|
||||
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=${{ secrets.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY }}
|
||||
NEXT_PUBLIC_BING_MAPS_KEY=${{ secrets.NEXT_PUBLIC_BING_MAPS_KEY }}
|
||||
NEXT_PUBLIC_WWV_EDITION=${{ vars.NEXT_PUBLIC_WWV_EDITION || 'local' }}
|
||||
NEXT_PUBLIC_WS_ENGINE_URL=${{ vars.NEXT_PUBLIC_WS_ENGINE_URL }}
|
||||
NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL=${{ vars.NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL }}
|
||||
NEXT_PUBLIC_ADSENSE_CLIENT_ID=${{ secrets.NEXT_PUBLIC_ADSENSE_CLIENT_ID }}
|
||||
NEXT_PUBLIC_SUPABASE_URL=${{ vars.NEXT_PUBLIC_SUPABASE_URL }}
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=${{ secrets.NEXT_PUBLIC_SUPABASE_ANON_KEY }}
|
||||
@@ -0,0 +1,116 @@
|
||||
name: Garbage Collector
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 6 * * *' # 06:00 UTC daily
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
dry_run:
|
||||
description: 'Dry run — report findings only, open no PRs or Issues (recommended for first 3–5 days)'
|
||||
required: false
|
||||
default: 'true'
|
||||
type: choice
|
||||
options: ['true', 'false']
|
||||
days_branch:
|
||||
description: 'Days before a branch is considered stale'
|
||||
required: false
|
||||
default: '90'
|
||||
days_comment:
|
||||
description: 'Days before a TODO/FIXME comment is flagged'
|
||||
required: false
|
||||
default: '180'
|
||||
|
||||
concurrency:
|
||||
group: garbage-collector
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
issues: write
|
||||
id-token: write
|
||||
|
||||
jobs:
|
||||
collect:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GC_BOT_TOKEN }}
|
||||
DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }}
|
||||
DAYS_BRANCH: ${{ github.event.inputs.days_branch || '90' }}
|
||||
DAYS_COMMENT: ${{ github.event.inputs.days_comment || '180' }}
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # full history required for git blame and branch age
|
||||
token: ${{ secrets.GC_BOT_TOKEN }} # PAT so pushed branches trigger CI
|
||||
|
||||
- name: Configure git user
|
||||
run: |
|
||||
git config user.name 'WorldWideView GC Bot'
|
||||
git config user.email '[email protected]'
|
||||
|
||||
- name: Setup pnpm
|
||||
uses: pnpm/action-setup@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '22'
|
||||
cache: 'pnpm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: pnpm install --frozen-lockfile
|
||||
|
||||
- name: Run deterministic scan
|
||||
run: |
|
||||
node scripts/gc-scan.mjs \
|
||||
--out gc-findings.json \
|
||||
--days-branch=${{ env.DAYS_BRANCH }} \
|
||||
--days-comment=${{ env.DAYS_COMMENT }}
|
||||
|
||||
- name: Upload findings artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: gc-findings-${{ github.run_id }}
|
||||
path: gc-findings.json
|
||||
retention-days: 30
|
||||
|
||||
- name: Run Garbage Collector agent
|
||||
uses: anthropics/claude-code-action@v1
|
||||
with:
|
||||
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
|
||||
show_full_output: true
|
||||
prompt: |
|
||||
You are the WorldWideView Garbage Collector agent running headless in GitHub Actions.
|
||||
|
||||
Read `.agents/rules/garbage-collection.md` for your charter and all guard rails.
|
||||
Read `gc-findings.json` for the pre-scanned findings produced by `scripts/gc-scan.mjs`.
|
||||
|
||||
The DRY_RUN environment variable is: ${{ env.DRY_RUN }}
|
||||
|
||||
## If DRY_RUN is "true":
|
||||
Do NOT create any PRs or Issues.
|
||||
Instead, find or create the tracking Issue titled "[gc-bot] Daily Scan Reports" (label: gc-bot) in
|
||||
the silvertakana/worldwideview repository using the gh CLI:
|
||||
|
||||
# Find existing tracking issue
|
||||
gh issue list --repo silvertakana/worldwideview --label gc-bot --search "[gc-bot] Daily Scan Reports" --json number,title
|
||||
|
||||
# If it exists, add a comment:
|
||||
gh issue comment <number> --repo silvertakana/worldwideview --body "..."
|
||||
|
||||
# If it doesn't exist, create it:
|
||||
gh issue create --repo silvertakana/worldwideview --title "[gc-bot] Daily Scan Reports" --label gc-bot --body "..."
|
||||
|
||||
The comment body must list every finding with: tier, file, line, description.
|
||||
Include the run ID (${{ github.run_id }}) and timestamp at the top.
|
||||
|
||||
## If DRY_RUN is "false":
|
||||
Execute the full sweep procedure described in `.claude/agents/garbage-collector.md`.
|
||||
Create Tier A draft PRs and Tier B Issues per the guard rails in `.agents/rules/garbage-collection.md`.
|
||||
|
||||
Do not scan the codebase yourself. Work only from gc-findings.json.
|
||||
claude_args: '--model claude-haiku-4-5-20251001 --allowedTools Bash,Read,Edit,Write,Grep,Glob'
|
||||
@@ -0,0 +1,53 @@
|
||||
name: Mutation Testing
|
||||
|
||||
# Mutation testing is expensive (10–30 min per full run, even with
|
||||
# `coverageAnalysis: "perTest"`), so we don't gate every PR on it.
|
||||
# Instead it runs weekly so we catch drift in test quality, and on
|
||||
# demand via workflow_dispatch when someone wants to validate a
|
||||
# specific change.
|
||||
on:
|
||||
schedule:
|
||||
# 03:00 UTC Monday = 10 PM US Eastern Sunday night.
|
||||
- cron: '0 3 * * 1'
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
stryker:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 60
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # Required for Stryker's incremental mode.
|
||||
|
||||
- name: Setup pnpm
|
||||
uses: pnpm/action-setup@v3
|
||||
with:
|
||||
version: 9
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
|
||||
- name: Install dependencies
|
||||
run: pnpm install --frozen-lockfile
|
||||
|
||||
- name: Generate Prisma client
|
||||
run: pnpm exec prisma generate
|
||||
|
||||
- name: Run Stryker
|
||||
run: pnpm exec stryker run
|
||||
|
||||
- name: Upload mutation report
|
||||
if: always()
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: stryker-report
|
||||
path: reports/mutation/
|
||||
retention-days: 30
|
||||
@@ -0,0 +1,56 @@
|
||||
name: Playwright Tests
|
||||
on:
|
||||
push:
|
||||
branches: [ main, master ]
|
||||
pull_request:
|
||||
branches: [ main, master ]
|
||||
permissions:
|
||||
contents: read
|
||||
jobs:
|
||||
test:
|
||||
timeout-minutes: 60
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
browser: [chromium, firefox, webkit]
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: pnpm/action-setup@v3
|
||||
with:
|
||||
version: 9.15.4
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
cache: 'pnpm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: pnpm install
|
||||
|
||||
- name: Install Playwright Browsers
|
||||
run: pnpm exec playwright install --with-deps
|
||||
|
||||
- name: Run Project Setup
|
||||
run: pnpm run setup
|
||||
|
||||
- name: Boot Database
|
||||
run: |
|
||||
docker network create coolify || true
|
||||
pnpm run predev
|
||||
|
||||
- name: Run Playwright tests
|
||||
env:
|
||||
# Prevent Firefox from loading the AT-SPI/MSAA accessibility bridge on
|
||||
# Linux CI — without this, Firefox hangs for ~20 min waiting for a bus
|
||||
# that doesn't exist on ubuntu-latest runners.
|
||||
NO_AT_BRIDGE: ${{ matrix.browser == 'firefox' && '1' || '0' }}
|
||||
run: pnpm test:e2e --project=${{ matrix.browser }}
|
||||
|
||||
- uses: actions/upload-artifact@v4
|
||||
if: ${{ !cancelled() }}
|
||||
with:
|
||||
name: playwright-report-${{ matrix.browser }}
|
||||
path: playwright-report/
|
||||
retention-days: 30
|
||||
@@ -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"
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
name: Test Local Dev Environment
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
test-dev:
|
||||
name: Test Local Dev Startup
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
NEXT_PUBLIC_WWV_EDITION: local
|
||||
AUTH_SECRET: ci-placeholder-secret-not-used-in-tests
|
||||
ENCRYPTION_MASTER_KEY: ci-placeholder-key-not-used-in-tests
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
|
||||
- uses: pnpm/action-setup@v6
|
||||
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
|
||||
- name: Create coolify docker network
|
||||
# Needed because docker-compose.yml references external coolify network
|
||||
run: docker network create coolify || true
|
||||
|
||||
- name: Install dependencies
|
||||
run: pnpm install --frozen-lockfile
|
||||
|
||||
- name: Setup environment
|
||||
run: |
|
||||
cp .env.example .env
|
||||
sed -i 's/^ENCRYPTION_MASTER_KEY=.*/ENCRYPTION_MASTER_KEY=ci-placeholder-key-not-used-in-tests/' .env
|
||||
sed -i 's/^AUTH_SECRET=.*/AUTH_SECRET=ci-placeholder-secret-not-used-in-tests/' .env
|
||||
|
||||
- name: Test predev setup
|
||||
# Tests that Docker DB boots, port mappings work, Prisma pushes schema, and plugins sync
|
||||
run: pnpm run predev
|
||||
|
||||
- name: Test dev server startup
|
||||
run: |
|
||||
# Start the dev server in the background
|
||||
pnpm run dev &
|
||||
DEV_PID=$!
|
||||
|
||||
echo "Waiting for Next.js to respond on port 3000..."
|
||||
|
||||
# Wait up to 120 seconds for the dev server to return a response
|
||||
timeout 120 bash -c 'until curl -s http://localhost:3000 > /dev/null; do sleep 5; done'
|
||||
|
||||
# Check if the process is still running
|
||||
if ! kill -0 $DEV_PID 2>/dev/null; then
|
||||
echo "Dev server crashed or failed to start within timeout!"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Dev server started successfully!"
|
||||
|
||||
# Graceful shutdown
|
||||
kill $DEV_PID
|
||||
@@ -0,0 +1,121 @@
|
||||
name: Test Setup Scripts
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ "main" ]
|
||||
pull_request:
|
||||
branches: [ "main" ]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
test-bash:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.x'
|
||||
|
||||
- name: Start local HTTP server
|
||||
run: |
|
||||
python3 -m http.server 8080 &
|
||||
sleep 2 # Wait for server to start
|
||||
|
||||
- name: Patch setup.sh to use local server
|
||||
run: |
|
||||
sed -i 's|https://raw.githubusercontent.com/silvertakana/worldwideview/main|http://localhost:8080|g' self-host/setup.sh
|
||||
|
||||
- name: Run setup.sh
|
||||
run: |
|
||||
cd self-host
|
||||
bash setup.sh
|
||||
|
||||
- name: Verify .env generation
|
||||
run: |
|
||||
cd self-host
|
||||
if [ ! -f .env ]; then
|
||||
echo ".env file was not created"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! grep -q "^AUTH_SECRET=[a-f0-9]\{64\}$" .env; then
|
||||
echo "AUTH_SECRET was not generated correctly or is missing"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: Verify docker-compose.yml download
|
||||
run: |
|
||||
cd self-host
|
||||
if [ ! -f docker-compose.yml ]; then
|
||||
echo "docker-compose.yml was not downloaded"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: Verify Docker containers are running
|
||||
run: |
|
||||
cd self-host
|
||||
docker compose ps
|
||||
if ! docker compose ps | grep -q "Up"; then
|
||||
echo "Docker containers failed to start"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
test-powershell:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.x'
|
||||
|
||||
- name: Start local HTTP server
|
||||
run: |
|
||||
python3 -m http.server 8080 &
|
||||
sleep 2 # Wait for server to start
|
||||
|
||||
- name: Patch setup.ps1 to use local server
|
||||
run: |
|
||||
sed -i 's|https://raw.githubusercontent.com/silvertakana/worldwideview/main|http://localhost:8080|g' self-host/setup.ps1
|
||||
|
||||
- name: Run setup.ps1
|
||||
run: |
|
||||
cd self-host
|
||||
pwsh ./setup.ps1
|
||||
|
||||
- name: Verify .env generation
|
||||
run: |
|
||||
cd self-host
|
||||
if [ ! -f .env ]; then
|
||||
echo ".env file was not created"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! grep -q "^AUTH_SECRET=[a-f0-9]\{64\}$" .env; then
|
||||
echo "AUTH_SECRET was not generated correctly or is missing"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: Verify docker-compose.yml download
|
||||
run: |
|
||||
cd self-host
|
||||
if [ ! -f docker-compose.yml ]; then
|
||||
echo "docker-compose.yml was not downloaded"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: Verify Docker containers are running
|
||||
run: |
|
||||
cd self-host
|
||||
docker compose ps
|
||||
if ! docker compose ps | grep -q "Up"; then
|
||||
echo "Docker containers failed to start"
|
||||
exit 1
|
||||
fi
|
||||
+80
-6
@@ -1,7 +1,7 @@
|
||||
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
|
||||
|
||||
# dependencies
|
||||
/node_modules
|
||||
node_modules/
|
||||
/.pnp
|
||||
.pnp.*
|
||||
.yarn/*
|
||||
@@ -18,7 +18,10 @@
|
||||
/out/
|
||||
|
||||
# agents
|
||||
/.agents/
|
||||
/.agents/plans
|
||||
/.agents/research/
|
||||
/.agents/context/
|
||||
/.agents/settings.local.json
|
||||
|
||||
# performance
|
||||
/performance/
|
||||
@@ -26,11 +29,23 @@
|
||||
# artifacts
|
||||
/artifacts/
|
||||
|
||||
# scripts
|
||||
/scripts/
|
||||
# gc bot — generated scan output, never commit
|
||||
gc-findings.json
|
||||
|
||||
# scripts (tracked, but temporary scratchpads should go in /local-scripts/)
|
||||
|
||||
|
||||
# local database
|
||||
/data/
|
||||
packages/*/data/
|
||||
*.db
|
||||
*.sqlite
|
||||
*.sqlite3
|
||||
*.db-shm
|
||||
*.db-wal
|
||||
|
||||
# temporary files and credentials
|
||||
/tmp/
|
||||
|
||||
# generated prisma client
|
||||
/src/generated/
|
||||
@@ -49,8 +64,8 @@ yarn-error.log*
|
||||
.pnpm-debug.log*
|
||||
|
||||
# env files (can opt-in for committing if needed)
|
||||
.env*
|
||||
!.env
|
||||
.env
|
||||
.env.local
|
||||
|
||||
# vercel
|
||||
.vercel
|
||||
@@ -61,3 +76,62 @@ next-env.d.ts
|
||||
|
||||
# Plugin build artifacts
|
||||
packages/*/dist/
|
||||
|
||||
# Reference Reference Codebases
|
||||
/worldmonitor/
|
||||
|
||||
# Developmental scripts & temporary sandbox
|
||||
/local-scripts/
|
||||
/public/plugins-local/
|
||||
|
||||
# Local plugin development (gitignored workspace)
|
||||
local-plugins/*
|
||||
!local-plugins/.gitkeep
|
||||
!local-plugins/README.md
|
||||
|
||||
# git worktrees
|
||||
/.worktrees/
|
||||
|
||||
# proprietary extracted services
|
||||
packages/wwv-data-engine/
|
||||
|
||||
# IDE workspace files
|
||||
*.code-workspace
|
||||
*.vscode
|
||||
|
||||
# Build outputs and generated assets
|
||||
/public/cesium/
|
||||
build_output*.log
|
||||
build_output*.txt
|
||||
/build*.log
|
||||
|
||||
# Root-level scratch scripts and agent artifacts
|
||||
tmp_*.js
|
||||
dump-*.js
|
||||
dump_*.py
|
||||
test*.js
|
||||
test*.mjs
|
||||
delete-dups.js
|
||||
commit.json
|
||||
skills-lock.json
|
||||
|
||||
# Seeder repositories
|
||||
/local-seeders/
|
||||
/.local-seeders-dist/
|
||||
|
||||
# WorldwideView Ecosystem Repositories (Development Structure)
|
||||
# The following ignores represent the different repositories related to the entire setup found in C:\dev
|
||||
/worldwideview-marketplace/
|
||||
/worldwideview-plugins/
|
||||
/worldwideview-web/
|
||||
/wwv-data-engine/
|
||||
/wwv-data-engine-public/
|
||||
/wwv-seeders/
|
||||
/wwv-seeders-private/
|
||||
/wwv-test/
|
||||
worldwideview.code-workspace
|
||||
|
||||
# Playwright
|
||||
/playwright-report/
|
||||
/test-results/
|
||||
/playwright/.auth/
|
||||
Vendored
+36
@@ -0,0 +1,36 @@
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "Next.js: debug server-side",
|
||||
"type": "node-terminal",
|
||||
"request": "launch",
|
||||
"command": "pnpm run dev",
|
||||
"cwd": "${workspaceFolder}"
|
||||
},
|
||||
{
|
||||
"name": "Next.js: debug client-side",
|
||||
"type": "chrome",
|
||||
"request": "launch",
|
||||
"url": "http://localhost:3000",
|
||||
"webRoot": "${workspaceFolder}",
|
||||
"sourceMapPathOverrides": {
|
||||
"webpack://_N_E/*": "${webRoot}/*"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "WWV Data Engine: debug",
|
||||
"type": "node-terminal",
|
||||
"request": "launch",
|
||||
"command": "pnpm --filter wwv-data-engine run dev",
|
||||
"cwd": "${workspaceFolder}"
|
||||
},
|
||||
{
|
||||
"name": "Full Stack: debug",
|
||||
"type": "node-terminal",
|
||||
"request": "launch",
|
||||
"command": "pnpm run dev:all",
|
||||
"cwd": "${workspaceFolder}"
|
||||
}
|
||||
]
|
||||
}
|
||||
Vendored
+20
@@ -0,0 +1,20 @@
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"label": "npm: dev:all",
|
||||
"type": "npm",
|
||||
"script": "dev:all",
|
||||
"problemMatcher": [],
|
||||
"isBackground": true,
|
||||
"presentation": {
|
||||
"reveal": "always",
|
||||
"panel": "new"
|
||||
},
|
||||
"group": {
|
||||
"kind": "build",
|
||||
"isDefault": true
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,164 @@
|
||||
# WorldWideView — Agent Rules
|
||||
|
||||
## 1. Project Identity
|
||||
|
||||
WorldWideView is a **real-time geospatial intelligence engine** visualizing live global data on an interactive 3D globe. Built with **Next.js 16**, **CesiumJS**, **React 19**, and **Zustand**. Design/feature target: `www.worldmonitor.app` ([reference repo](https://github.com/koala73/worldmonitor)).
|
||||
|
||||
---
|
||||
|
||||
## 2. Tech Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|---|---|
|
||||
| Framework | Next.js 16 (App Router, `output: "standalone"`) |
|
||||
| Language | TypeScript 5, strict mode |
|
||||
| 3D Engine | CesiumJS + Resium (Google Photorealistic 3D Tiles) |
|
||||
| State | Zustand (9 slices: globe, layers, timeline, ui, filter, data, config, favorites, geojson) |
|
||||
| Event Bus | Custom typed `DataBus` (pub/sub singleton) |
|
||||
| Styling | Vanilla CSS — **no Tailwind** |
|
||||
| Database | PostgreSQL via Prisma 7 |
|
||||
| Auth | NextAuth v5 beta (Credentials provider, JWT sessions) |
|
||||
| Package Manager | pnpm (monorepo with `pnpm-workspace.yaml`) |
|
||||
| Testing | Vitest + jsdom + React Testing Library |
|
||||
| Deployment | Docker multi-stage build → Coolify |
|
||||
|
||||
---
|
||||
|
||||
## 3. Critical Invariants
|
||||
|
||||
Agents MUST respect these at all times:
|
||||
|
||||
- **Plugin source of truth**: `@worldwideview/wwv-plugin-sdk` — never define plugin types locally.
|
||||
- **All-Bundle Model**: every plugin is dynamically imported via `loadPluginFromManifest` using `import(/* webpackIgnore: true */ entry)`. Legacy `StaticDataPlugin` / `DeclarativePlugin` runtimes are deprecated.
|
||||
- **Agnostic frontend**: each plugin **MUST declare its own `streamUrl`**; do not assume one shared pipe.
|
||||
- **Nine Zustand slices** under `src/core/state/`: access via `useStore` in React, `useStore.getState()` elsewhere.
|
||||
- **Primitive-based rendering**: Point/Billboard/Label/Polyline collections only. Never mix `size`/`outlineWidth`/`outlineColor` onto billboard entities — GPU silently clips.
|
||||
- **Three editions** via `NEXT_PUBLIC_WWV_EDITION` (`local` / `cloud` / `demo`); feature flags in `src/core/edition.ts`.
|
||||
- **Nested git clones**: `local-plugins/` (community plugins) and `local-seeders/community/` + `local-seeders/private/` (seeders) are **independent git repos cloned inside this repo, gitignored from it**. Each has its own remote. Run `git pull` inside each before editing; commits/pushes there go to their own upstream — not to `worldwideview`. See `.agents/context/ecosystem-repositories.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Conventions
|
||||
|
||||
- **File size**: ~300 lines max. Extract helpers, split components, use hooks.
|
||||
- **Import aliases**: `@/*` → `./src/*`; `@worldwideview/wwv-plugin-sdk` → `./packages/wwv-plugin-sdk/src`
|
||||
- **CSS**: Vanilla CSS only. Global: `src/app/globals.css`. Scoped: CSS Modules. HUD: `src/styles/hud-animations.css`.
|
||||
- **Rendering entities**: Points use `type: "point"` + `size`/`outlineColor`/`outlineWidth`. Billboards use `type: "billboard"` + `iconUrl`/`iconScale`. NEVER mix.
|
||||
- **Plugin registration**: Built-ins via `AppShell.tsx` → `PluginRegistry` → `PluginManager`. Marketplace plugins via `InstalledPluginsLoader`.
|
||||
- **Workspace**: Use `"workspace:*"` (not `"*"`) for internal deps. New `packages/` plugins need `transpilePackages` in `next.config.ts`.
|
||||
- **Temp files**: Save debugging scripts/outputs exclusively in `/local-scripts/` — never in root.
|
||||
- **Cleanliness**: Remove dead code, unused imports, debug `console.log` before finalising. Never use `any` or `@ts-ignore`. Never create `.mdc` files.
|
||||
|
||||
---
|
||||
|
||||
## 5. AI Meta-Directives
|
||||
|
||||
> [!WARNING]
|
||||
> - Always use `.md` extensions. Never `.mdc`. Never reference Cursor IDE rules.
|
||||
> - **MUST** bump semver in `package.json` before every commit via `/commit` workflow (`feat:` → Minor, `fix/refactor/perf:` → Patch).
|
||||
> - **MUST** explain complex concepts simply — include an everyday-life analogy.
|
||||
> - **MUST** require explicit user authorization before any state-changing action that isn't simple/safe.
|
||||
> - **MUST** ask clarifying questions rather than assume when requirements are unclear.
|
||||
> - **MUST** update `.agents/rules/` files immediately whenever an architectural shift invalidates them.
|
||||
|
||||
---
|
||||
|
||||
## 6. Environment & Configuration
|
||||
|
||||
See `.agents/context/environment-config.md` for required environment variables and secrets.
|
||||
|
||||
---
|
||||
|
||||
## 7. Development & Deployment
|
||||
|
||||
```bash
|
||||
pnpm dev # Frontend only (auto-runs prisma db push + copy-cesium)
|
||||
pnpm dev:all # Frontend + data engine via Docker Compose
|
||||
pnpm build # Production build
|
||||
pnpm test # Vitest
|
||||
pnpm db:reset # Wipe + re-migrate DB (destructive)
|
||||
```
|
||||
|
||||
See `.agents/context/` → [deployment and testing details in `.agents/rules/deployment-and-testing.md`] for Docker architecture, Coolify rules, and CSP headers.
|
||||
|
||||
---
|
||||
|
||||
## 8. On-Demand Rules (path-scoped, auto-load on file access)
|
||||
|
||||
These load automatically when you read/edit files matching their paths:
|
||||
|
||||
| Rule | Triggers on |
|
||||
|---|---|
|
||||
| `.agents/rules/cesium-rendering.md` | `src/core/globe/**`, `src/plugins/**`, `packages/wwv-plugin-*/src/**` |
|
||||
| `.agents/rules/state-management.md` | `src/core/state/**`, `src/components/**` |
|
||||
| `.agents/rules/plugin-architecture.md` | `src/core/plugins/**`, `packages/wwv-plugin-*/src/**`, `local-plugins/**` |
|
||||
| `.agents/rules/marketplace-architecture.md` | `src/lib/marketplace/**`, `src/app/api/marketplace/**` |
|
||||
| `.agents/rules/cloud-auth-architecture.md` | `src/lib/auth*`, `src/app/api/auth/**`, `src/core/auth.ts` |
|
||||
| `.agents/rules/database-migrations.md` | `prisma/**` |
|
||||
| `.agents/rules/monorepo-workflow.md` | `packages/**`, `pnpm-workspace.yaml`, `local-plugins/**` |
|
||||
| `.agents/rules/data-engine-architecture.md` | `packages/**`, `local-seeders/**`, `docker-compose.yml` |
|
||||
| `.agents/rules/deployment-and-testing.md` | `Dockerfile`, `docker-compose.yml`, `.github/**`, `next.config.ts` |
|
||||
| `.agents/rules/e2e-testing.md` | `tests/**`, `public/e2e-fixtures/**`, `playwright.config.ts` |
|
||||
|
||||
---
|
||||
|
||||
## 9. On-Demand Context (read explicitly when needed)
|
||||
|
||||
See `.agents/context/INDEX.md` for the full navigation table. Key files:
|
||||
|
||||
| When to read | File |
|
||||
|---|---|
|
||||
| Product vision, business model, Edition system | `.agents/context/platform-architecture.md` |
|
||||
| Finding files, repo layout | `.agents/context/directory-structure.md` |
|
||||
| Routing fix to correct repository | `.agents/context/ecosystem-repositories.md` |
|
||||
| Next.js, data pipeline, Redis, DB schema | `.agents/context/application-architecture.md` |
|
||||
| Debugging plugin data, namespace collisions | `.agents/context/troubleshooting-and-debugging.md` |
|
||||
| SSH, Coolify MCP | `.agents/context/server-management.md` |
|
||||
| Coding principles, Definition of Done | `.agents/context/coding-principles.md` |
|
||||
| `.env` variables and secrets | `.agents/context/environment-config.md` |
|
||||
|
||||
---
|
||||
|
||||
## 10. Slash Commands
|
||||
|
||||
| Command | Description | File |
|
||||
|---|---|---|
|
||||
| `/commit` | **Required before every commit** — bump semver + conventional commit | `.agents/skills/commit/SKILL.md` |
|
||||
| `/remember` | Save a lesson or fact into permanent memory | `.agents/skills/remember/SKILL.md` |
|
||||
| `/pr-review` | 6-role comprehensive pull request review | `.agents/skills/pr-review/SKILL.md` |
|
||||
| `/local-dev` | Check, start, troubleshoot local dev environment | `.agents/workflows/local-dev.md` |
|
||||
| `/data-engine-cli` | Use the wwv-data-engine CLI wrapper | `.agents/workflows/data-engine-cli.md` |
|
||||
| `/debugging-coolify` | Troubleshoot deployed apps on Coolify via MCP/SSH | `.agents/workflows/debugging-coolify.md` |
|
||||
| `/five` | Five Whys root cause analysis | `.agents/workflows/five.md` |
|
||||
| `/stitch-to-nextjs` | Generate UI with Stitch MCP, port into Next.js | `.agents/workflows/stitch-to-nextjs.md` |
|
||||
|
||||
---
|
||||
|
||||
## 11. Agent Skills Reference
|
||||
|
||||
| Skill | When to Use |
|
||||
|---|---|
|
||||
| `worldwideview-plugin-creation` | **Use when creating any plugin** — strict architectural checklist |
|
||||
| `plugin-creation-master-guide.md` | Decision matrix for choosing plugin architecture |
|
||||
| `osm-static-plugin-creation.md` | Creating static GeoJSON plugins from OpenStreetMap |
|
||||
| `database-operations.md` | Prisma schema changes, migrations, database queries |
|
||||
| `database-incident-recovery-procedures.md` | Safely restoring a broken production database |
|
||||
|
||||
52 global skills available. See `.agents/global-skills-index.md`.
|
||||
|
||||
---
|
||||
|
||||
## 12. Pull Request & Commit Guidelines
|
||||
|
||||
- **Commit format**: Conventional Commits (`feat:`, `fix:`, `refactor:`, `perf:`). Use `/commit` workflow.
|
||||
- **Required checks**: `pnpm test` and `pnpm build` must pass before merge.
|
||||
- **Review**: Use `/pr-review` for comprehensive multi-role review.
|
||||
- **Worktrees**: Use `git-wt switch --create <branch>` and `git-wt remove` (never `rm -rf` a worktree — orphans the PostgreSQL Docker volume).
|
||||
|
||||
---
|
||||
|
||||
## Hard Rule
|
||||
|
||||
> **Always interface-based, extensible, composable, modular. Never band-aids on band-aids.**
|
||||
|
||||
Read `.agents/context/coding-principles.md` before any non-trivial code change.
|
||||
+2
-2
@@ -32,9 +32,9 @@ This project is licensed under the [Elastic License 2.0](./LICENSE). By submitti
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
4. **Copy the environment file** and fill in your API keys:
|
||||
4. **Generate environment file** (auto-creates `.env.local` with `AUTH_SECRET`):
|
||||
```bash
|
||||
cp .env.example .env.local
|
||||
npm run setup
|
||||
```
|
||||
5. **Start the dev server**:
|
||||
```bash
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# Design System: WorldWideView
|
||||
**Project ID:** local-worldwideview-app
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
The WorldWideView platform employs an **"Airy, High-Tech, and Geospatial-Focused"** aesthetic. The design philosophy centers around "Glassmorphism Pro Max"—keeping the user's primary focus on the rich, underlying 3D globe visualization while providing highly legible, structured, and floating Heads-Up Display (HUD) elements.
|
||||
|
||||
The mood is utilitarian yet premium, heavily relying on dense background blurring, delicate inner borders, and vibrant glowing accent states to establish depth, interactivity, and a sense of "live" intelligence.
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
WorldWideView operates using a multi-theme architecture (Default Dark, Pure Black, Legacy OLED, and Light). The core semantic roles for the **Default Dark Theme** are outlined below:
|
||||
|
||||
* **Obsidian Canvas** (`#171717`) - `--bg-primary`: The foundational layer behind the application shell and globe.
|
||||
* **Translucent Slate Glass** (`rgba(38, 38, 38, 0.85)`) - `--bg-glass`: The primary background for floating HUD panels, sidebars, and dialogs. Provides a frosted glass effect that allows the map to bleed through.
|
||||
* **Frost White** (`#ffffff`) - `--text-primary`: Primary typography for headers, active states, and high-emphasis data.
|
||||
* **Muted Ash** (`#a3a3a3`) - `--text-muted`: Secondary typography used for labels, subtitles, and inactive states to establish visual hierarchy.
|
||||
* **Gossamer Edge** (`rgba(255, 255, 255, 0.15)`) - `--border-subtle`: Defines the subtle, crisp edges of glass panels, dividers, and default button states.
|
||||
* **Starlight Cyan** (`#ffffff` / *Legacy:* `#22d3ee`) - `--accent-cyan`: Used for primary actions, active tabs, timeline scrubbers, and play buttons. Often paired with a diffuse glow (`0 0 24px rgba(255, 255, 255, 0.15)`) for emphasis and technical flair.
|
||||
* **Telemetry Green** (`#22c55e`) - `--accent-green`: Used for live status indicators, pulsing connectivity badges, and positive data deltas.
|
||||
* **Warning Amber** (`#f59e0b`) - `--accent-amber`: Used for warnings, "Alpha" badges, or unavailable data states.
|
||||
|
||||
## 3. Typography Rules
|
||||
The system uses a dual-font strategy to balance clean user interfaces with technical precision.
|
||||
|
||||
* **UI Font (Inter):** Used for all general interface elements, headers, and buttons.
|
||||
* Headers and brand elements use a bold `600/700` weight with tight letter-spacing (`-0.02em`) for a sleek, modern feel.
|
||||
* Section titles, keys, and subtitles use a very small size (`11px`), a medium weight, uppercase transformation, and wide letter-spacing (`0.05em` to `0.1em`) to mimic aerospace or military HUD interfaces.
|
||||
* **Monospace Font (JetBrains Mono):** Used strictly for data values, coordinates, telemetry, and exact timestamps (`11px` to `12px`). Ensures tabular alignment, clear distinction between similar characters (e.g., 0 and O), and technical precision.
|
||||
|
||||
## 4. Component Stylings
|
||||
|
||||
* **Glass Panels (Cards/Containers):**
|
||||
* **Shape:** Generously rounded corners (`16px` / `var(--radius-lg)`).
|
||||
* **Surface:** Dense frosted background blur (`24px`).
|
||||
* **Depth:** Elevated significantly above the map using a dual-layered drop shadow (`0 8px 32px rgba(0, 0, 0, 0.4)` combined with `0 2px 8px rgba(0, 0, 0, 0.2)`). Features a crisp inner border (`inset 0 1px 1px rgba(255, 255, 255, 0.1)`) to simulate physical glass thickness.
|
||||
* **Buttons:**
|
||||
* **Shape:** Subtly rounded corners (`12px` / `var(--radius-md)`) with a standard height of `36px`.
|
||||
* **Surface:** Translucent glass background with a subtle border.
|
||||
* **Behavior:** Smooth, spring-based transitions. On hover, the background brightens, the element scales up/translates slightly (`translateY(-1px)`), and primary buttons emit a vivid neon glow. On click (active), buttons physically depress (`scale(0.97)`).
|
||||
* **Tabs & Selectors:**
|
||||
* **Shape:** Softly rounded (`8px` / `var(--radius-sm)`).
|
||||
* **Surface:** Clean, flat, and transparent by default.
|
||||
* **Behavior:** Transitions to a soft glass hover or active state. Active tabs use a highlighted background (`rgba(var(--accent-rgb), 0.1)`) and bright cyan text with increased font weight.
|
||||
* **Timeline Scrubber:**
|
||||
* **Track:** Slender `4px` tall track with softly rounded edges.
|
||||
* **Handle:** A circular `14px` handle that emits a cyan glow, expanding dynamically on hover (`scale(1.2)`).
|
||||
|
||||
## 5. Layout Principles
|
||||
* **Absolute Overlays:** The UI does not push the map; instead, it floats over a full-screen, `z-index: 0` globe canvas. Elements are anchored to the edges (Header to top, Sidebar to sides, Timeline to bottom).
|
||||
* **Strict 4/8dp Rhythm:** All spacing adheres to an 8-point grid base (`4px`, `8px`, `12px`, `16px`, `24px`, `32px`, `48px`).
|
||||
* **Dynamic Containment:** Sidebars and bottom panels push each other dynamically to prevent overlap and optimize map visibility (e.g., when the bottom panel opens, sidebars slide upward).
|
||||
* **Whitespace & Density:** Panels use a dense `16px` padding globally to maximize the amount of intelligence data visible while maintaining clear breathing room between individual data rows. Scrollable areas hide scrollbars until hovered to maintain the clean glass aesthetic.
|
||||
+116
-14
@@ -1,32 +1,134 @@
|
||||
# Stage 1: Install dependencies
|
||||
FROM node:22-alpine AS deps
|
||||
# Stage 0: Extract package.json files for layer caching
|
||||
FROM alpine AS extractor
|
||||
WORKDIR /app
|
||||
COPY package.json package-lock.json ./
|
||||
RUN npm ci
|
||||
|
||||
# Stage 2: Build the application
|
||||
FROM node:22-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY --from=deps /app/node_modules ./node_modules
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
RUN find . -type f \! -name 'package.json' \! -name 'pnpm-workspace.yaml' \! -name 'pnpm-lock.yaml' -delete && \
|
||||
find . -type d -empty -delete
|
||||
|
||||
# Stage 1: Install ALL dependencies (needed for build)
|
||||
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
|
||||
|
||||
|
||||
# Stage 3: Build the application
|
||||
FROM deps AS builder
|
||||
# Copy full source code
|
||||
COPY . .
|
||||
# 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
|
||||
ARG NEXT_PUBLIC_WWV_AGENT_BUS_ENABLED
|
||||
ARG NEXT_PUBLIC_WWV_BUILD_ID
|
||||
ARG NEXT_PUBLIC_WWV_BUILD_AT
|
||||
|
||||
# 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
|
||||
|
||||
# Stamp the build with a millisecond-precision id + iso timestamp. If the
|
||||
# operator hasn't passed NEXT_PUBLIC_WWV_BUILD_ID via build args, generate
|
||||
# one here so /api/build and the client console.log both carry a unique
|
||||
# value per `docker build`.
|
||||
RUN if [ -z "$NEXT_PUBLIC_WWV_BUILD_ID" ]; then \
|
||||
NEXT_PUBLIC_WWV_BUILD_ID="$(date +%s%3N 2>/dev/null || node -e 'process.stdout.write(String(Date.now()))')" ; \
|
||||
fi && \
|
||||
if [ -z "$NEXT_PUBLIC_WWV_BUILD_AT" ]; then \
|
||||
NEXT_PUBLIC_WWV_BUILD_AT="$(node -e 'process.stdout.write(new Date().toISOString())')" ; \
|
||||
fi && \
|
||||
echo "$NEXT_PUBLIC_WWV_BUILD_ID" > /app/.build-id && \
|
||||
echo "$NEXT_PUBLIC_WWV_BUILD_AT" > /app/.build-at
|
||||
|
||||
# Write .env.production.local so Next.js sees every NEXT_PUBLIC_* var
|
||||
# whose ARG was passed in. Docker doesn't reliably promote ARGs into the
|
||||
# build process's environment for `next build` to inline references with
|
||||
# Webpack's DefinePlugin — `process.env.NEXT_PUBLIC_X` either gets the
|
||||
# inlined literal value (when set) or stays as a runtime polyfill access
|
||||
# that resolves to undefined in the browser. Writing the file is the
|
||||
# documented Next.js path and behaves the same on every host.
|
||||
RUN set +e ; { \
|
||||
echo "NEXT_PUBLIC_WWV_BUILD_ID=$(cat /app/.build-id)" ; \
|
||||
echo "NEXT_PUBLIC_WWV_BUILD_AT=$(cat /app/.build-at)" ; \
|
||||
if [ -n "$NEXT_PUBLIC_WWV_EDITION" ]; then echo "NEXT_PUBLIC_WWV_EDITION=$NEXT_PUBLIC_WWV_EDITION" ; fi ; \
|
||||
if [ -n "$NEXT_PUBLIC_WWV_AGENT_BUS_ENABLED" ]; then echo "NEXT_PUBLIC_WWV_AGENT_BUS_ENABLED=$NEXT_PUBLIC_WWV_AGENT_BUS_ENABLED" ; fi ; \
|
||||
if [ -n "$NEXT_PUBLIC_CESIUM_ION_TOKEN" ]; then echo "NEXT_PUBLIC_CESIUM_ION_TOKEN=$NEXT_PUBLIC_CESIUM_ION_TOKEN" ; fi ; \
|
||||
if [ -n "$NEXT_PUBLIC_GOOGLE_MAPS_API_KEY" ]; then echo "NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=$NEXT_PUBLIC_GOOGLE_MAPS_API_KEY" ; fi ; \
|
||||
if [ -n "$NEXT_PUBLIC_BING_MAPS_KEY" ]; then echo "NEXT_PUBLIC_BING_MAPS_KEY=$NEXT_PUBLIC_BING_MAPS_KEY" ; fi ; \
|
||||
if [ -n "$NEXT_PUBLIC_WS_ENGINE_URL" ]; then echo "NEXT_PUBLIC_WS_ENGINE_URL=$NEXT_PUBLIC_WS_ENGINE_URL" ; fi ; \
|
||||
if [ -n "$NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL" ]; then echo "NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL=$NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL" ; fi ; \
|
||||
if [ -n "$NEXT_PUBLIC_ADSENSE_CLIENT_ID" ]; then echo "NEXT_PUBLIC_ADSENSE_CLIENT_ID=$NEXT_PUBLIC_ADSENSE_CLIENT_ID" ; fi ; \
|
||||
if [ -n "$NEXT_PUBLIC_SUPABASE_URL" ]; then echo "NEXT_PUBLIC_SUPABASE_URL=$NEXT_PUBLIC_SUPABASE_URL" ; fi ; \
|
||||
if [ -n "$NEXT_PUBLIC_SUPABASE_ANON_KEY" ]; then echo "NEXT_PUBLIC_SUPABASE_ANON_KEY=$NEXT_PUBLIC_SUPABASE_ANON_KEY" ; fi ; \
|
||||
} > /app/.env.production.local
|
||||
|
||||
# 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
|
||||
|
||||
# Stage 3: Production runner
|
||||
FROM node:22-alpine AS runner
|
||||
# Deploy flattened production dependencies
|
||||
RUN pnpm --filter worldwideview deploy --prod /app/prod
|
||||
|
||||
# Stage 4: Production 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
|
||||
# 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
|
||||
COPY --from=builder /app/prisma ./prisma
|
||||
COPY --from=builder /app/prisma.config.ts ./prisma.config.ts
|
||||
|
||||
# Copy Prisma generated client
|
||||
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
|
||||
|
||||
EXPOSE 3000
|
||||
# Build stamp — read by /api/build at runtime.
|
||||
COPY --from=builder /app/.build-id ./.build-id
|
||||
COPY --from=builder /app/.build-at ./.build-at
|
||||
|
||||
CMD ["node", "server.js"]
|
||||
# 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
|
||||
|
||||
EXPOSE 3000 3001
|
||||
|
||||
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
|
||||
CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
|
||||
|
||||
ENTRYPOINT ["./docker-entrypoint.sh"]
|
||||
Binary file not shown.
@@ -1,33 +1,93 @@
|
||||
Elastic License 2.0
|
||||
|
||||
Acceptance
|
||||
URL: https://www.elastic.co/licensing/elastic-license
|
||||
|
||||
## Acceptance
|
||||
|
||||
By using the software, you agree to all of the terms and conditions below.
|
||||
|
||||
Copyright License
|
||||
## Copyright License
|
||||
|
||||
The licensor grants you a non-exclusive, royalty-free, worldwide, non-transferable, non-sublicensable license to use, copy, distribute, make available, and prepare derivative works of the software.
|
||||
The licensor grants you a non-exclusive, royalty-free, worldwide,
|
||||
non-sublicensable, non-transferable license to use, copy, distribute, make
|
||||
available, and prepare derivative works of the software, in each case subject to
|
||||
the limitations and conditions below.
|
||||
|
||||
Limitations
|
||||
## Limitations
|
||||
|
||||
You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
|
||||
You may not provide the software to third parties as a hosted or managed
|
||||
service, where the service provides users with access to any substantial set of
|
||||
the features or functionality of the software.
|
||||
|
||||
You may not move, alter, disable, or circumvent any of the licensing features contained in the software, or remove or obscure any functionality in the software that is protected by the licensing features.
|
||||
You may not move, change, disable, or circumvent the license key functionality
|
||||
in the software, and you may not remove or obscure any functionality in the
|
||||
software that is protected by the license key.
|
||||
|
||||
You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor's trademarks is subject to applicable law.
|
||||
You may not alter, remove, or obscure any licensing, copyright, or other notices
|
||||
of the licensor in the software. Any use of the licensor’s trademarks is subject
|
||||
to applicable law.
|
||||
|
||||
Patents
|
||||
## Patents
|
||||
|
||||
The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import, and have imported, the software. This license is subject to the conditions of this license, and does not cover patent claims infringed by your modifications or your additions to the software. If you or your company make any written claim that the software infringes or contributes to an infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
|
||||
The licensor grants you a license, under any patent claims the licensor can
|
||||
license, or becomes able to license, to make, have made, use, sell, offer for
|
||||
sale, import and have imported the software, in each case subject to the
|
||||
limitations and conditions in this license. This license does not cover any
|
||||
patent claims that you cause to be infringed by modifications or additions to
|
||||
the software. If you or your company make any written claim that the software
|
||||
infringes or contributes to infringement of any patent, your patent license for
|
||||
the software granted under these terms ends immediately. If your company makes
|
||||
such a claim, your patent license ends immediately for work on behalf of your
|
||||
company.
|
||||
|
||||
Notices
|
||||
## Notices
|
||||
|
||||
You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms. If you modify the software, you must include prominent notices in modified copies stating that you have modified it.
|
||||
You must ensure that anyone who gets a copy of any part of the software from you
|
||||
also gets a copy of these terms.
|
||||
|
||||
No Other Rights
|
||||
If you modify the software, you must include in any modified copies of the
|
||||
software prominent notices stating that you have modified the software.
|
||||
|
||||
The terms do not imply any licenses other than those expressly granted under these terms.
|
||||
## No Other Rights
|
||||
|
||||
Termination
|
||||
These terms do not imply any licenses other than those expressly granted in
|
||||
these terms.
|
||||
|
||||
If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violations of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
|
||||
## Termination
|
||||
|
||||
If you use the software in violation of these terms, such use is not licensed,
|
||||
and your licenses will automatically terminate. If the licensor provides you
|
||||
with a notice of your violation, and you cease all violation of this license no
|
||||
later than 30 days after you receive that notice, your licenses will be
|
||||
reinstated retroactively. However, if you violate these terms after such
|
||||
reinstatement, any additional violation of these terms will cause your licenses
|
||||
to terminate automatically and permanently.
|
||||
|
||||
## No Liability
|
||||
|
||||
*As far as the law allows, the software comes as is, without any warranty or
|
||||
condition, and the licensor will not be liable to you for any damages arising
|
||||
out of these terms or the use or nature of the software, under any kind of
|
||||
legal claim.*
|
||||
|
||||
## Definitions
|
||||
|
||||
The **licensor** is the entity offering these terms, and the **software** is the
|
||||
software the licensor makes available under these terms, including any portion
|
||||
of it.
|
||||
|
||||
**you** refers to the individual or entity agreeing to these terms.
|
||||
|
||||
**your company** is any legal entity, sole proprietorship, or other kind of
|
||||
organization that you work for, plus all organizations that have control over,
|
||||
are under the control of, or are under common control with that
|
||||
organization. **control** means ownership of substantially all the assets of an
|
||||
entity, or the power to direct its management and policies by vote, contract, or
|
||||
otherwise. Control can be direct or indirect.
|
||||
|
||||
**your licenses** are all the licenses granted to you for the software under
|
||||
these terms.
|
||||
|
||||
**use** means anything you do with the software requiring one of your licenses.
|
||||
|
||||
**trademark** means trademarks, service marks, and similar rights.
|
||||
@@ -1,38 +1,181 @@
|
||||
<div align="center">
|
||||
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# WorldWideView
|
||||
|
||||
**WorldWideView** is a modular, real-time geospatial intelligence engine built on top of a CesiumJS 3D globe. It is designed to ingest live data streams, transform them through a generalized plugin system, and render them as high-performance visual layers.
|
||||
**The Open-Source, Plugin-Driven Geospatial Intelligence Engine**
|
||||
|
||||
As a real-time situational awareness platform, it turns raw geospatial signals—such as aircraft positions, maritime AIS, or satellite orbits—into interactive, cinematic layers on a high-fidelity 3D globe.
|
||||
*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.*
|
||||
|
||||
## Key Philosophies
|
||||
[](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)
|
||||
|
||||
- **Modular Intelligence**: Every data source is a plugin. The core engine is data-agnostic.
|
||||
- **High-Performance Rendering**: Engineered for scale using Cesium primitives to handle 100,000+ objects smoothly.
|
||||
- **Situational Awareness**: Designed for real-time updates and cinematic visualization (orientated icons, smooth tracking).
|
||||
- **Extensible & Open**: Add new intelligence layers without touching the core architecture.
|
||||

|
||||
|
||||
## Quick Start
|
||||
</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, maritime vessels, or conflict events—are ingested and rendered decoupled from the core 3D viewer.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **"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.
|
||||
- **Agent Bus (opt-in)**: HTTP+SSE control surface that lets an external tool — typically an MCP server fronting an LLM — fly the globe, toggle layers, and select entities in the running browser session. Default off; see [Agent Bus docs](docs/agent-bus.md).
|
||||
|
||||
## Core Technologies
|
||||
|
||||
- **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
|
||||
|
||||
## Project Architecture
|
||||
|
||||
WorldWideView separates the data acquisition layer from the frontend rendering loop, using a real-time event bus to bridge them.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph Data Sources
|
||||
A[Public APIs] -->|Poll| B[Data Engine Seeders]
|
||||
C[Microservices] -->|Stream| B
|
||||
end
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
mkdir worldwideview && cd worldwideview
|
||||
curl -fsSL https://raw.githubusercontent.com/silvertakana/worldwideview/main/self-host/setup.sh | bash
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
mkdir worldwideview; cd worldwideview
|
||||
Invoke-WebRequest -Uri https://raw.githubusercontent.com/silvertakana/worldwideview/main/self-host/setup.ps1 -UseBasicParsing | Invoke-Expression
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> Ensure you connect a PostgreSQL database via the `DATABASE_URL` environment variable for production deployments.
|
||||
|
||||
## Quick Start (Local Development)
|
||||
|
||||
To run the source code locally for contributing or developing:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/silvertakana/worldwideview.git
|
||||
cd worldwideview
|
||||
npm install
|
||||
npm run dev
|
||||
pnpm install
|
||||
pnpm run setup # generates .env.local with AUTH_SECRET
|
||||
pnpm run dev:all # boots the UI, cache layers, and the data engine
|
||||
```
|
||||
|
||||
Visit `http://localhost:3000` to see the live globe.
|
||||
|
||||
## Fair-Use Notice
|
||||
## Project Structure
|
||||
|
||||
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. It is believed that this constitutes a "fair use" of any such copyrighted material as provided for in section 107 of the US Copyright Law.
|
||||
The codebase utilizes a `pnpm` monorepo configuration:
|
||||
|
||||
## Key Documentation Sections
|
||||
```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
|
||||
```
|
||||
|
||||
- **[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.
|
||||
- **[Plugin System Guide](docs/PLUGIN_GUIDE.md)**: How to build and register custom data layers.
|
||||
- **[User Guide](docs/USER_GUIDE.md)**: Application features and navigation tips.
|
||||
## Plugin Ecosystem
|
||||
|
||||
---
|
||||
WorldWideView operates on an open-core philosophy. The platform itself is data-agnostic; all data sources are dynamically imported as plugins at runtime.
|
||||
|
||||
For a full list of resources, see the **[Documentation Index](docs/index.md)**.
|
||||
- **[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.
|
||||
|
||||
## Repository Ecosystem
|
||||
|
||||
WorldWideView is distributed across several specialized repositories:
|
||||
|
||||
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.
|
||||
6. **[`szski/wwv-mcp`](https://github.com/szski/wwv-mcp)**: Reference MCP server for driving the globe from an LLM agent (Claude Code, Claude Desktop, Cursor, Cline, …) via the [Agent Bus](docs/agent-bus.md). Contributor-hosted today; may move under the project org.
|
||||
|
||||
## Development & Workflow
|
||||
|
||||
- **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.
|
||||
|
||||
## Contributing
|
||||
|
||||
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
|
||||
|
||||
This project is licensed under the Elastic License 2.0 - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## Documentation Index
|
||||
|
||||
Explore our comprehensive documentation suite for detailed engineering insights:
|
||||
|
||||
- **[Project Overview](docs/project-overview.md)**: High-level value proposition and technology stack.
|
||||
- **[Architecture](docs/ARCHITECTURE.md)**: Plugin system, state management, data pipeline, and Cesium rendering deep-dive.
|
||||
- **[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.
|
||||
- **[Agent Bus](docs/agent-bus.md)**: Wiring an MCP server (or any external tool) to drive the running globe.
|
||||
- **[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).
|
||||
+161
@@ -0,0 +1,161 @@
|
||||
# WorldWideView — Implementation Roadmap
|
||||
|
||||
Each stage is **self-contained and demo-able**. Any stage can be shipped independently.
|
||||
|
||||
---
|
||||
|
||||
## Stage 1: Plugin SDK & Manifest Schema ✅
|
||||
**Demo:** "Here's the schema that defines a plugin. Our existing aviation plugin has a manifest file."
|
||||
|
||||
- [x] `plugin.json` manifest files for each existing plugin
|
||||
- [x] Manifest validation logic (`validateManifest()`)
|
||||
- [x] `type` field on `WorldPlugin` interface (`"data-layer" | "extension"`)
|
||||
- [x] `capabilities` field on `WorldPlugin` interface
|
||||
- [x] `@worldwideview/wwv-plugin-sdk` npm package — shared types published to npm
|
||||
|
||||
---
|
||||
|
||||
## Stage 2: Marketplace Browse UI (Static Catalog) ✅
|
||||
**Demo:** "Open the marketplace, see all available plugins with categories and search."
|
||||
|
||||
- [x] `worldwideview-marketplace` repo (Next.js)
|
||||
- [x] Browse page — grid of plugin cards with icons, descriptions, categories
|
||||
- [x] Search + category filter
|
||||
- [x] Plugin detail page (readme, version history, install count)
|
||||
|
||||
---
|
||||
|
||||
## Stage 3: Prisma ORM & Local Database ✅
|
||||
**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] PostgreSQL default: `DATABASE_URL` required
|
||||
- [x] `predev` script: `prisma migrate deploy`
|
||||
- [x] DB auto-creates on first run — zero manual setup
|
||||
|
||||
---
|
||||
|
||||
## Stage 4: Bridge API & One-Click Install ✅
|
||||
**Demo:** "Click 'Install' on marketplace → plugin appears in your local WWV instance."
|
||||
|
||||
- [x] `GET /api/marketplace/install-redirect` — session-based redirect install flow
|
||||
- [x] `GET /api/marketplace/grant-token` — issues marketplace JWT without install
|
||||
- [x] `GET /api/marketplace/status` — list installed plugins (session or JWT auth)
|
||||
- [x] `POST /api/marketplace/uninstall` — delete installed plugin record
|
||||
- [x] `GET /api/marketplace/load` — serve valid manifests to client at startup
|
||||
- [x] `GET /api/auth/setup-status` — CORS-enabled connection test endpoint
|
||||
- [x] `src/lib/marketplace/marketplaceToken.ts` — `issueMarketplaceToken()` / `verifyMarketplaceToken()`
|
||||
- [x] `src/lib/marketplace/auth.ts` — `validateMarketplaceAuth()` (session → JWT → legacy token)
|
||||
- [x] `src/lib/marketplace/registryClient.ts` — Ed25519 registry verification + 5-min cache
|
||||
- [x] Marketplace: `InstanceConfig`, `InstallButton`, `useInstalledPlugins`, `InstalledPluginCard`, Manage page
|
||||
- [x] NPM-driven submission: Admin enters package name → marketplace fetches + parses `"worldwideview"` block from `package.json`
|
||||
- [x] `NpmCache` table — decouples marketplace from live NPM registry
|
||||
|
||||
---
|
||||
|
||||
## Stage 5: AI & Sharing Features (Immediate User Value)
|
||||
**Demo:** "Chat with the AI to explore the globe, record a narrated briefing, and share the view via a URL."
|
||||
|
||||
- [ ] Unified Data Format schema (WWVDocument) with snapshot radius bounding
|
||||
- [ ] Base64url view link sharing (`#v=...`)
|
||||
- [ ] Shared `ActionExecutor` core for Animation & Copilot
|
||||
- [ ] Animation Engine (TrackScheduler, Player, overlays, TTS voice)
|
||||
- [ ] MCP Server (tools wrapping the action vocabulary)
|
||||
- [ ] Hybrid Spatial Awareness (Pre-computed summaries + MCP spatial query tools)
|
||||
|
||||
---
|
||||
|
||||
## Stage 6: Publisher Workflow
|
||||
**Demo:** "A plugin author submits their plugin. After review, it appears in the catalog."
|
||||
|
||||
- [ ] Marketplace user accounts (Supabase Auth — email/password + GitHub OAuth)
|
||||
- [ ] Publisher submission form (upload bundle, fill metadata, declare capabilities)
|
||||
- [ ] Admin review queue (approve/reject with notes)
|
||||
- [ ] Version management (semver, changelogs)
|
||||
- [ ] Publisher dashboard (install counts, download analytics)
|
||||
- [ ] Publisher namespaces (`publisher.plugin-name`)
|
||||
|
||||
---
|
||||
|
||||
## Stage 7: Cloud Platform & Accounts
|
||||
**Demo:** "User registers, gets [user].app.worldwideview.dev, installs plugins from marketplace."
|
||||
|
||||
- [ ] `app.worldwideview.dev` — auth/register/dashboard
|
||||
- [ ] Auto-provisioning on signup (tenant DB row → instance live immediately)
|
||||
- [ ] RLS tenant isolation in PostgreSQL
|
||||
- [ ] Cloud edition adapters (`auth.ts`, `storage.ts`, `tenant.ts`)
|
||||
- [ ] Runtime settings store + setup wizard
|
||||
- [ ] License key validation with RSA public key
|
||||
- [ ] Tier gating (free/pro/enterprise feature flags)
|
||||
- [ ] Cloudflare Turnstile + nginx rate limiting for bot prevention
|
||||
- [ ] SSO: marketplace redirects to `app.worldwideview.dev` for login
|
||||
|
||||
---
|
||||
|
||||
## Stage 8: Built-In Data Services
|
||||
**Demo:** "Aviation and maritime data with full history, served from api.worldwideview.dev."
|
||||
|
||||
- [ ] `api.worldwideview.dev` — aviation/maritime polling + persistence
|
||||
- [ ] Redesign aviation as declarative plugin pointing to `api.worldwideview.dev`
|
||||
- [ ] Redesign maritime the same way
|
||||
- [ ] History/timeline with `%t` parameter substitution
|
||||
- [ ] Snapshot capture (pro tier — counts toward storage quota)
|
||||
- [ ] API key proxy with per-tenant-per-plugin rate limiting and response caching
|
||||
|
||||
---
|
||||
|
||||
## Stage 9: Trust Tiers, Extensions & Polish
|
||||
**Demo:** "Install a verified extension plugin that adds cockpit view to aviation."
|
||||
|
||||
- [x] Ed25519-signed plugin registry (`GET /api/registry` on marketplace)
|
||||
- [x] Server-side trust stamping at install time
|
||||
- [x] Trust tier badges (`TrustBadge` component — Official / Verified / Unverified)
|
||||
- [x] Unverified plugin warning dialog (`UnverifiedPluginDialog` + `useMarketplaceSync`)
|
||||
- [ ] Extension plugin type support in `PluginManager`
|
||||
- [ ] Activation events and contribution points
|
||||
- [ ] Capability enforcement at runtime (`PluginPermissionError`)
|
||||
- [ ] Web Worker sandboxing for unverified plugins (`comlink`)
|
||||
- [ ] Reviews & ratings system
|
||||
- [ ] Extension packs (bundles of related plugins)
|
||||
- [ ] Auto-update mechanism (local: manual opt-in; cloud: automatic CDN swap)
|
||||
- [ ] Plausible/Umami self-hosted analytics
|
||||
|
||||
---
|
||||
|
||||
## Stage 10: Infrastructure & Monetization
|
||||
**Demo:** "Buy Pro, paste license key, unlock snapshot history and higher rate limits."
|
||||
|
||||
- [ ] Coolify on ThinkPad T480s — deploy all services
|
||||
- [ ] Uptime Kuma monitoring (all subdomains)
|
||||
- [ ] Stripe Checkout for license purchase
|
||||
- [ ] Storage quota enforcement (cloud only)
|
||||
- [ ] Stripe Connect for marketplace revenue split on paid plugins
|
||||
- [ ] Cloudflare R2 as CDN for plugin bundles (`cdn.worldwideview.dev`)
|
||||
|
||||
---
|
||||
|
||||
## Resolved Architectural Decisions
|
||||
|
||||
| Decision | Resolution |
|
||||
|---|---|
|
||||
| **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** | 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 |
|
||||
| **Plugin execution** | Client-side (browser), not server-side |
|
||||
| **Plugin architecture** | VS Code model — activation events, contribution points, namespaces |
|
||||
| **Server-side compute** | Not supported — third-party backends handle compute |
|
||||
| **Auth** | Auth.js on `app.worldwideview.dev`. `Credentials` (local), `@auth/supabase-adapter` (cloud). Marketplace uses SSO redirect |
|
||||
| **Instance provisioning** | Auto-provision on signup — just a DB row insert |
|
||||
| **API proxy** | `apikey` plugins routed through cached proxy, per-tenant-per-plugin rate limits |
|
||||
| **History** | Third-party `historyUrl` with `%t` (all tiers), WWV snapshot capture (pro only) |
|
||||
| **Built-in data** | Aviation/maritime → declarative plugins → `api.worldwideview.dev` |
|
||||
| **CI/CD** | GitHub Actions → GHCR → Coolify webhook |
|
||||
| **Plugin trust registry** | Ed25519-signed JSON, public key hardcoded in WWV, trust stamped server-side at install |
|
||||
| **Package manager** | pnpm workspaces (migrated from npm) |
|
||||
| **NPM submission flow** | Admin enters package name → marketplace infers manifest from `"worldwideview"` block in `package.json` |
|
||||
| **NPM caching** | `NpmCache` table decouples marketplace from live NPM registry |
|
||||
+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 @@
|
||||
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"
|
||||
@@ -0,0 +1,44 @@
|
||||
services:
|
||||
wwv:
|
||||
image: ghcr.io/silvertakana/worldwideview:latest
|
||||
pull_policy: always
|
||||
ports:
|
||||
- "3100: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}"
|
||||
# Provide the explicit public or host IP of the data engine for the frontend to use
|
||||
- "NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL=http://192.168.68.69:5002/stream"
|
||||
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:
|
||||
- "5433: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:
|
||||
@@ -0,0 +1,35 @@
|
||||
services:
|
||||
wwv-data-engine:
|
||||
image: ghcr.io/silvertakana/wwv-data-engine:latest
|
||||
pull_policy: always
|
||||
ports:
|
||||
- '5002:5000'
|
||||
env_file:
|
||||
- path: .env
|
||||
required: false
|
||||
environment:
|
||||
- PORT=5000
|
||||
- REDIS_URL=redis://wwv-redis:6379
|
||||
- DOWNLOAD_SEEDERS=true
|
||||
- GITHUB_PAT=${GITHUB_PAT:-}
|
||||
- DB_PATH=/app/data/engine.db
|
||||
depends_on:
|
||||
wwv-redis:
|
||||
condition: service_healthy
|
||||
volumes:
|
||||
- wwv-engine-data:/app/data
|
||||
- wwv-seeders:/app/seeders
|
||||
restart: unless-stopped
|
||||
|
||||
wwv-redis:
|
||||
image: redis:7-alpine
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
test: ['CMD', 'redis-cli', 'ping']
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 5
|
||||
|
||||
volumes:
|
||||
wwv-engine-data:
|
||||
wwv-seeders:
|
||||
@@ -0,0 +1,97 @@
|
||||
services:
|
||||
wwv:
|
||||
build:
|
||||
context: .
|
||||
args:
|
||||
- NEXT_PUBLIC_WWV_EDITION=${NEXT_PUBLIC_WWV_EDITION:-local}
|
||||
- NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL=${NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL:-}
|
||||
- NEXT_PUBLIC_SUPABASE_URL=${NEXT_PUBLIC_SUPABASE_URL:-}
|
||||
- NEXT_PUBLIC_SUPABASE_ANON_KEY=${NEXT_PUBLIC_SUPABASE_ANON_KEY:-}
|
||||
- NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=${NEXT_PUBLIC_GOOGLE_MAPS_API_KEY:-}
|
||||
- NEXT_PUBLIC_BING_MAPS_KEY=${NEXT_PUBLIC_BING_MAPS_KEY:-}
|
||||
- NEXT_PUBLIC_CESIUM_ION_TOKEN=${NEXT_PUBLIC_CESIUM_ION_TOKEN:-}
|
||||
- NEXT_PUBLIC_ADSENSE_CLIENT_ID=${NEXT_PUBLIC_ADSENSE_CLIENT_ID:-}
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- wwv-data:/app/data
|
||||
- ./public/plugins-local:/app/public/plugins-local:ro
|
||||
env_file:
|
||||
- path: .env
|
||||
required: false
|
||||
environment:
|
||||
- "AUTH_SECRET=${AUTH_SECRET:-default_secret_for_local_dev}"
|
||||
- "ENCRYPTION_MASTER_KEY=${ENCRYPTION_MASTER_KEY:-local_dev_encryption_key_change_in_prod}"
|
||||
- "WWV_DEMO_ADMIN_SECRET=${WWV_DEMO_ADMIN_SECRET:-}"
|
||||
- "WWV_BRIDGE_TOKEN=${WWV_BRIDGE_TOKEN:-}"
|
||||
- "DATABASE_URL=postgresql://postgres:postgres@db:5432/worldwideview?schema=public"
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 30s
|
||||
restart: unless-stopped
|
||||
|
||||
db:
|
||||
image: postgres:15-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: postgres
|
||||
POSTGRES_DB: worldwideview
|
||||
ports:
|
||||
- "${WWV_DB_PORT:-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
|
||||
|
||||
wwv-data-engine:
|
||||
image: ghcr.io/silvertakana/wwv-data-engine:latest
|
||||
command: >
|
||||
sh -c "
|
||||
echo 'Syncing workspace dependencies...' &&
|
||||
if [ -d \"$$SEEDERS_DIR/community\" ]; then cd $$SEEDERS_DIR/community && CI=true pnpm install --ignore-scripts && pnpm -r rebuild better-sqlite3 esbuild; fi &&
|
||||
if [ -d \"$$SEEDERS_DIR/private\" ]; then cd $$SEEDERS_DIR/private && CI=true pnpm install --ignore-scripts && pnpm -r rebuild better-sqlite3 esbuild; fi &&
|
||||
cd /app && node dist/server.js"
|
||||
ports:
|
||||
- "5000:5000"
|
||||
volumes:
|
||||
- ./local-seeders:/app/seeders
|
||||
environment:
|
||||
- PORT=5000
|
||||
- REDIS_URL=redis://wwv-redis:6379
|
||||
- SEEDERS_DIR=/app/seeders
|
||||
- DB_PATH=/app/data/engine.db
|
||||
depends_on:
|
||||
wwv-redis:
|
||||
condition: service_healthy
|
||||
restart: unless-stopped
|
||||
profiles:
|
||||
- engine
|
||||
|
||||
wwv-redis:
|
||||
image: redis:7-alpine
|
||||
healthcheck:
|
||||
test: ['CMD', 'redis-cli', 'ping']
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 5
|
||||
profiles:
|
||||
- engine
|
||||
|
||||
networks:
|
||||
coolify:
|
||||
external: true
|
||||
|
||||
volumes:
|
||||
wwv-data:
|
||||
postgres-data:
|
||||
@@ -0,0 +1,99 @@
|
||||
#!/bin/sh
|
||||
# ─── Docker Entrypoint ───────────────────────────────────────
|
||||
# Ensures the PostgreSQL database is migrated before starting
|
||||
# the application. DATABASE_URL must point to a PostgreSQL
|
||||
# instance (Supabase, self-hosted, etc).
|
||||
|
||||
set -e
|
||||
|
||||
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..."
|
||||
set +e
|
||||
MIGRATE_OUT=$(prisma migrate deploy 2>&1)
|
||||
MIGRATE_CODE=$?
|
||||
set -e
|
||||
|
||||
if [ $MIGRATE_CODE -eq 0 ]; then
|
||||
echo "[entrypoint] Migrations complete."
|
||||
elif echo "$MIGRATE_OUT" | grep -q "P3005"; then
|
||||
# P3005: schema exists but _prisma_migrations has no history.
|
||||
# Happens when 'prisma db push' (pnpm dev) ran before 'prisma migrate deploy' (docker).
|
||||
# Safe to auto-baseline only if there is zero schema drift.
|
||||
echo "[entrypoint] P3005: schema exists without migration history."
|
||||
echo "[entrypoint] Verifying schema matches migrations before auto-baselining..."
|
||||
set +e
|
||||
DIFF_OUT=$(prisma migrate diff \
|
||||
--from-url "$DATABASE_URL" \
|
||||
--to-schema-datamodel prisma/schema.prisma \
|
||||
--script 2>&1)
|
||||
DIFF_CODE=$?
|
||||
set -e
|
||||
if [ $DIFF_CODE -ne 0 ]; then
|
||||
echo "[entrypoint] Could not verify schema state — aborting." >&2
|
||||
echo "$DIFF_OUT" >&2
|
||||
exit 1
|
||||
fi
|
||||
# Positive-match for DDL keywords: any real drift emits at least one of these.
|
||||
# Checking for presence is safer than checking for absence of content.
|
||||
if echo "$DIFF_OUT" | grep -qiE "^(CREATE|ALTER|DROP|INSERT|UPDATE|DELETE|TRUNCATE)"; then
|
||||
echo "[entrypoint] Schema drift detected — cannot auto-baseline." >&2
|
||||
echo "[entrypoint] Run 'pnpm db:reset' to wipe and re-migrate, or resolve drift manually." >&2
|
||||
echo "$MIGRATE_OUT" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "[entrypoint] No drift detected. Baselining existing schema..."
|
||||
for migration_dir in prisma/migrations/*/; do
|
||||
if [ -f "${migration_dir}migration.sql" ]; then
|
||||
migration_name=$(basename "$migration_dir")
|
||||
echo "[entrypoint] Marking as applied: $migration_name"
|
||||
set +e
|
||||
prisma migrate resolve --applied "$migration_name"
|
||||
RESOLVE_CODE=$?
|
||||
set -e
|
||||
if [ $RESOLVE_CODE -ne 0 ]; then
|
||||
echo "[entrypoint] Failed to baseline $migration_name — aborting." >&2
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
done
|
||||
prisma migrate deploy
|
||||
echo "[entrypoint] Migrations complete."
|
||||
else
|
||||
echo "$MIGRATE_OUT" >&2
|
||||
exit $MIGRATE_CODE
|
||||
fi
|
||||
|
||||
# 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.
|
||||
+189
-51
@@ -1,62 +1,200 @@
|
||||
# System Architecture
|
||||
# Architecture
|
||||
|
||||
WorldWideView is a high-performance, event-driven geospatial intelligence engine. It is designed to ingest live, fast-moving signals—such as aviation ADS-B, maritime AIS, or satellite feeds—and transform them into cinematic, real-time visual layers on a 3D globe.
|
||||
WorldWideView is a **real-time geospatial intelligence engine**: a Next.js 16 frontend that renders live global data on a CesiumJS 3D globe, fed by a network of independent data seeders streaming over WebSockets. The whole platform is built on an "All-Bundle" plugin architecture, so data sources are decoupled from the core viewer and can be added, removed, or hot-swapped without touching rendering code.
|
||||
|
||||
## Module Breakdown
|
||||
This document is the deep-dive companion to the [README](../README.md). It is intended for human contributors who want to understand how the pieces fit before opening their first PR. For agent-facing rules and conventions, see [`AGENTS.md`](../AGENTS.md) at the repo root and the documents under [`.agents/rules/`](../.agents/rules/).
|
||||
|
||||
1. **`src/core/plugins`**: The registration and lifecycle management layer. Defines how plugins are booted and destroyed.
|
||||
2. **`src/core/data`**: The "Heartbeat" of the system.
|
||||
- **DataBus**: Decentralized event pipeline for all system actions.
|
||||
- **PollingManager**: Intelligent scheduler for external API calls with backoff logic.
|
||||
- **CacheLayer**: 2-stage persistent caching (In-Memory + IndexedDB).
|
||||
3. **`src/core/globe`**: The Rendering Engine.
|
||||
- **Cesium Integration**: Low-level control over the Cesium Viewer.
|
||||
- **EntityRenderer**: High-performance "Primitive" renderer.
|
||||
4. **`src/plugins`**: Domain-specific logic (Aviation, Maritime, etc.).
|
||||
|
||||
## Performance: Primitives vs. Entities
|
||||
|
||||
One of our core design decisions is using **Cesium Primitives** instead of the standard high-level **Entity API** for high-count datasets.
|
||||
|
||||
| Feature | Entity API | Primitive API (WWV) |
|
||||
|---|---|---|
|
||||
| **Abstration** | High (Easy to use) | Low (Direct GPU access) |
|
||||
| **Overhead** | Significant per-entity JS objects | Minimal (Batched rendering) |
|
||||
| **Max Capacity** | ~1,000 entities | **100,000+ points/billboards** |
|
||||
| **WWV Use Case** | Info window content | Live data point visualization |
|
||||
|
||||
**Why?** The Entity API in Cesium is great for rich features but triggers significant CPU overhead when managing thousands of moving objects. By using `PointPrimitiveCollection` and `BillboardCollection`, WorldWideView batches these draw calls, ensuring 60FPS even with dense global data.
|
||||
|
||||
## Data Pipeline (Example: Aviation)
|
||||
|
||||
The following diagram trace the journey of a single data point from a remote sensor to the user's screen:
|
||||
## System Overview
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant S as Remote API (e.g. OpenSky)
|
||||
participant P as Plugin (AviationPlugin)
|
||||
participant D as DataBus
|
||||
participant R as EntityRenderer
|
||||
participant G as GPU (Cesium)
|
||||
flowchart TD
|
||||
subgraph "Data Sources"
|
||||
A[Public APIs] -->|Poll| B[Data Engine Seeders]
|
||||
C[Custom Microservices] -->|Stream| B
|
||||
end
|
||||
|
||||
Note over S, P: Polling Interval (e.g. 30s)
|
||||
S->>P: raw JSON data
|
||||
rect rgb(200, 230, 255)
|
||||
Note right of P: Mapping to GeoEntity
|
||||
P->>P: parse, filter, sanitize
|
||||
subgraph "Engine Tier"
|
||||
B -->|WebSocket /stream| D[WsClient]
|
||||
end
|
||||
P->>D: emit("dataUpdated", { entities })
|
||||
D->>R: trigger render cycle
|
||||
rect rgb(255, 230, 200)
|
||||
Note right of R: Batch Update Primitives
|
||||
R->>G: update collection buffer
|
||||
|
||||
subgraph "Frontend Pipeline"
|
||||
D --> E[DataBus<br/>typed pub/sub]
|
||||
E -->|"_hydrateSnapshot()"| F[Zustand Store<br/>9 slices]
|
||||
F -->|Memoized visible entities| G[EntityRenderer]
|
||||
G -->|Primitive collections| H[CesiumJS Globe]
|
||||
H --> I[AnimationLoop<br/>horizon culling + LOD]
|
||||
end
|
||||
|
||||
subgraph "Plugin Layer"
|
||||
J[PluginRegistry] -->|"loadPluginFromManifest"| K[Dynamic ES module imports]
|
||||
J -.->|register| E
|
||||
end
|
||||
G-->>G: 60FPS visualization
|
||||
```
|
||||
|
||||
## Design Principles
|
||||
The strict unidirectional flow — engine → bus → store → renderer — is what lets the system push sub-second updates for thousands of entities without React render-cycle bottlenecks.
|
||||
|
||||
- **Single Responsibility (SRP)**: Plugins only handle data mapping; they don't know about the UI or the Cache.
|
||||
- **Dependency Inversion**: The `PluginManager` communicates with plugins through the `WorldPlugin` interface, allowing new plugins to be added without modifying core code.
|
||||
- **Event-Driven Architecture**: The system is reactive. Components subscribe to what they need, reducing prop-drilling and unnecessary re-renders.
|
||||
- **Defensive Programming**: All external API calls in plugins are wrapped in error boundaries and handled by the `PollingManager`'s backoff logic to prevent system-wide failures.
|
||||
## Plugin System (Core Abstraction)
|
||||
|
||||
Every data source in WorldWideView is a **plugin** implementing the `WorldPlugin` interface from [`@worldwideview/wwv-plugin-sdk`](../packages/wwv-plugin-sdk/). The plugin's lifecycle plugs into a real-time WebSocket firehose:
|
||||
|
||||
```text
|
||||
PluginRegistry.register() → PluginManager.registerPlugin()
|
||||
→ plugin.initialize(context)
|
||||
|
||||
Visibility Toggle → DataBusSubscriber subscribes to layer via WsClient
|
||||
→ Engine responds with instantaneous WebSocket snapshots over /stream
|
||||
→ WsClient pipes to DataBus.emit("dataUpdated", WsStreamPayload)
|
||||
→ Store → EntityRenderer → Globe
|
||||
```
|
||||
|
||||
Four plugin architectures coexist under the "All-Bundle Model":
|
||||
|
||||
1. **Data Engine Seeder** — A lightweight `seeder.mjs` script run by the dynamic `wwv-data-engine` runner. (Previously a standalone microservice container; the runner replaces that.)
|
||||
2. **Dynamic CDN Loaded (Bundle)** — Externally developed plugins, dynamically imported at runtime via ES module CDNs (e.g. version-pinned `unpkg.com` 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 mediate frontend interactions. (Previously `DeclarativePlugin`.)
|
||||
|
||||
All four are now dynamically imported at runtime as ES module bundles via `loadPluginFromManifest`, which uses `import(/* webpackIgnore: true */ entry)`. The legacy `StaticDataPlugin` and `DeclarativePlugin` runtimes are fully deprecated.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Plugin types are re-exported from the SDK through `src/core/plugins/PluginTypes.ts` and `src/core/plugins/PluginManifest.ts`. The **source of truth is always `@worldwideview/wwv-plugin-sdk`** — never define plugin types locally.
|
||||
|
||||
For the contributor checklist when authoring a plugin, see [`.agents/skills/worldwideview-plugin-creation/`](../.agents/skills/) and the [Plugin Quickstart](plugin-quickstart.md).
|
||||
|
||||
## State Management
|
||||
|
||||
WorldWideView uses a Zustand store split into **nine slices**, each in its own file under [`src/core/state/`](../src/core/state/):
|
||||
|
||||
| Slice | Responsibility |
|
||||
|---|---|
|
||||
| `globe` | Camera position, imagery layers, scene settings |
|
||||
| `layers` | Per-plugin visibility toggles |
|
||||
| `timeline` | Playback range, current time, play/pause |
|
||||
| `ui` | Panel open/closed states, selected entity |
|
||||
| `filter` | Plugin filter expressions, applied via `filterEngine` |
|
||||
| `data` | Entity cache (`entitiesByPlugin`), websocket connection state |
|
||||
| `config` | Plugin settings, polling intervals, API keys |
|
||||
| `favorites` | User-bookmarked entities |
|
||||
| `geojson` | Custom GeoJSON overlays |
|
||||
|
||||
Access patterns:
|
||||
|
||||
- React components: `const camera = useStore((s) => s.camera);`
|
||||
- Outside React (animation loop, hooks setup): `const state = useStore.getState();`
|
||||
- Plugin settings: `configSlice.dataConfig.pluginSettings[pluginId]`
|
||||
- Polling intervals: `configSlice.dataConfig.pollingIntervals[pluginId]`
|
||||
|
||||
The animation loop deliberately snapshots state once per frame via `getState()` rather than subscribing — `requestAnimationFrame` is the loop driver, so adding a Zustand subscription would just duplicate ticks.
|
||||
|
||||
## Data Pipeline
|
||||
|
||||
Real-time data follows a strict unidirectional path optimised for sub-second updates:
|
||||
|
||||
```text
|
||||
Engine push /stream → DataBusSubscriber WsClient router
|
||||
→ WsClient.handleMessage() → DataBus.emit("websocketData", WsStreamPayload)
|
||||
→ DataBusSubscriber → _hydrateSnapshot() → Store.entitiesByPlugin
|
||||
→ GlobeView (memoised visible entities)
|
||||
→ EntityRenderer (billboard/point primitives)
|
||||
→ AnimationLoop (horizon culling, hover/selection)
|
||||
→ StackManager (co-located entity grouping)
|
||||
```
|
||||
|
||||
The `DataBus` is a custom typed pub/sub singleton (see [`src/core/data/DataBus.ts`](../src/core/data/DataBus.ts)). It exists specifically to bypass React's render cycle for high-frequency events — store updates are batched into the Zustand store, but raw stream events ride the bus directly.
|
||||
|
||||
## Data Engine & Seeders
|
||||
|
||||
The data engine ([`wwv-data-engine`](https://github.com/silvertakana/wwv-data-engine), public) is a **content-agnostic runner**. It discovers and executes seeder scripts from a configurable directory; the engine itself knows nothing about specific data sources.
|
||||
|
||||
- **Local development**: The engine runs via Docker Compose on port 5001, reading seeders dynamically from `local-seeders/` (split into `community` and `private` tiers).
|
||||
- **Production**: The engine container on Coolify downloads release bundles from `wwv-seeders-community` and `wwv-seeders-private` on startup, unzipping them into `/app/seeders`.
|
||||
- **Split-routing**: `resolveEngineUrl` prioritises the local dev engine (`ws://localhost:5001/stream`) for local testing — 12-Factor App methodology — and falls back to cloud-hosted endpoints (e.g. `wss://dataenginev2.worldwideview.dev/stream`) when nothing local is available.
|
||||
|
||||
### Agnostic Frontend
|
||||
|
||||
WorldWideView's frontend is a **completely agnostic renderer**. It has no concept of a "unified" data engine. If 30 plugins each declare a different `streamUrl`, the application opens 30 WebSocket connections; it just so happens that the default plugin set shares `wwv-data-engine`, but the platform is 100% decentralised.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Each plugin is a self-contained package and **MUST explicitly declare its own `streamUrl` in its manifest or config.** Do not assume the frontend acts as a unified pipe.
|
||||
|
||||
### Dual-Output Engine
|
||||
|
||||
Each seeder automatically exposes both a WebSocket stream (`/stream`) and a REST API endpoint (`/api/[plugin-id]`). Plugins can consume either depending on their data shape — bursty / live → stream, slow-moving / on-demand → REST.
|
||||
|
||||
### Scope Boundary (the 99 / 1 Rule)
|
||||
|
||||
The engine handles standard caching and broadcasting — the 99% case. Plugins that require complex on-demand compute (the 1%) must host their own custom backend; the engine intentionally does not grow features for them.
|
||||
|
||||
## Rendering Pipeline
|
||||
|
||||
The renderer is where most of WorldWideView's engineering depth lives. Three design choices drive the performance envelope:
|
||||
|
||||
### Primitive-based rendering
|
||||
|
||||
We use [`PointPrimitiveCollection`](https://cesium.com/learn/cesiumjs/ref-doc/PointPrimitiveCollection.html), `BillboardCollection`, `LabelCollection`, and `PolylineCollection` directly — **not** the Cesium Entity API. The Entity API is convenient but allocates per-entity ECS-style state that gets expensive past a few thousand entities. Primitive collections batch their state into typed GPU buffers, so 10k+ live entities still hold 60 fps on a moderate laptop.
|
||||
|
||||
Collections are tracked per-viewer via a module-level `WeakMap<CesiumViewer, PrimitiveCollections>` in [`src/core/globe/EntityRenderer.ts`](../src/core/globe/EntityRenderer.ts), keeping the renderer multi-viewer-capable and ensuring collections GC cleanly when a viewer is torn down.
|
||||
|
||||
### Chunked processing
|
||||
|
||||
Large datasets (10k+ entities) are rendered via [`ChunkedProcessor`](../src/core/globe/ChunkedProcessor.ts) in 500-entity chunks across multiple microtasks, so adding a new plugin layer never blocks the main thread long enough to drop a frame.
|
||||
|
||||
### Horizon culling and LOD
|
||||
|
||||
The animation loop performs **manual horizon culling** in [`AnimationLoop.ts`](../src/core/globe/AnimationLoop.ts) using a single dot-product against the Earth radius — much cheaper than depth-testing thousands of primitives every frame, and tunable for "entities just below the horizon should still be visible" semantics that depth-testing can't express.
|
||||
|
||||
Entities of `type: "model"` are promoted to full 3D glTF models at close range via the LOD system in [`useModelRendering.ts`](../src/core/globe/hooks/useModelRendering.ts) — so an aircraft at 50 nm range is a tinted billboard, but at 5 nm it's a textured plane model with the right wing geometry.
|
||||
|
||||
### Stack / Spiderifier
|
||||
|
||||
When multiple entities share a screen-space cluster (busy ports, busy airspaces), [`StackManager`](../src/core/globe/StackManager.ts) groups them and [`stackAnimation`](../src/core/globe/stackAnimation.ts) handles the spiderification expansion when a stack is clicked.
|
||||
|
||||
### Entity-type rules
|
||||
|
||||
> [!WARNING]
|
||||
> When returning `CesiumEntityOptions` from a plugin's `renderEntity()`:
|
||||
>
|
||||
> - **Points**: Use `type: "point"` with `color`, `size`, `outlineColor`, `outlineWidth`.
|
||||
> - **Billboards**: Use `type: "billboard"` with `iconUrl`, `color`, `iconScale`.
|
||||
> - **NEVER mix**: Do not set `size` / `outlineWidth` / `outlineColor` on a billboard — Cesium silently clips the GPU upload and the icon disappears.
|
||||
|
||||
## Edition System
|
||||
|
||||
WorldWideView ships in three editions, controlled by the `NEXT_PUBLIC_WWV_EDITION` environment variable. Feature flags are derived from this in [`src/core/edition.ts`](../src/core/edition.ts).
|
||||
|
||||
| Edition | Auth | Use case |
|
||||
|---|---|---|
|
||||
| `local` | Enabled (NextAuth credentials) | Self-hosted single-user / small-team deployments |
|
||||
| `cloud` | Enabled | Managed cloud instance with multi-tenancy |
|
||||
| `demo` | Disabled (optional admin via `WWV_DEMO_ADMIN_SECRET`) | Public demo deployments |
|
||||
|
||||
Edition isn't just an auth toggle — it also gates which marketplace endpoints are queried, which default plugins boot, and whether destructive admin actions are reachable.
|
||||
|
||||
## Key Source Files
|
||||
|
||||
Quick map of the load-bearing modules:
|
||||
|
||||
| Path | Role |
|
||||
|---|---|
|
||||
| [`src/core/plugins/PluginManager.ts`](../src/core/plugins/PluginManager.ts) | Core plugin registry. Instantiates plugins, calls `initialize()`, manages lifecycle. |
|
||||
| [`src/core/plugins/loaders/InstalledPluginsLoader.ts`](../src/core/plugins/loaders/InstalledPluginsLoader.ts) | Dynamic ES module loader for marketplace plugins (`import(/* webpackIgnore: true */ entry)`). |
|
||||
| [`src/core/data/DataBus.ts`](../src/core/data/DataBus.ts) | Typed pub/sub singleton — the high-frequency event channel. |
|
||||
| [`src/core/data/WsClient.ts`](../src/core/data/WsClient.ts) | WebSocket router. Pipes engine `/stream` messages onto the DataBus. |
|
||||
| [`src/core/globe/GlobeView.tsx`](../src/core/globe/GlobeView.tsx) | The Cesium viewer container. Imagery layers, camera setup, primitive collection wiring. |
|
||||
| [`src/core/globe/EntityRenderer.ts`](../src/core/globe/EntityRenderer.ts) | Translates store entities into Cesium primitives. Hot path for 10k+ entities. |
|
||||
| [`src/core/globe/AnimationLoop.ts`](../src/core/globe/AnimationLoop.ts) | Per-frame update: horizon culling, hover/selection, model LOD promotion. |
|
||||
| [`src/core/state/store.ts`](../src/core/state/store.ts) | Zustand store registry linking the nine slices. |
|
||||
|
||||
## Further Reading
|
||||
|
||||
For deeper coverage of specific subsystems, see the rule files under [`.agents/rules/`](../.agents/rules/):
|
||||
|
||||
- [`platform-architecture.md`](../.agents/rules/platform-architecture.md) — high-level platform goals, product vision, Edition System
|
||||
- [`application-architecture.md`](../.agents/rules/application-architecture.md) — Next.js frontend, Zustand, CesiumJS integration
|
||||
- [`plugin-architecture.md`](../.agents/rules/plugin-architecture.md) — plugin lifecycle, capability declarations, seeders
|
||||
- [`marketplace-architecture.md`](../.agents/rules/marketplace-architecture.md) — dynamic plugin installation, DB sync, CDN loading
|
||||
- [`cesium-rendering.md`](../.agents/rules/cesium-rendering.md) — globe rendering, entity types, primitives, LOD, culling
|
||||
- [`state-management.md`](../.agents/rules/state-management.md) — slice access patterns, plugin settings
|
||||
- [`data-engine-architecture.md`](../.agents/rules/data-engine-architecture.md) — engine internals, seeder loading, workspace dependencies
|
||||
|
||||
For getting started as a contributor, see [Development](development.md), [Plugin Quickstart](plugin-quickstart.md), and [Plugin Advanced](plugin-advanced.md).
|
||||
@@ -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,81 +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+)
|
||||
- **NPM**: v9 or higher
|
||||
- **Browser**: Chrome, Firefox, or Edge (CesiumJS requires WebGL support)
|
||||
|
||||
## Environment Setup
|
||||
|
||||
WorldWideView requires several API keys to function correctly. You can copy the provided `.env.example` file to `.env.local` and fill in the values:
|
||||
|
||||
```bash
|
||||
cp .env.example .env.local
|
||||
```
|
||||
|
||||
Or manually create a `.env.local` file in the root directory:
|
||||
|
||||
```env
|
||||
# Cesium Ion Access Token (Required for terrain and default imagery)
|
||||
NEXT_PUBLIC_CESIUM_ION_TOKEN=your_token_here
|
||||
|
||||
# Bing Maps API Key (Optional, for high-res imagery)
|
||||
NEXT_PUBLIC_BING_MAPS_KEY=your_key_here
|
||||
|
||||
# Supabase Configuration (Required for persistence and historical data)
|
||||
NEXT_PUBLIC_SUPABASE_URL=your_project_url
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
|
||||
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
|
||||
```
|
||||
|
||||
## Running Locally
|
||||
|
||||
1. **Install Dependencies**:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Start Dev Server**:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
*Note: Our `dev` script automatically runs `predev` to copy Cesium assets to the public directory.*
|
||||
|
||||
3. **Open Browser**:
|
||||
Navigate to [http://localhost:3000](http://localhost:3000).
|
||||
|
||||
## Folder Structure Explanation
|
||||
|
||||
Understanding the project layout:
|
||||
|
||||
```text
|
||||
worldwideview/
|
||||
├── .agents/ # Agentic AI workflows and memory
|
||||
├── docs/ # Project documentation (Markdowns)
|
||||
├── public/ # Static assets (Imagery, GeoJSON, 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 polling
|
||||
└── plugins/ # Feature-specific 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.
|
||||
|
||||
---
|
||||
|
||||
> [!IMPORTANT]
|
||||
> If you encounter issues with hot reloading (HMR), ensure you are running with the `--webpack` flag in the dev script (this is the default in our `package.json`).
|
||||
@@ -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.
|
||||
@@ -0,0 +1,166 @@
|
||||
# Agent Bus — driving WWV from external tools
|
||||
|
||||
## Overview
|
||||
|
||||
The Agent Bus is an opt-in HTTP+SSE surface that lets a trusted external process — most commonly a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server fronting an LLM agent — drive the running WWV browser session. The agent can fly the globe, toggle layers, focus entities, and select things by posting JSON actions to a server endpoint, which fans them out over SSE to every browser tab belonging to the same logged-in user.
|
||||
|
||||
Read-only camera and engine queries already work via the existing REST API. The Agent Bus is the missing **write path**.
|
||||
|
||||
```
|
||||
LLM client ──MCP──▶ szski/wwv-mcp ──HTTP──▶ /api/agent/publish ──SSE──▶ browser
|
||||
(Claude, Cursor, …) (separate repo) (this PR adds these) (Cesium flies)
|
||||
```
|
||||
|
||||
## Enabling the bus
|
||||
|
||||
The bus is **off by default**. The subscriber early-returns and no SSE connection is opened. You explicitly opt in via a build-time environment variable.
|
||||
|
||||
### In Docker
|
||||
|
||||
Pass the ARG at build time:
|
||||
|
||||
```sh
|
||||
docker build \
|
||||
--build-arg NEXT_PUBLIC_WWV_AGENT_BUS_ENABLED=true \
|
||||
-t worldwideview .
|
||||
```
|
||||
|
||||
### In a Coolify / hosted build
|
||||
|
||||
Set `NEXT_PUBLIC_WWV_AGENT_BUS_ENABLED=true` in the build environment. Because it's a `NEXT_PUBLIC_*` variable, it is inlined into the JavaScript bundle at `next build` time — runtime-only env changes will not enable it.
|
||||
|
||||
### Verifying it's on
|
||||
|
||||
On a fresh page load, open the browser DevTools console. You should see a one-line build banner:
|
||||
|
||||
```
|
||||
[wwv build] id=1714572934123 built_at=2026-05-13T18:35:34Z agent_bus=on
|
||||
```
|
||||
|
||||
If `agent_bus=off` after enabling the env var, the build did not pick up the variable — re-check that it was passed as `--build-arg` (Docker) or set before `next build` ran (other hosts).
|
||||
|
||||
You can also hit `/api/build` to confirm the served bundle's build id and flag state.
|
||||
|
||||
## Using it — quick smoke test with curl
|
||||
|
||||
To verify the bus end-to-end without an MCP server, log into WWV in your browser, grab your `__Secure-authjs.session-token` cookie value from DevTools, and POST an action:
|
||||
|
||||
```sh
|
||||
curl -X POST https://your-wwv-host/api/agent/publish \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Cookie: __Secure-authjs.session-token=PASTE_TOKEN_HERE" \
|
||||
-d '{"action":"fly_to","lat":35.7796,"lon":-78.6382,"distance":50000}'
|
||||
```
|
||||
|
||||
If the bus is enabled and the cookie is valid, the open tab will fly to Raleigh and the response will be:
|
||||
|
||||
```json
|
||||
{ "ok": true, "delivered": 1, "subscribers": 1 }
|
||||
```
|
||||
|
||||
`subscribers: 0` means the bus is off in the build, the cookie's user has no open tabs, or the env var wasn't applied — see *Verifying* above.
|
||||
|
||||
## Using it — wiring an MCP server
|
||||
|
||||
The reference MCP server for WWV is published at **[szski/wwv-mcp](https://github.com/szski/wwv-mcp)**. It exposes 15 tools (`globe_fly_to`, `layer_toggle`, `engine_query`, `geocode`, `system_status`, etc.) and works with any MCP-aware client (Claude Code, Claude Desktop, Cursor, Continue, Cline).
|
||||
|
||||
> [!NOTE]
|
||||
> `szski/wwv-mcp` lives in a contributor's namespace today and may move under the project's own organization later. Update the install URL accordingly when that happens.
|
||||
|
||||
### Install (Node)
|
||||
|
||||
```sh
|
||||
git clone https://github.com/szski/wwv-mcp
|
||||
cd wwv-mcp
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
Then store credentials so the MCP server can auto-login at startup:
|
||||
|
||||
```sh
|
||||
mkdir -p ~/.config/wwv-mcp
|
||||
cat > ~/.config/wwv-mcp/credentials <<'EOF'
|
||||
[email protected]
|
||||
WWV_PASSWORD=your-password
|
||||
EOF
|
||||
chmod 600 ~/.config/wwv-mcp/credentials
|
||||
```
|
||||
|
||||
### Install (Docker)
|
||||
|
||||
If a published image exists at `szski/wwv-mcp` (or wherever the maintainer mirrors it), no install step is needed — the MCP client config below uses `docker run` to launch the server on demand.
|
||||
|
||||
### Client config — Claude Code
|
||||
|
||||
Edit `~/.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wwv": {
|
||||
"command": "node",
|
||||
"args": ["/absolute/path/to/wwv-mcp/dist/index.js"],
|
||||
"env": {
|
||||
"WWV_BASE_URL": "https://your-wwv-host.example",
|
||||
"WWV_ENGINE_URL": "http://localhost:5001"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or, with Docker:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wwv": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "-i", "--rm",
|
||||
"-e", "WWV_BASE_URL=http://host.docker.internal:3000",
|
||||
"-e", "WWV_ENGINE_URL=http://host.docker.internal:5001",
|
||||
"szski/wwv-mcp:latest"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then `/mcp` in Claude Code should list `wwv` with all 15 tools.
|
||||
|
||||
### Client config — Claude Desktop
|
||||
|
||||
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). The `mcpServers.wwv` block is identical to Claude Code above.
|
||||
|
||||
### Client config — Cursor, Continue, Cline
|
||||
|
||||
Each of these reads an MCP server list in its own settings UI but the shape of the entry — `command` + `args` + `env` — is the same as Claude Code's. See your client's MCP docs for the exact location of its config file.
|
||||
|
||||
### Verifying the wiring
|
||||
|
||||
Once configured, ask the agent something like *"What's the status of the WWV system?"* — it should call `system_status` and report back. If you see `agent_bus_enabled: false`, the bus is off in the WWV build; fix that before trying write tools like `globe_fly_to`.
|
||||
|
||||
## Security and multi-tenancy
|
||||
|
||||
- **Default off.** Without the env var, the subscriber doesn't open a connection, the publish endpoint exists but has no subscribers, and the bundle's dead-code elimination removes the `EventSource` constructor entirely.
|
||||
- **Auth gated.** Both `/api/agent/publish` and `/api/agent/stream` use the same `auth()` helper as the rest of the marketplace API. No tokens — just the existing Auth.js session cookie.
|
||||
- **Per-user scoping.** Subscriptions live in `Map<userId, …>`, so a publish from user A's session never reaches user B's stream, even though both sit on the same Node process. Multi-tenant deployments are safe.
|
||||
- **Same trust model as a browser tab.** An MCP server "acts as the user" by holding the user's session cookie. If you wouldn't trust a browser tab on the same machine, don't give an MCP server the cookie.
|
||||
- **Single-process only.** The `AgentBus` is in-memory and process-local. Multi-instance deployments behind a load balancer would need a Redis pub/sub adapter — about 30 lines of additional code, not included here.
|
||||
|
||||
## Endpoint reference
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/agent/stream` | SSE channel. Auth-gated. Streams `AgentAction` JSON events for the connected user. Heartbeat every 25s. |
|
||||
| `POST` | `/api/agent/publish` | Accept an `AgentAction` JSON body, broadcast to the publishing user's subscribers, return `{ok, delivered, subscribers}`. |
|
||||
| `GET` | `/api/build` | Build id + ISO timestamp + `NEXT_PUBLIC_*` flag state. Used by `AgentBusSubscriber` to print the build banner. |
|
||||
|
||||
`AgentAction` is currently a six-verb union: `fly_to`, `face_towards`, `layer_toggle`, `highlight_layer`, `select_entity`, `ping`. The shape is `{action: string, …payload}` JSON, so additive changes are backwards-compatible.
|
||||
|
||||
## Companion repos
|
||||
|
||||
- **[szski/wwv-mcp](https://github.com/szski/wwv-mcp)** — reference MCP server. 15 tools. Required for any LLM-driven use of the bus.
|
||||
- **[silvertakana/wwv-data-engine](https://github.com/silvertakana/wwv-data-engine)** — separate repo, supplies the read-only `engine_query` data that the MCP server's read tools wrap.
|
||||
+154
@@ -0,0 +1,154 @@
|
||||
# ADR-001: Decentralized Plugin Authentication & SSRF Mitigation
|
||||
|
||||
## Status
|
||||
Proposed *(Pending Review)*
|
||||
|
||||
## Date
|
||||
2026-05-14
|
||||
|
||||
## Related
|
||||
- **Dependencies:** `docs/ARCHITECTURE.md` (Agnostic Client principle), `prisma/schema.prisma` (existing Local App Postgres integration).
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The WorldWideView ecosystem faces four interlocking security and scalability problems:
|
||||
|
||||
1. **The SSRF Liability:** The Local App uses generic proxy routes (`/api/camera/proxy`) to bypass browser CORS restrictions. These lack robust SSRF hardening (no DNS rebinding defense, no private IP blocking), exposing the host LAN.
|
||||
2. **The CORS Barrier:** Browser-enforced Cross-Origin Resource Sharing (CORS) prevents the agnostic frontend from connecting directly to independent Data Engines via standard HTTP.
|
||||
3. **The Centralization Bottleneck:** If every Data Engine queries the Marketplace database to verify a user's subscription on every frame, the Marketplace becomes a catastrophic bottleneck.
|
||||
4. **The Credential Interception Threat:** Passing credentials via simple URL redirects during setup exposes them to browser history theft and MITM attacks.
|
||||
|
||||
To resolve these, we are adopting an umbrella "Token Exchange" architecture, broken down into four specific decisions.
|
||||
|
||||
---
|
||||
|
||||
## Decisions
|
||||
|
||||
### ADR-001A: Direct WebSocket Data Plane
|
||||
We mandate that heavy data streams utilize WebSockets (`wss://`). Browsers do not apply CORS preflight to WebSockets, allowing direct connections.
|
||||
* **Security Constraint:** Because CORS is bypassed, Data Engines MUST explicitly validate the `Origin`, `Host`, TLS state, and expected tenant/plugin metadata upon connection.
|
||||
|
||||
### ADR-001B: Marketplace-Issued JWT Tickets
|
||||
To enforce monetization without centralized database queries, we implement a stateless Token Exchange via Asymmetric Cryptography (Ed25519).
|
||||
* **The JWT Contract:** The token MUST contain the following claims:
|
||||
* `iss`: `https://marketplace.worldwideview.dev`
|
||||
* `sub`: The user's unique ID.
|
||||
* `aud`: **Crucial.** The specific Data Engine or plugin ID. Tokens MUST be audience-bound to prevent a valid token for Engine A being replayed against Engine B.
|
||||
* `exp`: Expiration (exactly 5 minutes from issuance).
|
||||
* `iat`: Issued at.
|
||||
* `jti`: Unique token identifier.
|
||||
* `tier`: Subscription level (e.g., "pro").
|
||||
* `scope`: Specific entitlements.
|
||||
|
||||
### ADR-001C: PKCE Bootstrap (The API Key)
|
||||
The Local App acts as the credential holder. It uses the OAuth 2.0 Authorization Code flow with PKCE to securely acquire a **long-lived refresh credential** (The API Key).
|
||||
* **API Key Lifetime:** The API Key does not expire automatically but is bound to the specific device/installation. It rotates manually via the Marketplace UI or automatically upon suspicion of compromise.
|
||||
|
||||
### ADR-001D: SSRF Proxy Hardening
|
||||
For legacy plugins (e.g., Webcams) that *cannot* use WebSockets, the local proxy must be hardened.
|
||||
* **Constraints:** We will remove generic proxying where possible. Where proxying remains, we enforce:
|
||||
1. Exact HTTPS origin allowlists.
|
||||
2. Blocking of private / link-local / loopback IPs *after* DNS resolution.
|
||||
3. Re-resolving or pinning DNS to defend against DNS rebinding.
|
||||
4. Rejecting redirects to non-allowlisted hosts.
|
||||
5. Strict payload size and time limits.
|
||||
|
||||
---
|
||||
|
||||
## Threat Model & Non-Goals
|
||||
|
||||
**In Scope:**
|
||||
* Defending against external attackers on the user's LAN (via SSRF hardening).
|
||||
* Preventing interception of the long-lived API key during setup (via PKCE).
|
||||
* Preventing URL/Header credential leakage (via First-Message Auth).
|
||||
|
||||
**Non-Goals (Accepted Residual Risks):**
|
||||
* Defending against compromised Local App hosts (root OS access).
|
||||
* Defending against XSS in the Local App frontend (token theft via JS).
|
||||
* Defending against malicious browser extensions (full session access).
|
||||
* Real-time subscription revocation for *already issued* 5-minute tickets.
|
||||
|
||||
---
|
||||
|
||||
## Operational Implementation Details
|
||||
|
||||
### 1. Library Selection
|
||||
* **`jose`:** The industry-standard library for modern JS. Used by the Marketplace to generate Ed25519 keys, sign JWTs, and expose the JWKS endpoint. **Also used by Data Engines** to verify tickets — `createRemoteJWKSet` handles remote fetching, caching, and `kid` selection, and `jwtVerify` validates the signature plus `iss`/`aud`/`exp` in one call, with native OKP/Ed25519 support.
|
||||
* **`openid-client`:** The RFC-compliant library used by the Local App to execute the PKCE Authorization Code flow securely.
|
||||
|
||||
> [!NOTE]
|
||||
> **Amendment (2026-05-22):** The original draft specified `@fastify/jwt` + `get-jwks` for Data Engines. This was found to be incorrect during local integration testing: `get-jwks.getPublicKey()` converts JWKs via `jwk-to-pem`, which **does not support OKP/Ed25519 keys** (throws `Unsupported key type "OKP"`). `@fastify/jwt`'s standalone `verify()` is also incompatible with a remote-JWKS async key resolver. Data Engines now use `jose` — the same library already mandated for the Marketplace — which supports Ed25519 natively.
|
||||
|
||||
### 2. Hardened First-Message Auth
|
||||
Data Engines MUST enforce strict WebSocket handshake rules:
|
||||
1. **Silence until Auth:** The server MUST accept no subscription or data messages before auth succeeds.
|
||||
2. **Timeout:** Auth MUST complete within a short timeout (e.g., 3 seconds of connection).
|
||||
3. **Drop on Failure:** A failed auth immediately closes the socket with a `4003` code.
|
||||
4. **No Re-Auth:** Re-authentication on the same socket is forbidden.
|
||||
5. **Log Redaction:** All server logs MUST redact the JWT payload from capture.
|
||||
|
||||
### 3. API Key Encryption at Rest (Local App)
|
||||
The Local App stores the API Key in PostgreSQL. It MUST NOT be stored in plaintext.
|
||||
* **Algorithm:** AES-256-GCM.
|
||||
* **Key Derivation (KDF):** The encryption key is derived from `AUTH_SECRET` using PBKDF2 (100,000+ iterations) and a unique salt per installation.
|
||||
* **Nonce/Salt Storage:** The 96-bit nonce and the KDF salt are stored alongside the encrypted payload in the DB.
|
||||
* **Versioning:** The DB column must support key versioning (e.g., `v1:base64_nonce:base64_ciphertext`) to allow future `AUTH_SECRET` rotation without permanently bricking the DB.
|
||||
|
||||
---
|
||||
|
||||
## Failure-Mode Behavior
|
||||
|
||||
| Scenario | System Behavior |
|
||||
| :--- | :--- |
|
||||
| **Marketplace is down** | Local App cannot get new JWTs. Existing streams continue until the 5-min JWT expires. |
|
||||
| **Data Engine Cold Start (Marketplace down)** | Engine cannot fetch `jwks.json`. Engine **fails closed** and rejects all connections. |
|
||||
| **JWKS Cache expires (Marketplace down)** | Data Engine retains stale cache for a grace period, but eventually **fails closed**. |
|
||||
| **Redis is down (Marketplace)** | Ticket issuance falls back to PostgreSQL (slower, but functional). |
|
||||
| **Unknown `kid` arrives** | Data Engine immediately triggers a background re-fetch of `jwks.json`. If still unknown, rejects token. |
|
||||
| **Clocks drift beyond leeway** | Token is rejected (Next.js and Fastify default to 60s leeway). NTP sync is a hard operational requirement. |
|
||||
|
||||
---
|
||||
|
||||
## Revocation Latency
|
||||
|
||||
| Event | Time to take effect |
|
||||
| :--- | :--- |
|
||||
| **User cancels subscription** | Up to 5 minutes (bounded strictly by active JWT lifetime). |
|
||||
| **Admin rotates Ed25519 key** | Zero downtime (handled via key overlap in JWKS array). |
|
||||
| **User revokes API Key** | Immediate for *new* issuances, up to 5 minutes for active streams. |
|
||||
|
||||
---
|
||||
|
||||
## The End-to-End Auth Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as User Browser
|
||||
participant L as Local App
|
||||
participant M as Marketplace
|
||||
participant E as Data Engine
|
||||
|
||||
Note over U,M: ADR-001C: PKCE bootstrap (once)
|
||||
U->>L: Click "Connect to Marketplace"
|
||||
L->>L: Generate code_verifier + challenge
|
||||
L->>U: Redirect to Marketplace with challenge
|
||||
U->>M: Authorize
|
||||
M->>U: Redirect with temp code
|
||||
U->>L: Forward temp code
|
||||
L->>M: POST temp code + code_verifier
|
||||
M->>L: API Key (Long-lived)
|
||||
L->>L: PBKDF2 + AES-GCM Encrypt & Store
|
||||
|
||||
Note over L,E: ADR-001B & A: Ongoing Data Plane
|
||||
loop every 4.5 minutes
|
||||
L->>M: POST API Key (Request audience: Engine A)
|
||||
M->>L: 5-min JWT (aud: Engine A)
|
||||
L->>U: JWT
|
||||
U->>E: wss://engine (Origin validation)
|
||||
U->>E: { type: "auth", v: 1, token: "..." }
|
||||
E->>E: Verify JWT via jose (cached JWKS)
|
||||
E->>U: Stream
|
||||
end
|
||||
```
|
||||
@@ -0,0 +1,158 @@
|
||||
# ADR-0002: Source-of-truth for plugin identity and registration
|
||||
|
||||
## Status
|
||||
Accepted
|
||||
|
||||
## Date
|
||||
2026-05-20
|
||||
|
||||
## Context
|
||||
|
||||
Two related problems in the plugin system surfaced in the same period, and both have the same root cause: canonical plugin information was being derived in middleware translation layers (folder names, hard-coded lists) rather than at its proper source. Each problem is fixed by pushing the canonical truth back to its rightful owner and removing the static translation in the middle. Documenting them together makes the shared principle explicit and discourages future regressions of the same shape.
|
||||
|
||||
### Problem 1 — Engine seeder ID derived from folder name
|
||||
|
||||
The WorldWideView local data engine discovers seeders by scanning the filesystem under `/app/seeders`. Historically, the engine assigned each seeder an ID equal to its **folder name** (e.g., the folder `gpsjam/` became plugin ID `"gpsjam"`).
|
||||
|
||||
The frontend, however, identifies plugins by a separate **`id` field** declared in each plugin class (e.g., `"gps-jamming"`). The engine's `/manifest` endpoint listed available plugins using folder-derived IDs, and the frontend's `localEngineHasPlugin(pluginId)` performed an exact string match against that list.
|
||||
|
||||
This created a silent failure mode: six seeders had folder names that did not match their corresponding frontend plugin IDs:
|
||||
|
||||
| Folder name | Frontend plugin `id` |
|
||||
|---|---|
|
||||
| `gpsjam/` | `gps-jamming` |
|
||||
| `sanctions/` | `international-sanctions` |
|
||||
| `wildfires/` | `wildfire` |
|
||||
| `civilUnrest/` | `civil-unrest` |
|
||||
| `conflictEvents/` | `conflict-events` |
|
||||
| `cyberAttacks/` | `cyber-attacks` |
|
||||
|
||||
When `localEngineHasPlugin('gps-jamming')` returned `false` (because the manifest listed `"gpsjam"`), the frontend silently fell through to the production cloud engine, bypassing the local engine entirely. The bug was invisible — no error, just incorrect routing.
|
||||
|
||||
A short-term patch introduced `SEEDER_ID_ALIASES` in `src/core/data/engineManifest.ts` — a frontend translation map from folder names to plugin IDs. This was explicitly a band-aid: it duplicated knowledge in a consumer rather than fixing the contract at the source, and would go stale as new seeders were added.
|
||||
|
||||
The engine's TypeScript source (`seeder-loader.ts`) also had a `toKebabCase()` helper intended to normalize camelCase folder names (e.g., `civilUnrest` → `civil-unrest`), but its compiled `dist/` was stale (the production image had not been rebuilt to include it), and `toKebabCase` alone cannot resolve abbreviation mismatches like `gpsjam` → `gps-jamming`.
|
||||
|
||||
### Problem 2 — Fresh-install plugin set hard-coded
|
||||
|
||||
The marketplace auto-seeder ([src/lib/marketplace/seedDefaultPlugins.ts](../../../src/lib/marketplace/seedDefaultPlugins.ts)) writes a starter set of plugins to the database on first boot so the globe isn't empty on day one. The list of plugins to seed lived in a hard-coded constant `DEFAULT_PLUGIN_IDS` ([src/lib/marketplace/defaultPlugins.ts](../../../src/lib/marketplace/defaultPlugins.ts)).
|
||||
|
||||
Two failure modes followed from the static list:
|
||||
|
||||
1. **Drift**: ten plugins were published to npm under `@worldwideview/*` and verified — surveillance-satellites, military-bases, embassies, seaports, lighthouses, spaceports, iranwarlive, undersea-cables, mineral-mines, nuclear-facilities — but never added to `DEFAULT_PLUGIN_IDS`. Fresh installs missed them silently.
|
||||
2. **Phantom 404s**: two entries in the list (`fortiguard`, `nz-traffic-cameras`) were dev-only sandboxes in `local-plugins/`, never published to npm. Every fresh boot hit `https://marketplace.worldwideview.dev/api/plugins/fortiguard` → 404, logged a warning, and continued. The branch `fix/diagnose-plugins-404` was opened to diagnose those.
|
||||
|
||||
A separate, signed verified-plugins registry already existed at `marketplace.worldwideview.dev/api/registry`, loaded by [registryClient.ts](../../../src/lib/marketplace/registryClient.ts) with Ed25519 verification. It was used for trust-stamping installed plugins but not for selecting which plugins to seed. That registry is the authoritative list of plugins that have been reviewed and verified — exactly the list a starter set should come from.
|
||||
|
||||
### Shared shape
|
||||
|
||||
Both problems wrap the same anti-pattern: a consumer (frontend, seeder) maintains a static translation/list derived from the producer's actual identity (seeder export, npm publication). The translation drifts. The fix in both cases is the same: stop translating in the consumer; let the producer declare the truth and consume it directly.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1 — The seeder's exported `name` field is the canonical plugin ID
|
||||
|
||||
The engine reads each seeder's `dist/index.mjs` default export's `name` property and uses it as the plugin ID everywhere:
|
||||
|
||||
- `/manifest` endpoint `plugins` array
|
||||
- WebSocket welcome message plugin list
|
||||
- WebSocket data message `pluginId` field
|
||||
- Redis key (`data:<name>:live`)
|
||||
- Scheduler logs
|
||||
|
||||
The folder name is used only as a filesystem fallback if the seeder exports no `name`. The engine logs a warning at startup whenever the kebab-cased folder name differs from the seeder's exported `name`, making drift visible without blocking startup.
|
||||
|
||||
**Contract:** Every seeder MUST export a `name` field that exactly equals the corresponding frontend plugin's `id` field (kebab-case). This is a two-place contract: declare the same ID string in the seeder export and in the frontend plugin class.
|
||||
|
||||
Implementation: `seeder-loader.ts` was updated to set `id = seederConfig.name || toKebabCase(folderName)` instead of `id = toKebabCase(folderName)`. The frontend `SEEDER_ID_ALIASES` map was removed entirely. No translation layer exists between the engine's manifest and the frontend's plugin lookup.
|
||||
|
||||
### Decision 2 — The signed verified registry is the source-of-truth for fresh-install auto-seeding
|
||||
|
||||
The marketplace auto-seeder iterates the set returned by `getVerifiedPluginIds()` (the signed registry) instead of a hard-coded `DEFAULT_PLUGIN_IDS` constant. Publishing a plugin to the verified registry automatically makes it part of the fresh-install starter set on subsequent boots, with no code change.
|
||||
|
||||
The static `DEFAULT_PLUGIN_IDS` list is deleted. There is no fallback list in code — if the registry is unreachable on first attempt, the seeder defers without marking-seeded so the next request retries (the 5-min in-memory cache in `registryClient.ts` bounds the request rate during outages).
|
||||
|
||||
Trust stamping is collapsed: every plugin landed by the seeder is `verified` by definition, so the per-plugin `verified.has(pluginId)` check inside the seeder is dropped — `manifest.trust = "verified"` is set directly.
|
||||
|
||||
**Contract:** A plugin is part of the fresh-install starter set iff it appears in the signed verified-plugins registry. There is no other list to maintain.
|
||||
|
||||
## Shared principle
|
||||
|
||||
> **Canonical plugin truth lives at the source. Reject static translation/lookup layers in the middle.**
|
||||
|
||||
This is the architectural rule both decisions encode. Concrete corollaries for future contributions:
|
||||
|
||||
- Don't introduce a static map in a consumer to compensate for a producer that mis-labels itself. Fix the producer.
|
||||
- Don't introduce a static list in code to enumerate what a registry or filesystem already enumerates. Read from the registry/filesystem.
|
||||
- A translation layer that "just needs an entry added each time we publish a plugin" is a foot-gun — it will silently drift the moment someone forgets.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### For Decision 1
|
||||
|
||||
#### Folder renames (rejected as primary fix)
|
||||
Rename the six mismatched folders to match their frontend plugin IDs (e.g., `gpsjam/` → `gps-jamming/`). This would make the folder name the canonical ID.
|
||||
|
||||
- **Rejected as primary fix** because Windows Docker Desktop holds NTFS volume mount locks on running containers, making renames impossible without a full Docker Desktop shutdown. More importantly, it makes the canonical ID fragile — any accidental folder rename breaks routing silently.
|
||||
- Folder renames remain a cosmetic cleanup option, now that the seeder export is the actual source of truth.
|
||||
|
||||
#### Frontend alias map (`SEEDER_ID_ALIASES`)
|
||||
Maintain a static mapping in `engineManifest.ts` that translates engine-reported IDs to frontend plugin IDs.
|
||||
|
||||
- **Rejected** because it puts translation responsibility on the consumer rather than the producer. Every new seeder with a naming mismatch requires a manual alias entry. The map goes stale silently — no warning if an alias is wrong or missing.
|
||||
|
||||
#### `toKebabCase()` normalization only
|
||||
Apply `toKebabCase()` to folder names in the engine and rely on the convention that folder names encode the plugin ID in camelCase.
|
||||
|
||||
- **Rejected** because `toKebabCase` cannot resolve abbreviation mismatches (`gpsjam` → still `gpsjam`, not `gps-jamming`) or singular/plural differences (`wildfires` → still `wildfires`, not `wildfire`). It only handles camelCase-to-kebab conversion.
|
||||
|
||||
#### Strict validation with engine startup failure
|
||||
Refuse to load any seeder whose folder name doesn't match its exported `name`, blocking startup until inconsistencies are resolved.
|
||||
|
||||
- **Rejected** as too aggressive for a local dev environment. A warning is sufficient — startup continues, mismatches are visible, and the system keeps working.
|
||||
|
||||
### For Decision 2
|
||||
|
||||
#### Add the missing 10 IDs to `DEFAULT_PLUGIN_IDS` (rejected)
|
||||
Extend the static list to include the newly-published plugins.
|
||||
|
||||
- **Rejected** because it ships a fix that resolves the immediate symptom while preserving the underlying drift mechanism. The list would go stale again the next time a plugin is published.
|
||||
|
||||
#### Hybrid: registry as default + static fallback list
|
||||
Read from the registry; fall back to a hard-coded list if the registry is empty/unreachable.
|
||||
|
||||
- **Rejected** because it reintroduces the static list as a permanent shadow source-of-truth. Fallback lists go stale silently. The chosen "defer seeding on empty registry" behavior is safer — fresh installs retry on the next request rather than locking in a stale set.
|
||||
|
||||
#### Delete auto-seeding entirely (rejected)
|
||||
Drop the seeder and let users install everything from the marketplace UI starting from an empty globe.
|
||||
|
||||
- **Rejected** because fresh installs should have something to look at on day one. The user explicitly stated this requirement: "we want the user to have something to get started with."
|
||||
|
||||
## Consequences
|
||||
|
||||
### Easier
|
||||
|
||||
**Decision 1 — engine seeder identity**
|
||||
- Self-documenting identity. Reading any seeder's `src/index.ts` immediately tells you its plugin ID. No external registry to consult.
|
||||
- Filesystem layout is irrelevant. Folders can be named for readability or organized in subdirectories without affecting routing.
|
||||
- No translation layers. The frontend receives the correct ID directly from the manifest; `localEngineHasPlugin()` works with a direct string comparison.
|
||||
- Drift is visible. The engine warns on startup when folder names diverge from exported names, catching mistakes during development rather than silently at runtime.
|
||||
- Adding a new seeder requires only: (1) export `name: '<plugin-id>'` matching the frontend plugin's `id`, (2) no registration step, no alias map entry.
|
||||
|
||||
**Decision 2 — marketplace seeding**
|
||||
- Publishing a plugin to the verified registry is sufficient to add it to the starter set. No code change, no PR to add an ID to a constant.
|
||||
- Phantom 404s are gone. The seeder only queries IDs that exist in the verified registry, which by construction reflects what's actually published.
|
||||
- Trust semantics align. "Verified" and "auto-seeded on fresh install" are now the same condition, not two near-overlapping lists that can drift.
|
||||
- Registry outages no longer brick fresh installs. The deferral semantics ensure the seeder retries instead of marking-seeded with zero rows.
|
||||
|
||||
### Harder
|
||||
|
||||
**Decision 1 — engine seeder identity**
|
||||
- Seeder author bears responsibility. If a seeder exports the wrong `name`, routing fails silently (same failure mode as before, but now localized to the seeder rather than the folder). The startup warning mitigates this.
|
||||
- Contract validation is advisory, not enforced. There is no build-time check that the seeder's `name` matches an actual frontend plugin `id`. A validation script (`scripts/validate-seeder-ids.mjs`) is the recommended mitigation.
|
||||
- Engine image must be kept up to date. The fix lives in `dist/seeder-loader.js` inside the Docker image. If the published `ghcr.io/silvertakana/wwv-data-engine:latest` image is behind the local source, the behavior reverts to folder-name-based IDs. Local changes require `docker cp` injection or an image rebuild until the fix is published.
|
||||
|
||||
**Decision 2 — marketplace seeding**
|
||||
- The verified registry must be kept accurate. A newly-published plugin doesn't auto-seed until it's added to the registry and the registry is re-signed. Operational responsibility shifts from "remember to add the ID to a code constant" to "remember to add the ID to the registry" — a similar discipline, but now at the right layer (the marketplace, not the consumer).
|
||||
- Existing instances are not back-filled. Users whose `Setting` table already has `defaults_seeded=true` will not automatically receive newly-verified plugins; they must install via the marketplace UI. This is by design — re-seeding could reinstall plugins a user explicitly uninstalled.
|
||||
- Dev-only sandboxes (`local-plugins/<name>/`) no longer "tag along" via the default list. `fortiguard` and `nz-traffic-cameras` only reach users once published to npm and added to the verified registry. The local-plugins folder discovery in `/api/marketplace/load` still surfaces them in dev (`NODE_ENV=development` or `WWV_PLUGIN_DEV=true`).
|
||||
@@ -0,0 +1,175 @@
|
||||
# ADR-0003: Shared Identity & Ecosystem Authentication Host
|
||||
|
||||
## Status
|
||||
Proposed *(Pending Review)*
|
||||
|
||||
## Date
|
||||
2026-05-22
|
||||
|
||||
## Related
|
||||
- **Builds on:** ADR-001 (Decentralized Plugin Auth & SSRF Mitigation) — specifically the PKCE flow that lets the Local App acquire tokens from the Marketplace
|
||||
- **Supersedes:** `.agents/rules/cloud-auth-architecture.md` (which incorrectly states that `app.worldwideview.dev` owns all login UI — this ADR reverses that)
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
WorldWideView is growing into a multi-product ecosystem:
|
||||
|
||||
| Product | URL | Purpose |
|
||||
|---|---|---|
|
||||
| Landing / Auth | `worldwideview.dev` | Marketing, login, signup, cloud plan registration |
|
||||
| Marketplace | `marketplace.worldwideview.dev` | Browse, install, and manage plugins |
|
||||
| Cloud App | `app.worldwideview.dev` (or `[tenant].app.worldwideview.dev`) | Hosted geospatial intelligence instance |
|
||||
| Local App | Self-hosted | User's own instance, authenticated locally |
|
||||
|
||||
Four interrelated problems required a unified decision:
|
||||
|
||||
1. **No Marketplace identity system exists.** Users have nowhere to create an account, log in, or manage subscriptions.
|
||||
2. **Fragmented account experience.** Without a plan, a user would need separate accounts for the Marketplace and the Cloud App — unacceptable for a single-vendor ecosystem.
|
||||
3. **Cookie domain fragmentation.** If each product hosts its own login page, sessions cannot be shared across subdomains. A user logged into the Marketplace would need to log in again at the Cloud App.
|
||||
4. **The `worldwideview-web` repo is a static export** (`output: "export"`). It has a `/login` page backed by client-side Supabase but cannot support server-side sessions, API routes, or cross-subdomain cookie management.
|
||||
|
||||
---
|
||||
|
||||
## Decisions
|
||||
|
||||
### ADR-003A: Federated Identity — One Account Across All Products
|
||||
|
||||
All WorldWideView products share a **single identity**. A user who creates an account anywhere in the ecosystem (Marketplace, Cloud App, or the landing site) has that same identity available everywhere else.
|
||||
|
||||
This is the standard industry pattern for multi-product SaaS — used by GitHub (one account → GitHub, Marketplace, Actions, Packages), Atlassian (one account → Jira, Confluence, Marketplace), and Stripe (one account → Dashboard, Atlas, Stripe Apps).
|
||||
|
||||
The shared identity store is a **single Supabase project**. All products point to the same `NEXT_PUBLIC_SUPABASE_URL` and read from the same `auth.users` table. No synchronisation jobs, no duplicate user records.
|
||||
|
||||
### ADR-003B: Supabase Auth as the Identity Provider
|
||||
|
||||
**Supabase Auth** is the identity layer for the entire ecosystem. It was chosen over:
|
||||
|
||||
- **Better Auth** — excellent self-hosted option, but requires a Postgres database to be provisioned separately. Since the Marketplace and `worldwideview-web` have no existing database, Supabase provides auth + Postgres in a single managed service with zero extra infrastructure.
|
||||
- **NextAuth v5** — already present in the Local App for local access control, but it is not a full identity platform. Missing 2FA, RBAC, and a proper OAuth server model. Not suitable as an ecosystem-wide IdP.
|
||||
- **Clerk** — fastest setup and best Stripe integration, but ~$25–50/month at low user counts, per-MAU pricing at scale, and user data is stored on Clerk's servers. Vendor lock-in is unacceptable for a product that holds plugin and subscription data.
|
||||
|
||||
Supabase Auth provides:
|
||||
- Email + password, Google OAuth, GitHub OAuth, and magic link — all configured in the Supabase dashboard with no provider code
|
||||
- `@supabase/ssr` package with first-class Next.js App Router support (server components, middleware, server actions)
|
||||
- Cookie-based sessions that can be scoped to the parent domain
|
||||
- Free tier is sufficient for early-stage Marketplace; Pro plan ($25/month) unlocks unlimited MAU
|
||||
|
||||
### ADR-003C: `worldwideview.dev` (worldwideview-web repo) is the Ecosystem Auth Host
|
||||
|
||||
The login and account registration UI lives at **`worldwideview.dev`** — the apex domain, served by the `worldwideview-web` repository. Three alternatives were considered:
|
||||
|
||||
**Option A — Each app has its own login page**
|
||||
Rejected. Each product renders its own login form against the shared Supabase project. Browser `localStorage` (used by client-side Supabase) is domain-scoped and cannot be shared across subdomains. This means a user logged in at `marketplace.worldwideview.dev` would not be recognised at `app.worldwideview.dev`. Solving this in each app separately creates duplicated middleware and fragile cookie coordination.
|
||||
|
||||
**Option B — Marketplace owns the login page**
|
||||
Rejected. The Cloud App would be permanently subordinate to the Marketplace for authentication. If the Marketplace is down, Cloud App users cannot log in. Also creates a confusing UX: users navigate to `app.worldwideview.dev` and are immediately bounced to `marketplace.worldwideview.dev` just to authenticate.
|
||||
|
||||
**Option C — Dedicated `accounts.worldwideview.dev` subdomain**
|
||||
Seriously considered. A neutral auth subdomain is the cleanest long-term architecture. Rejected for now because it requires a third Next.js deployment and a third Coolify application. The same result is achieved by hosting auth on the apex domain itself (`worldwideview.dev`), which is already managed by `worldwideview-web` and is the identity host by virtue of owning the root domain.
|
||||
|
||||
**Chosen: Apex domain as auth host.** The `worldwideview-web` repo becomes the auth surface for the whole ecosystem:
|
||||
|
||||
| Path | Type | Purpose |
|
||||
|---|---|---|
|
||||
| `/` | Static | Landing page (marketing) |
|
||||
| `/about`, `/docs`, `/plugins` | Static | Marketing content |
|
||||
| `/login` | Dynamic (SSR) | Shared login for all products |
|
||||
| `/signup` | Dynamic (SSR) | New account creation |
|
||||
| `/cloud` | Dynamic (SSR) | Cloud plan registration and subscription |
|
||||
| `/accounts/*` | Dynamic (SSR) | Account management, billing, API keys |
|
||||
| `/api/auth/callback` | Dynamic (SSR) | OAuth redirect handler (Google, GitHub) |
|
||||
|
||||
**Why the apex domain is correct:** A session cookie set on `worldwideview.dev` is automatically inherited by all subdomains (`marketplace.worldwideview.dev`, `app.worldwideview.dev`, and any future product). This is the same mechanism used by Stripe — `stripe.com/login` sets the session that `dashboard.stripe.com` reads.
|
||||
|
||||
### ADR-003D: Cross-Subdomain Session Sharing via Parent Domain Cookie
|
||||
|
||||
Supabase Auth session cookies are explicitly scoped to the parent domain so that all products share the same session without additional coordination:
|
||||
|
||||
```typescript
|
||||
// Applied in worldwideview-web middleware and all Supabase server clients
|
||||
cookieOptions: {
|
||||
domain: '.worldwideview.dev', // leading dot = all subdomains inherit
|
||||
path: '/',
|
||||
sameSite: 'lax',
|
||||
secure: true, // HTTPS required — see local dev below
|
||||
}
|
||||
```
|
||||
|
||||
Each product (Marketplace, Cloud App) reads this cookie to get the authenticated user, then calls `supabase.auth.getUser()` server-side to validate the session. No cross-app API calls for authentication.
|
||||
|
||||
**Logout** must clear the cookie on the parent domain, not the subdomain, or the session will persist across products.
|
||||
|
||||
### ADR-003E: `worldwideview-web` Converts from Static Export to Mixed Static/SSR
|
||||
|
||||
The current `worldwideview-web` uses `output: "export"` in `next.config.ts`, forcing every page to be a static HTML file served by Nginx. This is removed.
|
||||
|
||||
Without `output: "export"`, Next.js App Router applies per-route rendering:
|
||||
- Pages that do not call `cookies()`, `headers()`, or other dynamic functions are **statically generated at build time** — marketing pages remain fast and CDN-cached with no change required.
|
||||
- Pages that call `cookies()` (all auth pages using `@supabase/ssr`) are **server-rendered on request**.
|
||||
|
||||
The Docker deployment changes from an Nginx static image to a Node.js runtime image. The Coolify application is updated in-place — no new Coolify application is needed.
|
||||
|
||||
### ADR-003F: `wwv.local` Local Development Environment
|
||||
|
||||
Because the parent-domain cookie requires `secure: true` (HTTPS only), local development using `localhost` will not replicate production session-sharing behaviour. A local HTTPS domain is required.
|
||||
|
||||
The project adopts `wwv.local` as the local development TLD with a self-signed certificate:
|
||||
|
||||
| Local URL | Maps to | Purpose |
|
||||
|---|---|---|
|
||||
| `wwv.local` | worldwideview-web on port 3001 | Landing + auth |
|
||||
| `marketplace.wwv.local` | worldwideview-marketplace on port 3002 | Marketplace |
|
||||
| `app.wwv.local` | worldwideview main app on port 3000 | Local App / Cloud App |
|
||||
|
||||
This setup is a deliberate investment: it ensures that cross-subdomain auth, redirect flows, and cookie behaviour can be tested locally before production deployment. The setup cost is a one-time `mkcert` install and hosts file edit per developer machine.
|
||||
|
||||
Setup (documented in each repo's README):
|
||||
```bash
|
||||
# Install mkcert (once per machine)
|
||||
# macOS: brew install mkcert && mkcert -install
|
||||
# Windows: choco install mkcert && mkcert -install
|
||||
|
||||
mkcert "*.wwv.local" wwv.local
|
||||
# Add to hosts: 127.0.0.1 wwv.local marketplace.wwv.local app.wwv.local
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Constraints (from Pre-Mortem Review)
|
||||
|
||||
The following risks were identified and mitigated before implementation:
|
||||
|
||||
| Risk | Mitigation |
|
||||
|---|---|
|
||||
| Supabase anon key can read all rows if RLS is disabled | Row Level Security (RLS) MUST be enabled on all app-specific tables (`MarketplaceUser`, `InstalledPlugin`). Policy: `using (id = auth.uid())`. Server routes use `SUPABASE_SERVICE_ROLE_KEY` which bypasses RLS by design. |
|
||||
| PKCE authorization code replay attack | The authorization code is deleted from the database transactionally at the moment of redemption. Any subsequent attempt receives `400 invalid_grant`. |
|
||||
| Supabase free tier limits magic link email to 2/hour per address | A custom SMTP provider (Resend) is configured in Supabase project settings before magic link is enabled in production. |
|
||||
| `MarketplaceUser` becomes orphaned when `auth.users` row is deleted | A Postgres trigger on `auth.users` DELETE cascades to `MarketplaceUser` and all related rows. |
|
||||
| Ed25519 signing key rotation causes token rejection at Data Engines | Signing keys are stored in a `SigningKey` DB table, not env vars. The JWKS endpoint serves all non-revoked keys simultaneously. During rotation, the old key is marked `retiring` and kept in JWKS for 10 minutes before being marked `revoked`. |
|
||||
|
||||
---
|
||||
|
||||
## Marketplace PKCE OAuth Server (Relation to ADR-001)
|
||||
|
||||
The Marketplace acts as the **OAuth 2.0 Authorization Server** in the ADR-001 PKCE flow. Supabase Auth handles user identity; a thin custom layer handles the code exchange:
|
||||
|
||||
1. Local App redirects user to `marketplace.worldwideview.dev/api/oauth/authorize`
|
||||
2. Marketplace validates the Supabase session (or redirects to `worldwideview.dev/login`)
|
||||
3. User sees consent screen and approves
|
||||
4. Marketplace issues a short-lived authorization code (60s TTL), redirects to Local App
|
||||
5. Local App exchanges code + `code_verifier` for a long-lived API Key
|
||||
6. Subsequent plugin connections use the API Key to request 5-minute EdDSA JWTs (ADR-001B)
|
||||
|
||||
This is not a new Supabase feature — it is custom Next.js API routes sitting on top of the existing Supabase Auth session.
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
- **One Supabase project** is a shared dependency across `worldwideview-web`, `worldwideview-marketplace`, and `worldwideview` (Cloud App). A Supabase outage affects all products simultaneously. This is an accepted tradeoff at current scale; the mitigation is Supabase's SLA and free-tier generous limits.
|
||||
- **`worldwideview-web` must run as a Node.js server**, not a static Nginx container. This increases Coolify resource usage marginally but enables all auth functionality.
|
||||
- **Local development requires `mkcert` setup** (one-time, ~5 minutes). This is a deliberate decision to prevent a class of production bugs that cannot be caught with `localhost`.
|
||||
- **The old `cloud-auth-architecture.md` rule is invalidated.** That rule stated `app.worldwideview.dev` owns all login UI and the Marketplace redirects there. The reverse is now true. That rules file must be updated to reference this ADR.
|
||||
- **Upgrade path is clear:** If the Marketplace matures into a platform that third-party developers build against (issuing OAuth tokens to external apps), the existing PKCE layer is extended without changing the user table or Supabase project. The identity layer is already decoupled from the token exchange layer.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 816 KiB |
@@ -0,0 +1,32 @@
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Build System
|
||||
|
||||
## 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 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
|
||||
|
||||
### 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-v2` + Redis containers via Docker Compose).
|
||||
|
||||
### 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
|
||||
|
||||
- **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.
|
||||
- **Data Engine:** The generic data engine runner and Redis cache are started via `docker compose up wwv-data-engine-v2 wwv-redis`. Custom data seeders are placed in the `local-seeders/community/` or `local-seeders/private/` sandboxes and dynamically loaded by the engine.
|
||||
- **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,378 +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
|
||||
- npm account (for publishing)
|
||||
- The WorldWideView monorepo cloned locally
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Create Your Plugin Package
|
||||
|
||||
All plugins live under `packages/` in the monorepo.
|
||||
|
||||
```bash
|
||||
mkdir packages/wwv-plugin-my-data
|
||||
cd packages/wwv-plugin-my-data
|
||||
```
|
||||
|
||||
Create `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@worldwideview/wwv-plugin-my-data",
|
||||
"version": "1.0.0",
|
||||
"description": "WorldWideView plugin — my custom data layer",
|
||||
"main": "src/index.ts",
|
||||
"types": "src/index.ts",
|
||||
"files": ["src"],
|
||||
"keywords": [
|
||||
"worldwideview",
|
||||
"worldwideview-plugin",
|
||||
"geojson",
|
||||
"cesium",
|
||||
"globe"
|
||||
],
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/silvertakana/worldwideview.git",
|
||||
"directory": "packages/wwv-plugin-my-data"
|
||||
},
|
||||
"license": "ISC",
|
||||
"author": "WorldWideView",
|
||||
"peerDependencies": {
|
||||
"@worldwideview/wwv-plugin-sdk": "*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> [!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
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> The marketplace pulls metadata (version, description, keywords) directly from the npm registry at runtime. You do not need to duplicate this metadata in the marketplace.
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Register in the Marketplace
|
||||
|
||||
### 4a. Add to `knownPlugins.ts`
|
||||
|
||||
Open `worldwideview-marketplace/src/data/knownPlugins.ts` and add your plugin:
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: "my-data",
|
||||
npmPackage: "@worldwideview/wwv-plugin-my-data",
|
||||
icon: "MapPin", // Lucide icon name
|
||||
category: "Custom", // Must match a value in CATEGORIES
|
||||
format: "static", // "static" | "bundle"
|
||||
trust: "verified", // "built-in" | "verified" | "unverified"
|
||||
capabilities: ["data:own"],
|
||||
longDescription:
|
||||
"Description shown on the plugin detail page in the marketplace.",
|
||||
changelog:
|
||||
"v1.0.0 — Initial release.",
|
||||
},
|
||||
```
|
||||
|
||||
### 4b. Add a manifest (static plugins only)
|
||||
|
||||
For **static** format plugins, open `worldwideview-marketplace/src/data/pluginManifests.ts` and add:
|
||||
|
||||
```typescript
|
||||
"my-data": {
|
||||
id: "my-data",
|
||||
name: "My Data Layer",
|
||||
version: "1.0.0",
|
||||
description: "My custom data layer",
|
||||
type: "data-layer",
|
||||
format: "static",
|
||||
trust: "verified",
|
||||
capabilities: ["data:own"],
|
||||
category: "Custom",
|
||||
icon: "MapPin",
|
||||
dataFile: "/data/my_data.geojson", // Path to GeoJSON in public/
|
||||
rendering: {
|
||||
entityType: "point",
|
||||
color: "#3b82f6",
|
||||
labelField: "name",
|
||||
clusterEnabled: true,
|
||||
clusterDistance: 50,
|
||||
maxEntities: 5000,
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
Bundle plugins do **not** need a manifest entry here — their code is loaded via dynamic import.
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Test Locally
|
||||
|
||||
1. Start the WorldWideView app: `npm run dev` (in the `worldwideview` directory)
|
||||
2. Start the marketplace: `npm run dev` (in the `worldwideview-marketplace` directory)
|
||||
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
|
||||
│ │
|
||||
▼ │
|
||||
Add to knownPlugins.ts ──► Marketplace ◄────────────┘
|
||||
(+ pluginManifests.ts shows plugin (fetches version,
|
||||
for static plugins) in browse grid description, etc.)
|
||||
│
|
||||
▼
|
||||
User clicks "Install"
|
||||
│
|
||||
▼
|
||||
Marketplace sends manifest
|
||||
to WorldWideView instance
|
||||
│
|
||||
▼
|
||||
InstalledPluginsLoader saves
|
||||
manifest to database (Prisma)
|
||||
│
|
||||
▼
|
||||
loadPluginFromManifest() routes
|
||||
by format: static → StaticDataPlugin
|
||||
bundle → dynamic import
|
||||
│
|
||||
▼
|
||||
Plugin renders on the 3D globe
|
||||
```
|
||||
@@ -0,0 +1,66 @@
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Deployment
|
||||
|
||||
## 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
|
||||
|
||||
### Main Application
|
||||
- **Build Output:** Located at `.next/standalone/`.
|
||||
- **Static Assets:** Cesium static workers are injected at build time via `scripts/copy-cesium.mjs`.
|
||||
|
||||
### Data Engine Runner
|
||||
- The generic `wwv-data-engine-v2` runner is deployed as a single Coolify service, orchestrating telemetry data by executing lightweight scripts from volume-mounted seeder directories. It features a dual-output architecture, exposing both WebSocket streams and REST APIs natively.
|
||||
|
||||
## Platform Deployment
|
||||
|
||||
### 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.
|
||||
- **Seeder Deployment:** The generic `wwv-data-engine-v2` runner is deployed as a Coolify service, reading plugin seeders dynamically from a volume-mounted directory. Seeders are pulled from private/community repositories via GitHub releases, maintaining strict namespace separation between community and private plugins.
|
||||
|
||||
### 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
|
||||
- **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)
|
||||
@@ -0,0 +1,167 @@
|
||||
# ADR-001 Pre-flight Audit — 2026-05-21
|
||||
|
||||
**Auditor:** Claude (ADR-001 Local App workstream) **Branch:** `feat/adr-001-local-app`
|
||||
**Status:** Complete — see gate summary in §6
|
||||
|
||||
This document records the six step-0 checklist items from the master deploy plan
|
||||
(`i-want-you-to-delightful-candle.md`, §"Deploy Order") before any ADR-001 code
|
||||
lands on production.
|
||||
|
||||
---
|
||||
|
||||
## 1. Coolify Env-Var Audit
|
||||
|
||||
Swept every `JWT_*`, `TICKET_*`, `JWKS_*`, and `AUTH_*` variable across the three
|
||||
live services. Values are masked; only presence is recorded.
|
||||
|
||||
### Debris check
|
||||
|
||||
| Service | Coolify resource | `JWT_*` | `TICKET_*` | `JWKS_*` | `AUTH_SECRET` | Decision |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Local App | `worldwideview-demo` | — | — | — | ✓ set | nothing to remove |
|
||||
| Data Engine | `wwv-engine-stack` | — | — | — | — | nothing to remove |
|
||||
| Marketplace | `worldwideview-marketplace` | — | — | — | — | nothing to remove |
|
||||
|
||||
**Result: No debris from the previous failed deploy.** All three services are clean.
|
||||
No removals required.
|
||||
|
||||
### ADR-001 vars — gaps to fill in deploy steps 1–2
|
||||
|
||||
| Service | Missing var | Required by | When to set | Notes |
|
||||
|---|---|---|---|---|
|
||||
| `worldwideview-demo` | `ENCRYPTION_MASTER_KEY` | **C1 hard gate** | **Step 1 — first action** | Without it the app boots but step-1 code will refuse to start |
|
||||
| `worldwideview-demo` | `MARKETPLACE_URL` | C3 ticketClient | Step 1 | Server-side token exchange endpoint |
|
||||
| `worldwideview-demo` | `NEXT_PUBLIC_WWV_MARKETPLACE_URL` | C3/C5 client | Step 1 | Client-side Marketplace link |
|
||||
| `worldwideview-demo` | `PROXY_HOST_ALLOWLIST` | C2 SSRF | Step 1 | Set to `"*"` (observation mode); tighten in step 7c |
|
||||
| `worldwideview-demo` | `NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS` | C5 flag | Step 6 | Leave empty (dormant) until step 6 cutover |
|
||||
| `worldwideview-marketplace` | `DATABASE_URL`, `AUTH_SECRET` | A basics | Step 2 | Marketplace cannot function without these |
|
||||
| `worldwideview-marketplace` | EdDSA signing key + JWKS endpoint | A1–A2 | Step 2 | Required for `/api/auth/exchange` to sign tickets |
|
||||
| `wwv-engine-stack` | JWKS / JWT public-key config | B JWKS wiring | Step 4 | See §5 — not blocking until cutover |
|
||||
|
||||
---
|
||||
|
||||
## 2. Data Engine `main` Branch State
|
||||
|
||||
**Repo:** `silvertakana/wwv-data-engine`
|
||||
**Branch audited:** `main` (HEAD matches `feat/adr-001-data-engine`)
|
||||
|
||||
The `main` branch is **not** in a rolled-back clean state. The decentralised auth
|
||||
work from the prior attempt was **retained and fully merged** (PR #5
|
||||
`feature/decentralised-plugin-auth-data-engine`, PR #6 `chore/standardise-ci`), with
|
||||
four additional fix commits on top.
|
||||
|
||||
**Auth code present in `main`:**
|
||||
|
||||
- Dependencies: `@fastify/jwt ^10`, `get-jwks ^11`, `jose ^6`
|
||||
- `websocket.ts` verifies EdDSA JWTs:
|
||||
```
|
||||
allowedIss: 'https://marketplace.worldwideview.dev'
|
||||
algorithms: ['EdDSA']
|
||||
clockTolerance: 60
|
||||
expectedAud: process.env.ENGINE_ID || 'wwv-data-engine'
|
||||
```
|
||||
|
||||
**Env-gated bypass (commit `e3e2940`):**
|
||||
`WWV_SKIP_WS_AUTH=true` is set on `wwv-engine-stack`. When true, every WS connection
|
||||
is pre-authenticated with no JWT required. **This bypass is currently load-bearing:**
|
||||
the JWKS endpoint is not yet wired (`websocket.ts:23` comment confirms), so the
|
||||
engine cannot verify real tokens. `WWV_SKIP_WS_AUTH=true` must stay until Workstream
|
||||
B wires JWKS (deploy step 4).
|
||||
|
||||
**Uncommitted working-tree WIP (not blocking steps 1–3):**
|
||||
`src/server.ts`, `src/websocket.ts`, `src/websocket.spec.ts` modified; untracked
|
||||
`HANDOFF.md`, `src/startup-checks.ts`, `vitest.config.ts`. The Data Engine
|
||||
workstream has unfinished work not yet committed. Must be resolved before step 4.
|
||||
|
||||
---
|
||||
|
||||
## 3. Dormant Routes / Flags Already in Production
|
||||
|
||||
| Flag / Route | Service | Current value | Introduced | Notes |
|
||||
|---|---|---|---|---|
|
||||
| `WWV_SKIP_WS_AUTH` | `wwv-engine-stack` | `true` (load-bearing) | 2026-05-20 | Engine bypass — must stay `true` until JWKS wired (step 4) |
|
||||
|
||||
No other ADR-001 feature flags are active in production. The old no-auth data path
|
||||
is still the only path through the Data Engine.
|
||||
|
||||
---
|
||||
|
||||
## 4. `ENCRYPTION_MASTER_KEY` Gate (C1)
|
||||
|
||||
**Status: FAIL — not set on `worldwideview-demo`**
|
||||
|
||||
The `ENCRYPTION_MASTER_KEY` env var is absent from the live Local App. Once
|
||||
`src/instrumentation.ts` boot validation ships (deploy step 1), the app will
|
||||
**refuse to start** if this var is missing.
|
||||
|
||||
**Action required before deploy step 1:**
|
||||
Generate a 32-character key (`openssl rand -hex 16`) and set `ENCRYPTION_MASTER_KEY`
|
||||
on `worldwideview-demo` in Coolify. This is the **first action of deploy step 1** and
|
||||
blocks all subsequent steps.
|
||||
|
||||
---
|
||||
|
||||
## 5. SDK Delivery Decision (Gate for Workstream B)
|
||||
|
||||
**Status: OPEN — operator to confirm**
|
||||
|
||||
No evidence of a published `@worldwideview/wwv-plugin-sdk` package in the deployed
|
||||
services. The `auth-contracts.ts` types (`TokenExchangeRequest`,
|
||||
`TokenExchangeResponse`, `PluginTicket`, `MarketplaceSessionToken`) currently live in
|
||||
the Local App's bundled SDK package.
|
||||
|
||||
Workstream B JWKS wiring requires a decision on how the engine receives the
|
||||
Marketplace public key:
|
||||
- **Option A:** Ed25519 public key as a Coolify env var (simplest)
|
||||
- **Option B:** Remote JWKS URL env var — engine fetches key from
|
||||
`https://marketplace.worldwideview.dev/.well-known/jwks.json` at startup
|
||||
|
||||
**Cross-repo issuer alignment note:** The engine hard-codes
|
||||
`allowedIss: 'https://marketplace.worldwideview.dev'`. The Local App's `MARKETPLACE_URL`
|
||||
config defaults to `https://app.worldwideview.dev`. Confirm that the live Marketplace
|
||||
issues JWTs with `iss: https://marketplace.worldwideview.dev` before step 5 smoke test.
|
||||
|
||||
This decision must be made and documented before deploy step 4.
|
||||
|
||||
---
|
||||
|
||||
## 6. Gate Summary
|
||||
|
||||
| Gate | Status | Blocks deploy step | Action |
|
||||
|---|---|---|---|
|
||||
| No legacy JWT/TICKET debris | ✅ PASS | — | None |
|
||||
| `ENCRYPTION_MASTER_KEY` set on Local App | ❌ FAIL | **Step 1** | Set as first action of step 1 |
|
||||
| Marketplace configured (DB, auth, signing key) | ❌ FAIL | **Step 2** | Configure `worldwideview-marketplace` in Coolify |
|
||||
| SDK delivery decision confirmed | ⚠️ OPEN | Step 4 | Operator decision needed |
|
||||
| Data Engine JWKS wired | ❌ FAIL | Step 4 / cutover | `WWV_SKIP_WS_AUTH` bypass active until then |
|
||||
| Data Engine WIP committed | ⚠️ OPEN | Step 4 | Not blocking steps 1–3 |
|
||||
| Issuer alignment confirmed | ⚠️ OPEN | Step 5 smoke test | Verify `iss` claim matches engine `allowedIss` |
|
||||
|
||||
**Top pre-cutover risks:**
|
||||
|
||||
1. **JWKS not wired on the engine** — `WWV_SKIP_WS_AUTH=true` is the only thing
|
||||
keeping streams alive. If this flag is ever accidentally unset, all WebSocket
|
||||
streams break immediately.
|
||||
2. **Marketplace under-configured** — token exchange will error until step 2 env vars
|
||||
are set. `worldwideview-marketplace` currently has only infra vars (NIXPACKS,
|
||||
REDIS, REGISTRY_PRIVATE_KEY).
|
||||
3. **`ENCRYPTION_MASTER_KEY` missing** — deploy step 1 will trigger a boot refusal
|
||||
if not set first. This is the riskiest item in the pre-cutover phase per the
|
||||
master plan.
|
||||
|
||||
---
|
||||
|
||||
## 7. Cleanup Log
|
||||
|
||||
**Removed this step (2026-05-21):**
|
||||
|
||||
| Resource | Type | UUID | Reason |
|
||||
|---|---|---|---|
|
||||
| `wwv-app-stack` | Coolify service | `h3gtnyotl6b7007hudlfqyf9` | Operator-confirmed deprecated |
|
||||
|
||||
**Remaining cleanup decisions (operator to confirm before step 4):**
|
||||
|
||||
| Resource | Type | UUID | Notes |
|
||||
|---|---|---|---|
|
||||
| `worldwideview web` | Application | `cisr3bruyyvvoeym41dexxa3` | Repo `silvertakana/worldwideview-web`; only REDIS+AISSTREAM vars — appears stale. Verify before removing. |
|
||||
| `wwv-data-engine-legacy` | Application | `sj8519kr561va8ktcdq166hn` | Repo `wwv-data-engine-internal`, branch `master`; appears superseded by `wwv-engine-stack`. Verify before removing. |
|
||||
@@ -0,0 +1,77 @@
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Development
|
||||
|
||||
## 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
|
||||
|
||||
### 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`.
|
||||
- **Color Theming & Design Tokens:** Defined in `src/styles/theme-tokens.css` via CSS variables (e.g., `[data-theme='black']`).
|
||||
|
||||
### 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
|
||||
|
||||
### Entity Rendering
|
||||
When translating raw plugin data into `CesiumEntityOptions` inside `renderEntity()`, follow these strict graphical rules:
|
||||
```typescript
|
||||
// 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);
|
||||
```
|
||||
|
||||
## Workflows
|
||||
|
||||
### 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.
|
||||
|
||||
### Local Plugin & Seeder Testing
|
||||
When developing a custom seeder for a plugin, place the seeder directory inside `local-seeders/community/` or `local-seeders/private/`. The local `wwv-data-engine-v2` Docker container automatically mounts this folder and discovers scripts on startup, providing a seamless sandbox.
|
||||
|
||||
### 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
|
||||
- **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`).
|
||||
@@ -0,0 +1,79 @@
|
||||
# ADR-001 Feature Flags
|
||||
|
||||
Single source of truth for all feature flags introduced by
|
||||
[ADR-0001](architecture/decisions/adr-0001-decentralized-plugin-auth-and-ssrf-mitigation.md)
|
||||
(Decentralized Plugin Auth + SSRF Mitigation).
|
||||
|
||||
**Keep the per-environment table current** whenever a flag is set, changed, or
|
||||
removed in Coolify. Drift between staging and production is the primary paper-cut
|
||||
this doc exists to prevent.
|
||||
|
||||
---
|
||||
|
||||
## Flag Inventory
|
||||
|
||||
### 5 Master-Plan Flags
|
||||
|
||||
| Flag | Repo | Default | Meaning |
|
||||
|---|---|---|---|
|
||||
| `NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS` | **Local App** | `""` (empty = dormant) | Comma-separated plugin IDs that require WS first-message auth (e.g. `aviation,maritime`). Empty or unset → ticket auth disabled for all plugins. Set *after* Marketplace + Data Engine are deployed (step 6). |
|
||||
| `REQUIRE_TICKET_AUTH` | **Data Engine** | `false` | When `true`, the engine rejects any WS connection that does not present a valid ticket. Global — applies to all plugins. Replaces `WWV_SKIP_WS_AUTH=false` once JWKS is wired (step 7a). |
|
||||
| `REQUIRE_TICKET_AUTH_PLUGINS` | **Data Engine** | `""` | Comma-separated plugin IDs for per-plugin enforcement before enabling the global flag. Not yet implemented (see Divergence Note below). |
|
||||
| `ENFORCE_ORIGIN_ALLOWLIST` | **Data Engine** | `false` | When `true`, the engine rejects connections from Origins not in its configured allowlist. Enable after populating the allowlist from observed traffic (step 7b). |
|
||||
| `PROXY_HOST_ALLOWLIST` | **Local App** | `""` (deny all) | SSRF allowlist for the camera / iframe proxy route. `""` or unset = deny all (safe default). `"*"` = permissive + logs WARN per host (observation mode). Comma-separated list = explicit allowlist. Ship `"*"` initially; tighten to an explicit list after one week of log observation (step 7c). |
|
||||
|
||||
### Deployed Reality: `WWV_SKIP_WS_AUTH`
|
||||
|
||||
> **Divergence note:** The Data Engine workstream implemented a single global bypass
|
||||
> flag (`WWV_SKIP_WS_AUTH`) instead of the three granular master-plan flags
|
||||
> (`REQUIRE_TICKET_AUTH`, `REQUIRE_TICKET_AUTH_PLUGINS`, `ENFORCE_ORIGIN_ALLOWLIST`).
|
||||
> The master-plan flags remain the target architecture and must be implemented before
|
||||
> step 7. `WWV_SKIP_WS_AUTH` is the current interim control.
|
||||
|
||||
| Flag | Repo | Default | Meaning |
|
||||
|---|---|---|---|
|
||||
| `WWV_SKIP_WS_AUTH` | **Data Engine** | `false` | When `true`, every WS connection is pre-authenticated — no JWT is checked. **Currently `true` in production and load-bearing** (JWKS not yet wired; the engine cannot verify real tokens). Must stay `true` until deploy step 4 wires JWKS. Flip to `false` as part of step 5 smoke test, replacing it with `REQUIRE_TICKET_AUTH=true`. |
|
||||
|
||||
---
|
||||
|
||||
## Per-Environment Table
|
||||
|
||||
Update this table whenever a flag changes in Coolify.
|
||||
|
||||
| Flag | Local dev | Staging | Production | Last updated |
|
||||
|---|---|---|---|---|
|
||||
| `NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS` | `""` (.env.example) | `""` (not set) | `""` (not set) | 2026-05-21 |
|
||||
| `REQUIRE_TICKET_AUTH` | N/A | N/A | N/A (not yet implemented) | — |
|
||||
| `REQUIRE_TICKET_AUTH_PLUGINS` | N/A | N/A | N/A (not yet implemented) | — |
|
||||
| `ENFORCE_ORIGIN_ALLOWLIST` | N/A | N/A | N/A (not yet implemented) | — |
|
||||
| `PROXY_HOST_ALLOWLIST` | `"*"` (.env.example) | TBD — set before step 5 | not set (= deny all) | 2026-05-21 |
|
||||
| `WWV_SKIP_WS_AUTH` | `false` | TBD — set before step 4 | `true` (**load-bearing**) | 2026-05-20 |
|
||||
|
||||
---
|
||||
|
||||
## Rollout Sequence
|
||||
|
||||
The sequence in which flags are set during the ADR-001 deploy order:
|
||||
|
||||
| Deploy step | Service | Flag change | Notes |
|
||||
|---|---|---|---|
|
||||
| Step 1 | Local App | Set `PROXY_HOST_ALLOWLIST="*"` | Observation mode — watch WARN logs for one week |
|
||||
| Step 3 | Local App | `NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS=""` confirmed empty | Dormant — no change needed, just confirm |
|
||||
| Step 4 | Data Engine | JWKS wired; `WWV_SKIP_WS_AUTH` remains `true` | Both paths exist, neither enforced |
|
||||
| Step 5 (staging) | Local App | `NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS=test-synthetic` | Smoke test only — revert after |
|
||||
| Step 5 (staging) | Data Engine | `WWV_SKIP_WS_AUTH=false` | Prove real JWT verification end-to-end |
|
||||
| Step 6 | Local App | `NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS=<first-real-plugin>` | One plugin at a time, 24 h soak |
|
||||
| Step 6 | Data Engine | `REQUIRE_TICKET_AUTH_PLUGINS=<same-plugin>` | Mirror Local App change |
|
||||
| Step 7a | Data Engine | `REQUIRE_TICKET_AUTH=true` | Global default-deny; 24 h soak |
|
||||
| Step 7b | Data Engine | `ENFORCE_ORIGIN_ALLOWLIST=true` | After populating allowlist from observed connections |
|
||||
| Step 7c | Local App | `PROXY_HOST_ALLOWLIST=<observed-list>` | Replace `"*"` with explicit host list |
|
||||
|
||||
---
|
||||
|
||||
## Rollback
|
||||
|
||||
Every step is independently revertable by flipping its single flag back. The old
|
||||
no-auth data path remains wired throughout steps 1–6 and is only superseded at
|
||||
step 7a. If anything breaks, removing the plugin from
|
||||
`NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS` immediately restores the old path for that
|
||||
plugin.
|
||||
@@ -0,0 +1,33 @@
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Files Catalog
|
||||
|
||||
## 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.
|
||||
|
||||
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 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/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
|
||||
- `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 the DataEngineV2 runner (`wwv-data-engine-v2`) loaded with local seeders.
|
||||
|
||||
## Configuration
|
||||
- `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 frontend plugins conform to the `@worldwideview/wwv-plugin-sdk` interface and are developed inside `packages/wwv-plugin-<name>/` or `local-plugins/<name>/`.
|
||||
- **Seeders Directory:** Backend telemetry scripts are developed in the `local-seeders/community/<name>/` or `local-seeders/private/<name>/` directories and are mounted directly into the data engine at runtime.
|
||||
@@ -0,0 +1,116 @@
|
||||
# GeoJSON Data Guide
|
||||
|
||||
WorldWideView supports visualizing external datasets and local static files by interpreting GeoJSON files. When using the built-in GeoJSON parser (for instance, via declarative configs, static plugins, or user-uploaded files), the data is automatically normalized into our internal `GeoEntity` format so it seamlessly displays on the globe and the UI's detail panels.
|
||||
|
||||
This guide outlines exactly what structures are supported, what isn't, and how you can map your data into the UI.
|
||||
|
||||
---
|
||||
|
||||
## What is Supported?
|
||||
|
||||
Our parser enforces a subset of the **RFC 7946** standard. To be successfully interpreted, your JSON file must meet the following criteria:
|
||||
|
||||
### 1. Root Level
|
||||
The root of your JSON document must be a `FeatureCollection`. It must contain a `features` array.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "FeatureCollection",
|
||||
"features": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Supported Geometry: Points
|
||||
WorldWideView's declarative parser strictly supports **Point** geometries. Your coordinates must be a flat array of numbers: `[longitude, latitude]` or optionally `[longitude, latitude, altitude]`.
|
||||
|
||||
```json
|
||||
"geometry": {
|
||||
"type": "Point",
|
||||
"coordinates": [-83.74088, 42.27756, 150.0]
|
||||
}
|
||||
```
|
||||
*Note: Altitude (the 3rd coordinate) is optional. If omitted, the entity will be clamped to the ground.*
|
||||
|
||||
### 3. Properties and Metadata
|
||||
You can include any arbitrary metadata inside the `properties` object. The parser maps these properties to the UI using a `FieldMapping` configuration.
|
||||
|
||||
```json
|
||||
"properties": {
|
||||
"stream": "http://example.com/video.mjpg",
|
||||
"country": "United States",
|
||||
"is_static": false,
|
||||
"nested_data": {
|
||||
"speed": 45,
|
||||
"heading": 180
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Field Mapping
|
||||
When configuring your data source, you can define how your GeoJSON properties map to standard WorldWideView `GeoEntity` fields. This is done via dot-notation:
|
||||
|
||||
| GeoEntity Field | Description | Example Path |
|
||||
| --- | --- | --- |
|
||||
| `id` | Unique identifier | Automatically maps to `Feature.id` if present, otherwise uses array index. |
|
||||
| `heading` | Rotation angle (degrees) | `properties.nested_data.heading` |
|
||||
| `speed` | Speed value | `properties.nested_data.speed` |
|
||||
| `timestamp` | Time of the event (string or epoch) | `properties.last_updated` |
|
||||
| `label` | Primary text label shown on map | `properties.city` |
|
||||
| `properties` | Custom fields mapped to the UI panel | `properties.stream` |
|
||||
|
||||
Any property extracted via mapping will appear automatically in the Entity Info Card when a user clicks the point on the map.
|
||||
|
||||
---
|
||||
|
||||
## What is NOT Supported?
|
||||
|
||||
To ensure extreme performance (60 FPS with 10k+ entities) and a unified UI experience, the following GeoJSON structures are **not supported** by the automatic data parser:
|
||||
|
||||
### 1. Complex Geometries
|
||||
The declarative parser will fail to render the following geometry types:
|
||||
- `Polygon`
|
||||
- `MultiPolygon`
|
||||
- `LineString`
|
||||
- `MultiLineString`
|
||||
- `GeometryCollection`
|
||||
|
||||
*Why?* The automatic parser maps features to single point entities (billboards or 3D models). If you supply a `Polygon`, the parser will read the nested coordinate arrays (`[[lon, lat], ...]`) as invalid numbers, resulting in a silent failure (`NaN` clamping).
|
||||
|
||||
If you need to render borders, heatmaps, or route lines, you must build a **Code Bundle Plugin** and interact with the Cesium primitives (`PolygonHierarchy`, `PolylineCollection`) directly via the `renderEntity` API.
|
||||
|
||||
### 2. Top-Level Features
|
||||
A single isolated `Feature` object at the root of the document will not be parsed. The data must be wrapped in a `FeatureCollection`.
|
||||
|
||||
### 3. Non-Standard Coordinate Orders
|
||||
Cesium and GeoJSON strictly require `[longitude, latitude]`. If your system outputs `[latitude, longitude]`, you must transform the data before passing it to WorldWideView.
|
||||
|
||||
---
|
||||
|
||||
## Example: Perfect GeoJSON Structure
|
||||
|
||||
Here is a fully supported and optimized example demonstrating cameras mounted globally:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "FeatureCollection",
|
||||
"features": [
|
||||
{
|
||||
"type": "Feature",
|
||||
"id": "cam-001",
|
||||
"geometry": {
|
||||
"type": "Point",
|
||||
"coordinates": [-83.74088, 42.27756]
|
||||
},
|
||||
"properties": {
|
||||
"stream": "http://173.167.10.225:80/mjpg/video.mjpg",
|
||||
"country": "United States",
|
||||
"city": "Ann Arbor",
|
||||
"categories": ["traffic"],
|
||||
"is_static": false
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
By ensuring your data matches this structure, WorldWideView can effortlessly stream, render, and display your intelligence layers on the interactive 3D globe.
|
||||
@@ -0,0 +1,281 @@
|
||||
<!-- 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 Repository
|
||||
|
||||
You only need the main WorldWideView application. The data engine backend will run automatically via Docker. Open your terminal and navigate to the folder where you want to store your code (e.g., `C:\dev`).
|
||||
|
||||
Run this command to download the code:
|
||||
```bash
|
||||
git clone https://github.com/silvertakana/worldwideview.git
|
||||
```
|
||||
|
||||
### 1.3 Install Dependencies
|
||||
|
||||
Next, 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: Scaffold the Plugin and Backend Seeder
|
||||
|
||||
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.
|
||||
|
||||
We will use the workspace CLI tool to generate a blank plugin template and its associated backend seeder in one go. In your terminal, navigate to your main `worldwideview` folder and run:
|
||||
|
||||
```bash
|
||||
node packages/wwv-cli/dist/index.js create
|
||||
```
|
||||
|
||||
The CLI will launch an interactive survey. Answer as follows:
|
||||
1. **Unique ID**: `iss`
|
||||
2. **Display Name**: `ISS Live Tracker`
|
||||
3. **Description**: `Real-time International Space Station tracking.`
|
||||
4. **Category**: `Space`
|
||||
5. **Data Architecture**: `Real-Time WebSockets (Generates backend seeder)`
|
||||
6. **Globe Rendering**: `2D Billboard`
|
||||
7. **Community Sharing**: `Yes, public community seeder`
|
||||
|
||||
This automatically creates:
|
||||
- Your frontend plugin at `local-plugins/wwv-plugin-iss`
|
||||
- Your backend seeder at `local-seeders/community/iss`
|
||||
|
||||
Now install the dependencies to finalize the setup:
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> **Dependency Management:** You do *not* need to create a `package.json` or manually install standard dependencies (like `axios`) for your backend seeder. The `wwv-data-engine-v2` runner dynamically resolves these via the pnpm workspace, keeping your seeder lightweight.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Write the Polling Logic (Backend Seeder)
|
||||
|
||||
Open the newly generated seeder file in your text editor: `local-seeders/community/iss/seeder.mjs`.
|
||||
|
||||
The Data Engine Runner will dynamically discover this script and execute its `fetch(ctx)` function based on the interval you define. Replace its contents with this code:
|
||||
|
||||
```javascript
|
||||
// seeder.mjs
|
||||
const WTIA_URL = 'https://api.wheretheiss.at/v1/satellites/25544';
|
||||
|
||||
export default {
|
||||
// Required: the unique namespace used by your plugin
|
||||
id: "iss",
|
||||
|
||||
// Define polling interval inside the seeder
|
||||
intervalMs: 5000,
|
||||
|
||||
// The Data Engine will call this function every intervalMs
|
||||
async fetch(ctx) {
|
||||
const { axios, logger } = ctx;
|
||||
|
||||
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 array
|
||||
const entities = [{
|
||||
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
|
||||
}];
|
||||
|
||||
logger.info(`[ISS] Poll OK: updated position to ${data.latitude}, ${data.longitude}`);
|
||||
|
||||
// 3. Return the array of entities, the engine runner will broadcast it over WebSockets
|
||||
return entities;
|
||||
|
||||
} catch (error) {
|
||||
logger.error(`[ISS] Polling error: ${error.message}`);
|
||||
return [];
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Testing the Data Engine
|
||||
|
||||
Before we modify the frontend, let's prove that our backend is actually fetching the ISS data.
|
||||
|
||||
### 4.1 Start the Engine
|
||||
|
||||
In your terminal, navigate to the `worldwideview` folder and start the entire stack using Docker Compose:
|
||||
```bash
|
||||
pnpm dev:all
|
||||
```
|
||||
Wait for the Data Engine Docker container to start. You should see `[ISS] Poll OK: updated position` appearing in the terminal logs every 5 seconds. Leave this terminal running.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Write the Plugin Logic (Frontend)
|
||||
|
||||
Now we will finalize the visual part of the plugin that connects to our backend stream and draws the ISS on the 3D globe.
|
||||
|
||||
### 5.1 Update the Plugin Code
|
||||
|
||||
Open `local-plugins/wwv-plugin-iss/src/index.ts` in your text editor. The CLI generated a boilerplate for you, but we want to customize the rendering with a 3D model. 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 6: Connecting and Testing Everything
|
||||
|
||||
Now we will link your new plugin to your local WorldWideView application to see it in action.
|
||||
|
||||
### 6.1 Develop Your Plugin
|
||||
|
||||
Because your plugin is located in `local-plugins/wwv-plugin-iss`, it is automatically detected by the workspace.
|
||||
You do not need to link it manually.
|
||||
|
||||
Since you already started the whole stack (`pnpm dev:all`) in Step 4, the `dev:plugins` watcher is already running in the background. It will automatically build your frontend plugin code whenever you save changes.
|
||||
|
||||
### 6.2 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 `pnpm dev:all` terminal is still running without errors.
|
||||
> - 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 `id` defined in `seeder.mjs`.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Publishing Your Plugin
|
||||
|
||||
You've built it, now share it with the world!
|
||||
|
||||
### 7.1 Update package.json
|
||||
|
||||
Open `c:\dev\worldwideview\local-plugins\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": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### 7.2 Publish to NPM
|
||||
|
||||
Log in to NPM and publish your package using the WWV CLI from the project root (you can also use the `--org` flag to publish under your own NPM organization):
|
||||
```bash
|
||||
npm login
|
||||
node packages/wwv-cli/dist/index.js publish iss [--org <your-org>]
|
||||
```
|
||||
*(Or `npx wwv publish iss [--org <your-org>]` if installed globally)*
|
||||
|
||||
### 7.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,90 @@
|
||||
<!-- 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 lightweight Javascript data polling script.
|
||||
|
||||
WorldWideView is a completely agnostic renderer. It has absolutely no concept of a "unified" Data Engine. If 30 plugins require 30 different WebSocket servers, the application will blindly open 30 connections. Each plugin is a self-contained package and **MUST explicitly declare its own `streamUrl` in its manifest or config**. Do NOT assume the frontend acts as a unified pipe.
|
||||
|
||||
While you can host your own backend, we provide the `DataEngineV2` runner as a standardized environment for seeders.
|
||||
|
||||
### Data Engine V2 Seeder Architecture
|
||||
Instead of the frontend fetching data, you write a lightweight seeder script that connects to an upstream source, normalizes the data, and is executed by the central `wwv-data-engine-v2` host runner.
|
||||
|
||||
1. **Create a Seeder Directory:** Inside your WorldWideView project, create a folder under `local-seeders/` (e.g., `local-seeders/community/my-plugin/`). Note that seeders are split into `community` and `private` tiers to prevent namespace collisions.
|
||||
2. **Write the Seeder Script:** Create a `seeder.mjs` file that exports a `fetch(ctx)` function.
|
||||
3. **Engine Auto-Discovery:** The local Docker-based `wwv-data-engine-v2` automatically mounts this directory, discovers your script, and runs it on the defined interval.
|
||||
4. **WebSocket & REST Delivery:** Seeders in V2 expose both a WebSocket stream (`/stream`) for real-time instantaneous updates, and a REST API endpoint (`/api/:id`) for fetching live data snapshots directly from Redis.
|
||||
|
||||
### Dependency Management & Monorepo Hoisting
|
||||
Seeders within `local-seeders/` are strictly orchestrated within the pnpm workspace. They are executed by the central runner, not as standalone applications.
|
||||
- **Keep `package.json` clean**: Do not include bulky `dependencies` in your seeder's local `package.json` (unless it's an exceptional, bespoke library).
|
||||
- **Workspace Resolution**: Standard packages (e.g., `zod`, `ws`, `node-cron`, `undici`) are provided by the engine. At runtime, `wwv-data-engine-v2` leverages native Node.js module resolution to fetch the required dependencies directly from the root workspace or its own containerized runtime. Seeders MUST NOT bundle these dependencies.
|
||||
- **Lightweight by Design**: This dependency orchestration guarantees that seeders remain extremely lightweight, hot-reloading takes milliseconds, and Docker container size stays optimized.
|
||||
|
||||
> [!TIP]
|
||||
> **Debugging WebSockets:** If your frontend isn't receiving data from your backend seeder:
|
||||
> 1. Check the `wwv-data-engine-v2` 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 plugins should explicitly define their own `streamUrl`, or fallback to the cloud at `wss://dataenginev2.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:**
|
||||
Log in to NPM and publish your package using the WWV CLI from the project root (you can also use the `--org` flag to publish under your own NPM organization):
|
||||
```bash
|
||||
npm login
|
||||
node packages/wwv-cli/dist/index.js publish <plugin-name> [--org <your-org>]
|
||||
```
|
||||
*(Or `npx wwv publish <plugin-name> [--org <your-org>]` if installed globally)*
|
||||
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,128 @@
|
||||
<!-- 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 packages within the monorepo workspace. To generate a new plugin sandbox, use the official interactive CLI from the root of your `worldwideview` repository:
|
||||
|
||||
```bash
|
||||
node packages/wwv-cli/dist/index.js create --local
|
||||
```
|
||||
|
||||
The CLI will launch an interactive survey to configure your plugin:
|
||||
1. **Unique ID**: `my-first-plugin`
|
||||
2. **Display Name**: `My First Data Layer`
|
||||
3. **Description**: `A simple example plugin.`
|
||||
4. **Category**: `Custom`
|
||||
5. **Data Architecture**: `REST Polling / Static Data (Frontend only)`
|
||||
6. **Globe Rendering**: `Map Point`
|
||||
|
||||
This automatically creates a lightweight Vite-based project pre-configured with the `@worldwideview/wwv-plugin-sdk` inside the `local-plugins/wwv-plugin-my-first-plugin/` directory.
|
||||
|
||||
Once the scaffolding completes, install the dependencies:
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## 3. Develop Your Plugin
|
||||
|
||||
Because your plugin is created inside the `local-plugins/` directory, it is automatically recognized by the pnpm workspace.
|
||||
|
||||
To see your plugin live on the globe while you develop, simply start the standard development servers from the repository root:
|
||||
|
||||
```bash
|
||||
pnpm dev:all
|
||||
```
|
||||
|
||||
The `dev:all` command automatically starts the frontend, the data engine, and the `dev:plugins` watcher. This watcher will automatically rebuild your plugin whenever you save a file in `local-plugins/`.
|
||||
|
||||
> [!TIP]
|
||||
> **Debugging Registration Issues:** If your plugin doesn't appear in the WorldWideView "Installed Plugins" list, check your `package.json` inside your local plugin folder. Ensure `id`, `name`, and `version` are populated correctly. Also verify that you ran `pnpm install` from the workspace root.
|
||||
|
||||
## 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, creating backend seeders using the `local-seeders` sandbox, or publishing your plugin to the global Marketplace—proceed to the **[Advanced Plugin Guide](docs/plugin-advanced.md)**.
|
||||
@@ -0,0 +1,28 @@
|
||||
<!-- 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 synchronously, including aircraft, maritime vessels, conflict events, satellites, and environmental data.
|
||||
|
||||
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 our default data provider runners like the `DataEngineV2` (`wwv-data-engine-v2`). Note that WorldWideView itself acts as an agnostic client, and any plugin can seamlessly point to its own independent backend WebSocket stream.
|
||||
|
||||
## Key Files
|
||||
- `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/`
|
||||
- **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` and `src/styles/theme-tokens.css`
|
||||
|
||||
## Platform Support
|
||||
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`.
|
||||
@@ -0,0 +1,82 @@
|
||||
<!-- Generated: 2026-04-23 06:11:00 UTC -->
|
||||
# Testing
|
||||
|
||||
## 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 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
|
||||
|
||||
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 targets tests located inside `src/lib/**`, `src/core/**`, `src/plugins/**`, `src/app/**`, and `packages/**`.
|
||||
- **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.
|
||||
|
||||
## Patterns
|
||||
|
||||
### Plain function — no mocks needed
|
||||
Pull in the function, call it with representative inputs, assert the output. See `src/lib/marketplace/cors.test.ts` or `src/app/api/camera/adapters/registry.test.ts` for examples.
|
||||
|
||||
### Stateful singleton — reset in `afterEach`
|
||||
Most of the data layer (`dataBus`, `cacheLayer`, `pollingManager`) is exported as a singleton instance. Tests pass when run alone but fail when run together if state leaks. `DataBus.test.ts` shows the canonical cleanup:
|
||||
|
||||
```typescript
|
||||
import { dataBus } from "./DataBus";
|
||||
|
||||
afterEach(() => {
|
||||
dataBus.removeAllListeners();
|
||||
});
|
||||
```
|
||||
|
||||
### Module-level dependency — mock with `vi.mock`
|
||||
When the module under test pulls in something heavy (the store, the database, Cesium), mock that module before the import. `vi.mock` calls are hoisted, so they take effect even when written below the import in source order. See `src/lib/marketplace/repository.test.ts` (Prisma client) or `src/core/data/PollingManager.test.ts` (Zustand store).
|
||||
|
||||
### Timers — fake them per test
|
||||
`vi.useFakeTimers()` in `beforeEach`, `vi.useRealTimers()` in `afterEach`. Advance time explicitly with `vi.advanceTimersByTimeAsync(ms)`.
|
||||
|
||||
> [!CAUTION]
|
||||
> `vi.runOnlyPendingTimersAsync()` ticks `setInterval`s scheduled on the same tick as the call. For tests where a function runs once synchronously and then schedules a recurring interval, this double-counts the first call. To drain microtasks without advancing the clock, use `await Promise.resolve()` a few times — see `PollingManager.test.ts` for the `flushMicrotasks()` helper.
|
||||
|
||||
## What NOT to Test (Yet)
|
||||
|
||||
- **Cesium-heavy components.** Anything that mounts a `<Viewer>` or renders entities to the globe needs WebGL, which jsdom doesn't provide. These belong in Playwright-style E2E tests rather than unit tests.
|
||||
- **Live database round-trips.** Mock the Prisma client at the module boundary — `repository.test.ts` is the reference pattern. Spinning up a real Postgres in CI is expensive and unreliable.
|
||||
- **Dynamic-import plugin bundles.** The loader uses `import(/* webpackIgnore: true */ entry)` at runtime against a real URL. Test the loader's pre-import logic with a fake module object, not a real dynamic import.
|
||||
|
||||
## Philosophy
|
||||
|
||||
A small focused suite is more valuable than a large one that's expensive to maintain. Each test should answer: *what specific regression does this catch that I'd otherwise discover from a user bug report?*
|
||||
|
||||
Two practical rules:
|
||||
|
||||
1. **Prefer testing pure logic over orchestration.** If a function takes inputs and returns outputs, test it directly. If it coordinates a half-dozen other things (the globe, the store, Cesium primitives), either refactor the pure parts out or use an integration test.
|
||||
2. **Add a test when you fix a bug.** A one-line test that fails today and passes after the fix is enough to prevent the bug from coming back. Land the test in the same PR as the fix.
|
||||
@@ -0,0 +1,50 @@
|
||||
import nextCoreWebVitals from "eslint-config-next/core-web-vitals";
|
||||
import nextTypeScript from "eslint-config-next/typescript";
|
||||
|
||||
const config = [
|
||||
{
|
||||
ignores: [
|
||||
"node_modules/**",
|
||||
".next/**",
|
||||
"out/**",
|
||||
"src/generated/**",
|
||||
"public/cesium/**",
|
||||
"packages/*/dist/**",
|
||||
".worktrees/**",
|
||||
"local-scripts/**",
|
||||
"local-plugins/**",
|
||||
"local-seeders/**",
|
||||
".agents/**",
|
||||
".claude/**",
|
||||
".gemini/**",
|
||||
"*.cjs",
|
||||
],
|
||||
},
|
||||
...nextCoreWebVitals,
|
||||
...nextTypeScript,
|
||||
{
|
||||
rules: {
|
||||
// ─── Demoted on first introduction ─────────────────────────────
|
||||
// The existing codebase has hundreds of violations across these
|
||||
// rules. To make the lint job runnable in CI without blocking on
|
||||
// pre-existing debt, every rule that currently fires errors is
|
||||
// demoted to `warn`. Promote back to `error` once the backlog
|
||||
// is addressed (recommended in this order: prefer-const,
|
||||
// no-unescaped-entities, ban-ts-comment, then the react-hooks
|
||||
// family once the team agrees on the React 19 hook-purity rules).
|
||||
|
||||
// Pre-existing — flagged in the original code review (#96):
|
||||
"@typescript-eslint/no-explicit-any": "warn",
|
||||
"no-console": "off",
|
||||
|
||||
// React 19 hook-purity rules from eslint-plugin-react-hooks 7+:
|
||||
// (These were previously hallucinated or require extra plugins)
|
||||
// Misc one-offs across the codebase:
|
||||
"@typescript-eslint/ban-ts-comment": "warn",
|
||||
"@next/next/no-assign-module-variable": "warn",
|
||||
"prefer-const": "warn",
|
||||
},
|
||||
},
|
||||
];
|
||||
|
||||
export default config;
|
||||
@@ -0,0 +1,55 @@
|
||||
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
|
||||
@@ -0,0 +1,38 @@
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🌍 Setting up WorldWideView for Local Development..."
|
||||
|
||||
# Check for pnpm
|
||||
if ! command -v pnpm &> /dev/null; then
|
||||
echo "❌ Error: pnpm is required but not installed."
|
||||
echo "Please install it first: https://pnpm.io/installation"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "📦 Installing dependencies..."
|
||||
pnpm install
|
||||
|
||||
echo "🔐 Running initial setup (generating secrets)..."
|
||||
pnpm run setup
|
||||
|
||||
# Check for the sibling Data Engine repository
|
||||
if [ ! -d "../wwv-data-engine" ]; then
|
||||
echo ""
|
||||
echo "====================================================================="
|
||||
echo "⚠️ NOTICE: Local Data Engine not found at ../wwv-data-engine"
|
||||
echo ""
|
||||
echo "Frontend-Only Mode: You are developing the frontend UI."
|
||||
echo "WorldWideView will automatically stream data from the Cloud Engine."
|
||||
echo ""
|
||||
echo "Full-Stack Mode: If you want to develop backend data seeders, you"
|
||||
echo "must clone the open-source data engine as a sibling directory:"
|
||||
echo " cd .. && git clone https://github.com/silvertakana/wwv-data-engine"
|
||||
echo " cd wwv-data-engine && pnpm install"
|
||||
echo "====================================================================="
|
||||
echo ""
|
||||
fi
|
||||
|
||||
echo "🚀 Starting local Next.js frontend server..."
|
||||
echo " (To run the data engine backends concurrently, run: pnpm dev:all)"
|
||||
pnpm run dev
|
||||
@@ -0,0 +1 @@
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# Local Plugins
|
||||
|
||||
This directory is a **pnpm workspace** for developing plugins locally without committing them to the main repository.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Scaffold a new plugin
|
||||
node packages/wwv-cli/dist/index.js create
|
||||
|
||||
# Start dev server (auto-discovers local plugins)
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Plugins here get full SDK type support via `workspace:*` linking
|
||||
2. The pre-dev script auto-builds each plugin with Vite
|
||||
3. Built bundles are copied to `public/plugins-local/`
|
||||
4. The marketplace load API auto-discovers them in dev mode
|
||||
5. Everything in this directory is gitignored
|
||||
|
||||
## Publishing to NPM
|
||||
|
||||
When your plugin is ready to share, you can publish it directly to NPM from the root directory:
|
||||
|
||||
```bash
|
||||
node packages/wwv-cli/dist/index.js publish <plugin-name> [--org <your-org>]
|
||||
```
|
||||
+34
-6
@@ -1,8 +1,21 @@
|
||||
import type { NextConfig } from "next";
|
||||
import webpack from "webpack";
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
output: "standalone",
|
||||
serverExternalPackages: ["@prisma/client", "prisma"],
|
||||
transpilePackages: ["@worldwideview/wwv-plugin-sdk", "resium", "react-player", "satellite.js", "@worldwideview/wwv-plugin-fortiguard", "@worldwideview/wwv-plugin-nz-traffic-cameras"],
|
||||
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,
|
||||
},
|
||||
async headers() {
|
||||
return [
|
||||
{
|
||||
@@ -13,11 +26,17 @@ const nextConfig: NextConfig = {
|
||||
value: [
|
||||
"default-src 'self'",
|
||||
// CesiumJS requires unsafe-eval (worker compilation) and unsafe-inline (styles)
|
||||
"script-src 'self' 'unsafe-eval' 'unsafe-inline' blob:",
|
||||
"script-src 'self' 'unsafe-eval' 'unsafe-inline' blob: https://unpkg.com https://cdn.jsdelivr.net https://analytics.worldwideview.dev https://va.vercel-scripts.com https://pagead2.googlesyndication.com https://adservice.google.com https://www.googletagservices.com https://ep2.adtrafficquality.google https://static.cloudflareinsights.com",
|
||||
"style-src 'self' 'unsafe-inline' fonts.googleapis.com",
|
||||
"font-src 'self' fonts.gstatic.com",
|
||||
"img-src 'self' data: blob: *.tile.openstreetmap.org *.arcgisonline.com *.virtualearth.net *.bing.com *.googleapis.com",
|
||||
"connect-src 'self' *.supabase.co *.worldwideview.dev *.cesium.com *.arcgisonline.com *.virtualearth.net *.googleapis.com *.vercel-scripts.com",
|
||||
// Camera streams load images/MJPEG from arbitrary IPs worldwide — http: https: required
|
||||
"img-src 'self' data: blob: http: https:",
|
||||
// Camera HLS streams and external data fetches need arbitrary origins
|
||||
"connect-src 'self' http: https: ws: wss:",
|
||||
// HLS video streams from arbitrary camera sources
|
||||
"media-src 'self' blob: http: https:",
|
||||
// Embeddable video platforms for camera iframes — needs to support arbitrary domains
|
||||
"frame-src 'self' http: https: blob:",
|
||||
"worker-src 'self' blob:",
|
||||
"frame-ancestors 'none'",
|
||||
].join("; "),
|
||||
@@ -34,13 +53,22 @@ const nextConfig: NextConfig = {
|
||||
},
|
||||
];
|
||||
},
|
||||
|
||||
outputFileTracingExcludes: {
|
||||
"*": ["./public/cesium/**"],
|
||||
"*": [
|
||||
"./public/cesium/**"
|
||||
],
|
||||
},
|
||||
env: {
|
||||
CESIUM_BASE_URL: "/cesium",
|
||||
},
|
||||
webpack: (config, { isServer }) => {
|
||||
webpack: (config, { isServer, webpack }) => {
|
||||
config.ignoreWarnings = [
|
||||
{ module: /node_modules[\\/]@opentelemetry/ },
|
||||
{ module: /node_modules[\\/]require-in-the-middle/ },
|
||||
{ module: /node_modules[\\/]@sentry/ },
|
||||
];
|
||||
|
||||
if (!isServer) {
|
||||
// Define CESIUM_BASE_URL for Cesium's worker resolution
|
||||
config.plugins?.push(
|
||||
|
||||
Generated
-8122
File diff suppressed because it is too large.
Load diff
+92
-29
@@ -1,59 +1,122 @@
|
||||
{
|
||||
"name": "worldwideview",
|
||||
"version": "0.1.0",
|
||||
"version": "2.18.1",
|
||||
"private": true,
|
||||
"workspaces": ["packages/*"],
|
||||
"type": "module",
|
||||
"packageManager": "[email protected]",
|
||||
"scripts": {
|
||||
"setup": "node scripts/setup.mjs",
|
||||
"test-worktree": "node scripts/test-worktree.mjs",
|
||||
"clean": "node -e \"const fs=require('fs');fs.rmSync('.next',{recursive:true,force:true})\"",
|
||||
"dev": "next dev --webpack",
|
||||
"predev": "npx prisma migrate deploy && node scripts/copy-cesium.mjs",
|
||||
"dev": "node scripts/dev.mjs",
|
||||
"dev:all": "concurrently -n \"dev,backends\" -c \"magenta,blue\" \"pnpm dev\" \"pnpm dev:backends\"",
|
||||
"dev:backends": "docker compose --profile engine up wwv-data-engine wwv-redis",
|
||||
"dev:plugins": "node scripts/watch-local-plugins.mjs",
|
||||
"predev": "node scripts/boot-db.mjs && npx dotenv-cli -c -- node scripts/safe-db-push.mjs && npx prisma generate && node scripts/copy-cesium.mjs && node scripts/sync-local-plugins.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"
|
||||
"test": "vitest run",
|
||||
"test:e2e": "playwright test",
|
||||
"test:mutate": "stryker run",
|
||||
"lint": "eslint .",
|
||||
"db:reset": "npx prisma migrate reset --force",
|
||||
"db:prune": "node scripts/db-prune.mjs",
|
||||
"generate": "prisma generate"
|
||||
},
|
||||
"dependencies": {
|
||||
"@worldwideview/wwv-plugin-sdk": "*",
|
||||
"@worldwideview/wwv-plugin-aviation": "*",
|
||||
"@worldwideview/wwv-plugin-maritime": "*",
|
||||
"@worldwideview/wwv-plugin-wildfire": "*",
|
||||
"@worldwideview/wwv-plugin-borders": "*",
|
||||
"@worldwideview/wwv-plugin-camera": "*",
|
||||
"@worldwideview/wwv-plugin-military-aviation": "*",
|
||||
"@auth/prisma-adapter": "^2.11.1",
|
||||
"@prisma/adapter-better-sqlite3": "^7.5.0",
|
||||
"@prisma/client": "^7.5.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.53.1",
|
||||
"@supabase/supabase-js": "^2.106.0",
|
||||
"@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",
|
||||
"lucide-react": "^0.576.0",
|
||||
"next": "16.1.6",
|
||||
"jose": "^6.2.3",
|
||||
"lucide-react": "^1.16.0",
|
||||
"next": "16.2.6",
|
||||
"next-auth": "^5.0.0-beta.30",
|
||||
"prisma": "^7.5.0",
|
||||
"react": "19.2.3",
|
||||
"react-dom": "19.2.3",
|
||||
"openid-client": "^6.8.4",
|
||||
"pg": "^8.21.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.1",
|
||||
"satellite.js": "^7.0.1",
|
||||
"stripe": "^22.1.1",
|
||||
"tslib": "^2.8.1",
|
||||
"ws": "^8.14.2",
|
||||
"zustand": "^5.0.11"
|
||||
"undici": "^8.3.0",
|
||||
"ws": "^8.20.1",
|
||||
"zod": "^4.4.3",
|
||||
"zustand": "^5.0.13"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@eslint/compat": "^2.1.0",
|
||||
"@eslint/eslintrc": "^3.3.5",
|
||||
"@playwright/test": "^1.60.0",
|
||||
"@stryker-mutator/core": "^9.6.1",
|
||||
"@stryker-mutator/vitest-runner": "^9.6.1",
|
||||
"@testing-library/dom": "^10.4.1",
|
||||
"@testing-library/react": "^16.3.2",
|
||||
"@types/bcryptjs": "^3.0.0",
|
||||
"@types/node": "^20",
|
||||
"@types/cesium": "^1.70.4",
|
||||
"@types/node": "^25",
|
||||
"@types/react": "^19",
|
||||
"@types/react-dom": "^19",
|
||||
"@types/ws": "^8.18.1",
|
||||
"@vitejs/plugin-react": "^5.1.4",
|
||||
"@typescript-eslint/eslint-plugin": "^8.59.4",
|
||||
"@typescript-eslint/parser": "^8.59.4",
|
||||
"@vitejs/plugin-react": "^6.0.2",
|
||||
"@vitest/coverage-v8": "4.1.6",
|
||||
"concurrently": "^9.2.1",
|
||||
"copy-webpack-plugin": "^14.0.0",
|
||||
"eslint": "^9",
|
||||
"eslint-config-airbnb": "^19.0.4",
|
||||
"eslint-config-airbnb-typescript": "^18.0.0",
|
||||
"eslint-config-next": "^16.2.6",
|
||||
"eslint-plugin-import": "^2.32.0",
|
||||
"eslint-plugin-jsx-a11y": "^6.10.2",
|
||||
"eslint-plugin-react": "^7.37.5",
|
||||
"eslint-plugin-react-hooks": "^7.1.1",
|
||||
"fast-check": "^4.8.0",
|
||||
"jsdom": "^28.1.0",
|
||||
"rollup-plugin-external-globals": "^0.13.0",
|
||||
"tree-kill": "^1.2.2",
|
||||
"tsx": "^4.22.2",
|
||||
"typescript": "^5",
|
||||
"vitest": "^4.0.18"
|
||||
"vite": "^8.0.13",
|
||||
"vitest": "^4.1.6"
|
||||
},
|
||||
"pnpm": {
|
||||
"overrides": {
|
||||
"@spz-loader/core": "0.3.0",
|
||||
"form-data@<2.5.4": "^2.5.5",
|
||||
"form-data@>=3.0.0 <3.0.4": "^3.0.4",
|
||||
"form-data@>=4.0.0 <4.0.4": "^4.0.5",
|
||||
"fast-uri@<3.1.2": "^3.1.2"
|
||||
},
|
||||
"onlyBuiltDependencies": [
|
||||
"@prisma/engines",
|
||||
"@sentry/cli",
|
||||
"prisma",
|
||||
"protobufjs",
|
||||
"sharp",
|
||||
"esbuild",
|
||||
"better-sqlite3"
|
||||
]
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=20.0.0",
|
||||
"pnpm": ">=9.0.0"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
# @worldwideview/wwv-cli
|
||||
|
||||
The official Command Line Interface for scaffolding and publishing WorldWideView plugins.
|
||||
|
||||
## Usage
|
||||
|
||||
This CLI is designed to be run from within the `worldwideview` monorepo.
|
||||
|
||||
### 1. Scaffold a new plugin
|
||||
```bash
|
||||
node packages/wwv-cli/dist/index.js create
|
||||
```
|
||||
This command generates a new plugin directory with a boilerplate `index.ts` and `package.json` configured for the WorldWideView plugin architecture inside the `local-plugins/` directory.
|
||||
|
||||
*(Note: To create a built-in plugin inside `packages/` instead, use the `--core` flag).*
|
||||
|
||||
### 2. Publish a plugin
|
||||
Once your plugin is ready for release, you can publish it to NPM. You can do this from within the plugin directory or directly from the project root.
|
||||
|
||||
**From the plugin directory:**
|
||||
```bash
|
||||
cd local-plugins/<plugin-name>
|
||||
npm login
|
||||
node ../../packages/wwv-cli/dist/index.js publish
|
||||
```
|
||||
|
||||
**From the project root:**
|
||||
You can also run the CLI from the root by providing the plugin name:
|
||||
```bash
|
||||
node packages/wwv-cli/dist/index.js publish <plugin-name>
|
||||
```
|
||||
|
||||
**Custom NPM Organizations:**
|
||||
By default, plugins are scaffolded under the `@worldwideview` NPM scope. To publish to your own organization, use the `--org` flag:
|
||||
```bash
|
||||
node packages/wwv-cli/dist/index.js publish <plugin-name> --org my-username
|
||||
```
|
||||
This will permanently update your `package.json` to use `@my-username` and publish the package.
|
||||
|
||||
The publish command verifies that your `package.json` contains the required `"worldwideview"` manifest block and invokes `npm publish --access public`.
|
||||
|
||||
## Development
|
||||
|
||||
To re-compile the CLI during development:
|
||||
```bash
|
||||
pnpm --filter @worldwideview/wwv-cli run build
|
||||
```
|
||||
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"name": "@worldwideview/wwv-cli",
|
||||
"version": "1.2.0",
|
||||
"type": "module",
|
||||
"description": "WorldWideView CLI",
|
||||
"main": "dist/index.js",
|
||||
"bin": {
|
||||
"wwv": "dist/index.js"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"dev": "tsc --watch",
|
||||
"clean": "rm -rf dist"
|
||||
},
|
||||
"dependencies": {
|
||||
"commander": "^14.0.3",
|
||||
"prompts": "^2.4.2"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^25.9.1",
|
||||
"@types/prompts": "^2.4.9",
|
||||
"typescript": "^5.0.0"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
/* eslint-disable no-console */
|
||||
import { Command } from 'commander';
|
||||
import { saveConfig } from '../utils/config.js';
|
||||
|
||||
export const configCommand = new Command('config')
|
||||
.description('Manage WWV CLI configuration')
|
||||
.argument('<action>', 'Action to perform (e.g., set)')
|
||||
.argument('<key>', 'Config key (e.g., org)')
|
||||
.argument('<value>', 'Config value (e.g., your-username)')
|
||||
.action((action, key, value) => {
|
||||
if (action !== 'set') {
|
||||
console.error(`[wwv-cli] Unknown config action: ${action}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (key === 'org') {
|
||||
saveConfig({ org: value });
|
||||
console.log(`[wwv-cli] Successfully set default organization to @${value}`);
|
||||
} else {
|
||||
console.error(`[wwv-cli] Unknown config key: ${key}. Valid keys: org`);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,235 @@
|
||||
/* eslint-disable no-console */
|
||||
import { Command } from 'commander';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
import prompts from 'prompts';
|
||||
|
||||
export const createCommand = new Command('create')
|
||||
.description('Interactively scaffold a new WorldWideView plugin')
|
||||
.option('-c, --core', 'Create inside packages instead of local-plugins (for core contributors)')
|
||||
.action(async (options) => {
|
||||
const response = await prompts([
|
||||
{
|
||||
type: 'text',
|
||||
name: 'pluginId',
|
||||
message: 'What is the unique ID for your plugin? (e.g. my-tracker)',
|
||||
validate: value => value.length > 0 ? true : 'Plugin ID is required'
|
||||
},
|
||||
{
|
||||
type: 'text',
|
||||
name: 'displayName',
|
||||
message: 'What is the display name? (e.g. My Live Tracker)',
|
||||
initial: (prev: string) => prev.replace(/-/g, ' ').replace(/\b\w/g, (l: string) => l.toUpperCase())
|
||||
},
|
||||
{
|
||||
type: 'text',
|
||||
name: 'description',
|
||||
message: 'Enter a short description:'
|
||||
},
|
||||
{
|
||||
type: 'select',
|
||||
name: 'category',
|
||||
message: 'Which category does this plugin belong to?',
|
||||
choices: [
|
||||
{ title: 'Aviation (Plane icon)', value: 'aviation' },
|
||||
{ title: 'Maritime (Ship icon)', value: 'maritime' },
|
||||
{ title: 'Space (Satellite icon)', value: 'space' },
|
||||
{ title: 'Weather (Cloud icon)', value: 'weather' },
|
||||
{ title: 'Custom (Box icon)', value: 'custom' }
|
||||
]
|
||||
},
|
||||
{
|
||||
type: 'select',
|
||||
name: 'architecture',
|
||||
message: 'How will your plugin receive data?',
|
||||
choices: [
|
||||
{ title: 'REST Polling / Static Data (Frontend only)', value: 'polling' },
|
||||
{ title: 'Real-Time WebSockets (Generates backend seeder)', value: 'websocket' }
|
||||
]
|
||||
},
|
||||
{
|
||||
type: (prev: string) => prev === 'websocket' ? 'select' : null,
|
||||
name: 'seederTier',
|
||||
message: 'Which tier should your backend seeder belong to?',
|
||||
choices: [
|
||||
{ title: 'Community (Open data, shared)', value: 'community' },
|
||||
{ title: 'Private (Requires API keys, restricted)', value: 'private' }
|
||||
]
|
||||
},
|
||||
{
|
||||
type: 'select',
|
||||
name: 'renderStyle',
|
||||
message: 'How should entities be rendered on the 3D globe?',
|
||||
choices: [
|
||||
{ title: '2D Billboard (Great for static icons)', value: 'billboard' },
|
||||
{ title: '3D Model with LOD (Transitions 2D to 3D)', value: 'model' },
|
||||
{ title: 'Simple Point (High performance dots)', value: 'point' }
|
||||
]
|
||||
}
|
||||
]);
|
||||
|
||||
if (!response.pluginId) {
|
||||
console.log('Plugin creation cancelled.');
|
||||
return;
|
||||
}
|
||||
|
||||
const { pluginId, displayName, description, category, architecture, seederTier, renderStyle } = response;
|
||||
|
||||
const targetBaseDir = options.core ? 'packages' : 'local-plugins';
|
||||
const pluginDir = path.join(process.cwd(), targetBaseDir, `wwv-plugin-${pluginId}`);
|
||||
|
||||
if (fs.existsSync(pluginDir)) {
|
||||
console.error(`Error: Directory ${pluginDir} already exists.`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
fs.mkdirSync(pluginDir, { recursive: true });
|
||||
|
||||
// Determine category icon
|
||||
const iconMap: Record<string, string> = {
|
||||
aviation: 'Plane',
|
||||
maritime: 'Ship',
|
||||
space: 'Satellite',
|
||||
weather: 'Cloud',
|
||||
custom: 'Box'
|
||||
};
|
||||
const defaultIcon = iconMap[category] || 'Box';
|
||||
|
||||
// Package.json boilerplate
|
||||
const streamUrlField = architecture === 'websocket'
|
||||
? `\n "streamUrl": "wss://dataenginev2.worldwideview.dev/stream",`
|
||||
: '';
|
||||
|
||||
const packageJsonContent = `{
|
||||
"name": "@worldwideview/wwv-plugin-${pluginId}",
|
||||
"version": "1.0.0",
|
||||
"description": "${description}",
|
||||
"main": "dist/frontend.mjs",
|
||||
"module": "dist/frontend.mjs",
|
||||
"exports": {
|
||||
".": {
|
||||
"import": "./dist/frontend.mjs",
|
||||
"require": "./dist/frontend.mjs"
|
||||
}
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc"
|
||||
},
|
||||
"dependencies": {
|
||||
"@worldwideview/wwv-plugin-sdk": "latest"
|
||||
},
|
||||
"worldwideview": {
|
||||
"pluginId": "${pluginId}",
|
||||
"name": "${displayName}",
|
||||
"description": "${description}",
|
||||
"icon": "${defaultIcon}",
|
||||
"category": "${category}",${streamUrlField}
|
||||
"author": "Your Name",
|
||||
"dev_entry": "src/index.ts",
|
||||
"format": "bundle"
|
||||
}
|
||||
}
|
||||
`;
|
||||
|
||||
// index.ts boilerplate
|
||||
const renderBoilerplate = {
|
||||
billboard: `return {
|
||||
type: 'billboard',
|
||||
iconUrl: '/icons/default.png',
|
||||
iconScale: 1.0,
|
||||
color: '#ffffff'
|
||||
};`,
|
||||
model: `return {
|
||||
type: 'billboard', // Placeholder for LOD logic, update to 3D model path when zoomed
|
||||
iconUrl: '/icons/default.png',
|
||||
iconScale: 1.0,
|
||||
modelUrl: '/models/default.glb', // Advanced LOD
|
||||
color: '#ffffff'
|
||||
};`,
|
||||
point: `return {
|
||||
type: 'point',
|
||||
color: '#ff0000',
|
||||
size: 8,
|
||||
outlineColor: '#ffffff',
|
||||
outlineWidth: 2
|
||||
};`
|
||||
}[renderStyle as string] || `return {};`;
|
||||
|
||||
const fetchBoilerplate = architecture === 'polling'
|
||||
? `\n async fetch(): Promise<GeoEntity[]> {
|
||||
// Implement REST polling logic here
|
||||
return [];
|
||||
}\n`
|
||||
: '';
|
||||
|
||||
const indexTsContent = `import { WorldPlugin, GeoEntity, CesiumEntityOptions } from '@worldwideview/wwv-plugin-sdk';
|
||||
|
||||
export default class ${pluginId.replace(/-/g, '')}Plugin implements WorldPlugin {
|
||||
id = '${pluginId}';
|
||||
name = '${displayName}';
|
||||
|
||||
async initialize(context: any): Promise<void> {
|
||||
console.log('${displayName} initialized.');
|
||||
}
|
||||
|
||||
getPollingInterval(): number {
|
||||
return ${architecture === 'polling' ? '10000' : '0'}; // ${architecture === 'polling' ? '10 seconds' : '0 for WebSockets'}
|
||||
}
|
||||
${fetchBoilerplate}
|
||||
renderEntity(entity: GeoEntity): CesiumEntityOptions {
|
||||
${renderBoilerplate}
|
||||
}
|
||||
|
||||
renderHUD(entity: GeoEntity): string {
|
||||
return \`<div>
|
||||
<h3>\${entity.id}</h3>
|
||||
<p>Data provided by ${displayName}</p>
|
||||
</div>\`;
|
||||
}
|
||||
}
|
||||
`;
|
||||
|
||||
fs.writeFileSync(path.join(pluginDir, 'package.json'), packageJsonContent);
|
||||
fs.mkdirSync(path.join(pluginDir, 'src'), { recursive: true });
|
||||
fs.writeFileSync(path.join(pluginDir, 'src', 'index.ts'), indexTsContent);
|
||||
|
||||
console.log(`\n✅ Successfully created plugin frontend at ${pluginDir}`);
|
||||
|
||||
// Generate seeder backend if requested
|
||||
if (architecture === 'websocket' && seederTier) {
|
||||
const seederDir = path.join(process.cwd(), 'local-seeders', seederTier, pluginId);
|
||||
|
||||
if (!fs.existsSync(seederDir)) {
|
||||
fs.mkdirSync(seederDir, { recursive: true });
|
||||
|
||||
const seederContent = `// WWV Data Engine Seeder for ${pluginId}
|
||||
export default async function run(context) {
|
||||
console.log('Starting ${displayName} seeder...');
|
||||
|
||||
// Example: Emit a mock entity to the engine
|
||||
setInterval(() => {
|
||||
context.emit({
|
||||
id: '${pluginId}-mock-1',
|
||||
lat: 0,
|
||||
lng: 0,
|
||||
alt: 10000,
|
||||
heading: 0,
|
||||
velocity: 250,
|
||||
properties: {
|
||||
status: 'active'
|
||||
}
|
||||
});
|
||||
}, 1000);
|
||||
}
|
||||
`;
|
||||
fs.writeFileSync(path.join(seederDir, 'seeder.mjs'), seederContent);
|
||||
console.log(`✅ Successfully created plugin seeder at ${seederDir}`);
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`\nNext steps:
|
||||
1. Run \`pnpm install\` from the project root.
|
||||
2. Edit \`index.ts\` in your plugin directory.
|
||||
${architecture === 'websocket' ? '3. Edit `seeder.mjs` in your local-seeders directory.' : ''}
|
||||
`);
|
||||
});
|
||||
@@ -0,0 +1,121 @@
|
||||
/* eslint-disable no-console */
|
||||
import { Command } from 'commander';
|
||||
import { execSync } from 'child_process';
|
||||
import path from 'path';
|
||||
import fs from 'fs';
|
||||
import prompts from 'prompts';
|
||||
import { getConfig, saveConfig } from '../utils/config.js';
|
||||
|
||||
export const publishCommand = new Command('publish')
|
||||
.description('Publish the plugin to NPM and notify the WWV Marketplace')
|
||||
.argument('[pluginName]', 'Name of the plugin to publish (if running from root)')
|
||||
.option('--org <orgName>', 'NPM organization to publish to (e.g., your-username)')
|
||||
.action(async (pluginName, options) => {
|
||||
console.log('[wwv-cli] Preparing to publish plugin...');
|
||||
let cwd = process.cwd();
|
||||
|
||||
// If pluginName is provided, try to find the plugin directory
|
||||
if (pluginName) {
|
||||
const rootLocalPath = path.join(cwd, 'local-plugins', pluginName);
|
||||
const rootWwvLocalPath = path.join(cwd, 'local-plugins', `wwv-plugin-${pluginName}`);
|
||||
const packagesPath = path.join(cwd, 'packages', pluginName);
|
||||
const packagesWwvPath = path.join(cwd, 'packages', `wwv-plugin-${pluginName}`);
|
||||
|
||||
if (fs.existsSync(rootWwvLocalPath)) {
|
||||
cwd = rootWwvLocalPath;
|
||||
} else if (fs.existsSync(rootLocalPath)) {
|
||||
cwd = rootLocalPath;
|
||||
} else if (fs.existsSync(packagesWwvPath)) {
|
||||
cwd = packagesWwvPath;
|
||||
} else if (fs.existsSync(packagesPath)) {
|
||||
cwd = packagesPath;
|
||||
} else {
|
||||
console.error(`[wwv-cli] Error: Could not find plugin '${pluginName}' in local-plugins or packages.`);
|
||||
process.exit(1);
|
||||
}
|
||||
console.log(`[wwv-cli] Found plugin at: ${cwd}`);
|
||||
}
|
||||
|
||||
const pkgPath = path.join(cwd, 'package.json');
|
||||
|
||||
if (!fs.existsSync(pkgPath)) {
|
||||
console.error('[wwv-cli] Error: No package.json found in directory: ' + cwd);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
const pkgContent = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
|
||||
|
||||
if (!pkgContent.worldwideview) {
|
||||
console.error('[wwv-cli] Error: package.json is missing the "worldwideview" manifest block. Is this a WWV plugin?');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const originalName = pkgContent.name;
|
||||
let publishedName = originalName;
|
||||
|
||||
// Determine organization
|
||||
let targetOrg = options.org;
|
||||
const config = getConfig();
|
||||
|
||||
if (!targetOrg) {
|
||||
if (config.org) {
|
||||
targetOrg = config.org;
|
||||
console.log(`[wwv-cli] Using default organization from config: @${targetOrg}`);
|
||||
} else {
|
||||
// Fallback to NPM whoami if possible
|
||||
try {
|
||||
const whoami = execSync('npm whoami', { stdio: 'pipe' }).toString().trim();
|
||||
targetOrg = whoami;
|
||||
} catch (_e) {
|
||||
// Not logged in or errored, ignore
|
||||
}
|
||||
|
||||
const response = await prompts({
|
||||
type: 'text',
|
||||
name: 'org',
|
||||
message: 'What NPM organization/username do you want to publish under?',
|
||||
initial: targetOrg || '',
|
||||
validate: value => value.length > 0 ? true : 'Organization is required'
|
||||
});
|
||||
|
||||
if (!response.org) {
|
||||
console.log('Publish cancelled.');
|
||||
return;
|
||||
}
|
||||
|
||||
targetOrg = response.org;
|
||||
saveConfig({ org: targetOrg });
|
||||
console.log(`[wwv-cli] Saved @${targetOrg} as your default organization.`);
|
||||
}
|
||||
} else {
|
||||
// Save the explicitly passed org as the new default
|
||||
saveConfig({ org: targetOrg });
|
||||
}
|
||||
|
||||
if (targetOrg) {
|
||||
const orgPrefix = targetOrg.startsWith('@') ? targetOrg : `@${targetOrg}`;
|
||||
const baseName = originalName.startsWith('@') ? originalName.split('/')[1] : originalName;
|
||||
publishedName = `${orgPrefix}/${baseName}`;
|
||||
|
||||
if (originalName !== publishedName) {
|
||||
pkgContent.name = publishedName;
|
||||
fs.writeFileSync(pkgPath, JSON.stringify(pkgContent, null, 2) + '\n');
|
||||
console.log(`[wwv-cli] Updated package name to ${publishedName}`);
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`[wwv-cli] Publishing ${publishedName}@${pkgContent.version} to NPM...`);
|
||||
|
||||
// Execute npm publish
|
||||
execSync('npm publish --access public', { stdio: 'inherit', cwd });
|
||||
|
||||
console.log('[wwv-cli] Successfully published to NPM!');
|
||||
console.log('[wwv-cli] To submit this plugin to the WorldWideView Marketplace, please visit: https://marketplace.worldwideview.dev/submit');
|
||||
console.log(`[wwv-cli] Package Name: ${publishedName}`);
|
||||
|
||||
} catch (err: any) {
|
||||
console.error('[wwv-cli] Error during publish:', err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,18 @@
|
||||
#!/usr/bin/env node
|
||||
import { Command } from 'commander';
|
||||
import { createCommand } from './commands/create.js';
|
||||
import { publishCommand } from './commands/publish.js';
|
||||
import { configCommand } from './commands/config.js';
|
||||
|
||||
const program = new Command();
|
||||
|
||||
program
|
||||
.name('wwv')
|
||||
.description('WorldWideView Plugin CLI')
|
||||
.version('1.1.2');
|
||||
|
||||
program.addCommand(createCommand);
|
||||
program.addCommand(publishCommand);
|
||||
program.addCommand(configCommand);
|
||||
|
||||
program.parse(process.argv);
|
||||
@@ -0,0 +1,27 @@
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
import os from 'os';
|
||||
|
||||
const CONFIG_PATH = path.join(os.homedir(), '.wwvrc');
|
||||
|
||||
export interface WwvConfig {
|
||||
org?: string;
|
||||
}
|
||||
|
||||
export function getConfig(): WwvConfig {
|
||||
if (!fs.existsSync(CONFIG_PATH)) {
|
||||
return {};
|
||||
}
|
||||
try {
|
||||
const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
|
||||
return JSON.parse(raw);
|
||||
} catch (e) {
|
||||
return {};
|
||||
}
|
||||
}
|
||||
|
||||
export function saveConfig(config: WwvConfig): void {
|
||||
const current = getConfig();
|
||||
const next = { ...current, ...config };
|
||||
fs.writeFileSync(CONFIG_PATH, JSON.stringify(next, null, 2), 'utf8');
|
||||
}
|
||||
Loaded 100 of 991 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user