Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
544c8e26f0 | ||
|
|
d5e4003dde |
No files matched your search
@@ -28,55 +28,14 @@ If any are missing, ask the user or tell them to run plugin-researcher first.
|
||||
|
||||
## Phase 2 — Scaffold
|
||||
|
||||
Always scaffold with the CLI, never by hand. From the project root (`C:\dev\wwv\worldwideview`).
|
||||
|
||||
**Step 1 — build the CLI if `dist/` is missing** (`dist` is gitignored, so fresh worktrees lack it):
|
||||
From the project root (`C:\dev\wwv\worldwideview`):
|
||||
|
||||
```bash
|
||||
pnpm --filter @worldwideview/wwv-cli build
|
||||
```
|
||||
|
||||
**Step 2 — run `create` non-interactively.** The CLI accepts a flag for every prompt;
|
||||
pass them all plus `--yes` so it never blocks on a prompt. Use the variant that matches
|
||||
the architecture — `--seeder-tier` is **websocket-only** (passing it with `polling` does
|
||||
nothing). Requires `@worldwideview/wwv-cli` **≥ 1.3.1** (earlier versions wrongly demanded
|
||||
`--seeder-tier` for polling under `--yes`).
|
||||
|
||||
```bash
|
||||
# Polling / static (frontend only — NO seeder, so NO --seeder-tier):
|
||||
node packages/wwv-cli/dist/index.js create <name> \
|
||||
--display-name "<Display Name>" \
|
||||
--description "<short description>" \
|
||||
--category <aviation|maritime|space|weather|custom> \
|
||||
--architecture polling \
|
||||
--render-style <billboard|model|point> \
|
||||
--yes
|
||||
|
||||
# Real-time / WebSocket (also scaffolds a backend seeder — REQUIRES --seeder-tier):
|
||||
node packages/wwv-cli/dist/index.js create <name> \
|
||||
--display-name "<Display Name>" \
|
||||
--description "<short description>" \
|
||||
--category <aviation|maritime|space|weather|custom> \
|
||||
--architecture websocket \
|
||||
--seeder-tier <community|private> \
|
||||
--render-style <billboard|model|point> \
|
||||
--yes
|
||||
|
||||
node packages/wwv-cli/dist/index.js create <name> --local
|
||||
pnpm install
|
||||
```
|
||||
|
||||
This creates `local-plugins/wwv-plugin-<name>/`. The `websocket` variant also creates the
|
||||
seeder at `local-seeders/<tier>/packages/<name>/` in the correct community/private layout
|
||||
(`package.json` + `tsup.config.ts` + `src/index.ts`, exporting `{ name, cron, fn }` with
|
||||
`name` === the plugin id). Verify the expected directories exist before proceeding.
|
||||
|
||||
> No post-CLI move is required — the CLI already targets `local-seeders/<tier>/packages/<name>/`.
|
||||
> (Pre-1.3.0 CLI dropped a bare `seeder.mjs` at `local-seeders/<tier>/<name>/`; if you ever see
|
||||
> that shape, the CLI is stale — rebuild it with the Step 1 command.)
|
||||
>
|
||||
> The CLI exits non-zero with a clear message on a bad `--category`/`--architecture`/etc., a
|
||||
> missing required value under `--yes`, or an existing target directory. Treat a non-zero exit
|
||||
> as a hard stop — fix the inputs and re-run; do not fall back to manual scaffolding.
|
||||
This creates `local-plugins/wwv-plugin-<name>/`. Verify it exists before proceeding.
|
||||
|
||||
**NEVER:**
|
||||
- Scaffold manually (always use the CLI)
|
||||
@@ -157,15 +116,13 @@ export class MyPlugin implements WorldPlugin {
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Implement the Seeder (skip for static / polling-only plugins)
|
||||
## Phase 4 — Implement the Seeder (skip for static plugins)
|
||||
|
||||
Seeders live in `local-seeders/<tier>/` — **independent git repos** (`github.com/silvertakana/wwv-seeders` for community, `wwv-seeders-private` for private). Never commit seeder files to the worldwideview repo.
|
||||
Seeders live in `local-seeders/community/` — **this is an independent git repo** (`github.com/silvertakana/wwv-seeders`). Never commit seeder files to the worldwideview repo.
|
||||
|
||||
If you scaffolded with `--architecture websocket`, **the CLI already created the seeder skeleton** at `local-seeders/<tier>/packages/<name>/` (`package.json` + `tsup.config.ts` + `src/index.ts` with a `{ name, cron, fn }` stub). Do **not** recreate those files — open the generated `src/index.ts` and replace the stub body with real fetch + map logic. The snippets below are the target shapes the CLI emits; use them to verify/adjust what was generated, not to create files from scratch.
|
||||
### Create `local-seeders/community/packages/<name>/`
|
||||
|
||||
### Generated layout: `local-seeders/<tier>/packages/<name>/`
|
||||
|
||||
**`package.json`** (CLI-generated — only adjust `dependencies` for what your seeder imports):
|
||||
**`package.json`:**
|
||||
```json
|
||||
{
|
||||
"name": "@wwv-seeders/<name>",
|
||||
|
||||
@@ -72,6 +72,23 @@ mapWebsocketPayload(payload: any, existingEntities: GeoEntity[]): GeoEntity[]
|
||||
- `existingEntities` — current entities in the store for this plugin (use for incremental updates)
|
||||
- Must return a **complete replacement** `GeoEntity[]` (not a diff)
|
||||
|
||||
### Property Tag Helpers
|
||||
|
||||
Always wrap typed property values with the SDK helpers so the Intel panel renders them richly:
|
||||
|
||||
```ts
|
||||
import { dtProp, urlProp, imageProp, videoProp } from "@worldwideview/wwv-plugin-sdk";
|
||||
|
||||
properties: {
|
||||
updated: dtProp(item.updated_at ?? null), // renders as expandable datetime row
|
||||
source: urlProp(item.source_url ?? null), // renders as clickable link
|
||||
preview: imageProp(item.image ?? null), // renders as inline thumbnail
|
||||
stream: videoProp(item.video_url ?? null), // renders as "Watch" link
|
||||
}
|
||||
```
|
||||
|
||||
All helpers are null-safe and return `null` for empty input. Plain string/number values that don't need rich rendering need no wrapper.
|
||||
|
||||
---
|
||||
|
||||
## Plugin Architectures (Manifest Formats)
|
||||
|
||||
@@ -1,161 +1,8 @@
|
||||
param([string]$worktreePath)
|
||||
|
||||
# git-wt (Worktrunk) pre-start hook.
|
||||
# Per the per-worktree isolation model, each worktree gets its OWN real, isolated
|
||||
# .planning directory -- NEVER a junction to the shared root. A shared junction caused
|
||||
# GSD phase bleed across simultaneous worktree sessions. See worktree-bootstrap SKILL Step 5
|
||||
# and C:\dev\wwv\.planning\WORKSPACE-OPTIMIZATION-BACKLOG.md.
|
||||
#
|
||||
# This hook is idempotent:
|
||||
# - existing REAL .planning with a WORKSPACE.md -> left untouched (preserve phase history)
|
||||
# - existing REAL .planning missing manifests -> manifests seeded, contents preserved
|
||||
# - existing JUNCTION (old-model leftover) -> junction removed, real dir created
|
||||
# - nothing there -> real isolated dir created
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
# Convert Unix-style path (/c/dev/...) to Windows path (C:\dev\...) if needed
|
||||
if ($worktreePath -match '^/([a-zA-Z])/(.+)$') {
|
||||
$worktreePath = $matches[1].ToUpper() + ':/' + $matches[2]
|
||||
}
|
||||
|
||||
$sharedRoot = 'C:\dev\wwv\.planning'
|
||||
$target = Join-Path $worktreePath '.planning'
|
||||
|
||||
# If a junction/symlink leftover from the old model exists, remove only the reparse
|
||||
# point (never recurse into the shared root it points at).
|
||||
if (Test-Path $target) {
|
||||
$item = Get-Item -LiteralPath $target -Force
|
||||
$isReparse = ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq [IO.FileAttributes]::ReparsePoint
|
||||
if ($isReparse) {
|
||||
[System.IO.Directory]::Delete($target, $false)
|
||||
} elseif (Test-Path (Join-Path $target 'WORKSPACE.md')) {
|
||||
# Already a fully set-up real isolated dir -- preserve it, do nothing.
|
||||
exit 0
|
||||
}
|
||||
}
|
||||
|
||||
# Resolve the branch name (fall back to the worktree folder leaf).
|
||||
$branch = $null
|
||||
try { $branch = (& git -C $worktreePath rev-parse --abbrev-ref HEAD 2>$null) } catch {}
|
||||
if (-not $branch) { $branch = Split-Path $worktreePath -Leaf }
|
||||
$branch = $branch.Trim()
|
||||
|
||||
$date = (Get-Date).ToString('yyyy-MM-dd')
|
||||
$isoDate = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.000Z')
|
||||
|
||||
# Create the isolated structure.
|
||||
foreach ($d in @('phases', 'debug', 'surveys')) {
|
||||
New-Item -ItemType Directory -Force -Path (Join-Path $target $d) | Out-Null
|
||||
}
|
||||
|
||||
# Copy the GSD config from the shared root if present.
|
||||
$sharedConfig = Join-Path $sharedRoot 'config.json'
|
||||
$localConfig = Join-Path $target 'config.json'
|
||||
if ((Test-Path $sharedConfig) -and -not (Test-Path $localConfig)) {
|
||||
Copy-Item $sharedConfig $localConfig -Force
|
||||
}
|
||||
|
||||
# Seed the three manifest files (only if missing -- never overwrite existing).
|
||||
$workspaceFile = Join-Path $target 'WORKSPACE.md'
|
||||
if (-not (Test-Path $workspaceFile)) {
|
||||
$workspace = @"
|
||||
# Workspace: $branch
|
||||
|
||||
Created: $date
|
||||
Strategy: worktree (git-wt)
|
||||
Branch: $branch
|
||||
Repo: $worktreePath
|
||||
|
||||
## Isolation
|
||||
|
||||
This ``.planning`` is a REAL, isolated directory (not a junction to the shared root).
|
||||
Phases and STATE.md here are private to this worktree. Changes do NOT bleed into
|
||||
other worktrees or the shared root. Created automatically by the git-wt pre-start
|
||||
hook (link-planning.ps1), per the per-worktree isolation model.
|
||||
|
||||
## Member Repos
|
||||
|
||||
| Repo | Source | Branch | Strategy |
|
||||
|------|--------|--------|----------|
|
||||
| worldwideview | C:\dev\wwv\worldwideview | $branch | worktree |
|
||||
|
||||
## Notes
|
||||
|
||||
Cross-feature docs are NOT duplicated here. See SHARED-DOCS.md.
|
||||
"@
|
||||
Set-Content -LiteralPath $workspaceFile -Value $workspace -Encoding UTF8
|
||||
}
|
||||
|
||||
$stateFile = Join-Path $target 'STATE.md'
|
||||
if (-not (Test-Path $stateFile)) {
|
||||
$state = @"
|
||||
---
|
||||
gsd_state_version: 1.0
|
||||
milestone: none
|
||||
milestone_name: $branch
|
||||
status: idle
|
||||
last_updated: "$isoDate"
|
||||
last_activity: $date -- isolated .planning created (git-wt pre-start hook)
|
||||
progress:
|
||||
total_phases: 0
|
||||
completed_phases: 0
|
||||
total_plans: 0
|
||||
completed_plans: 0
|
||||
percent: 0
|
||||
---
|
||||
|
||||
# Project State
|
||||
|
||||
## Project Reference
|
||||
|
||||
This is an ISOLATED worktree workspace. Its planning state is private to the
|
||||
``$branch`` worktree and intentionally distinct from the shared root
|
||||
(C:\dev\wwv\.planning).
|
||||
|
||||
Cross-feature docs (ROADMAP, MILESTONES, research) are NOT duplicated here.
|
||||
See SHARED-DOCS.md for how to reach them.
|
||||
|
||||
## Current Position
|
||||
|
||||
No active milestone. Workspace is idle.
|
||||
"@
|
||||
Set-Content -LiteralPath $stateFile -Value $state -Encoding UTF8
|
||||
}
|
||||
|
||||
$sharedDocsFile = Join-Path $target 'SHARED-DOCS.md'
|
||||
if (-not (Test-Path $sharedDocsFile)) {
|
||||
$sharedDocs = @"
|
||||
# Shared Cross-Feature Docs
|
||||
|
||||
This worktree's ``.planning`` is isolated (phases + STATE are private). But some
|
||||
documents are cross-feature and must stay authoritative in ONE place rather than
|
||||
being copied per worktree (copies drift out of sync).
|
||||
|
||||
## Where they live
|
||||
|
||||
Shared root: ``C:\dev\wwv\.planning``
|
||||
|
||||
| Doc | Purpose |
|
||||
|-----|---------|
|
||||
| ROADMAP.md | Cross-milestone roadmap |
|
||||
| MILESTONES.md | Milestone definitions and ship status |
|
||||
| research/ | ARCHITECTURE / FEATURES / PITFALLS / STACK |
|
||||
| PROJECT.md | Project identity |
|
||||
| REQUIREMENTS.md | Cross-cutting requirements |
|
||||
|
||||
## How to reach them
|
||||
|
||||
A ``WWV_SHARED_PLANNING`` env var in each worktree's ``.env.local`` points at the
|
||||
shared root, and GSD skills that need a cross-feature doc read
|
||||
``\$WWV_SHARED_PLANNING/<doc>`` instead of the local ``.planning/<doc>``.
|
||||
|
||||
Do NOT copy these docs into this worktree. Single source of truth lives at the
|
||||
shared root.
|
||||
"@
|
||||
Set-Content -LiteralPath $sharedDocsFile -Value $sharedDocs -Encoding UTF8
|
||||
}
|
||||
|
||||
# Always report success: the internal git probe above may set a non-zero $LASTEXITCODE,
|
||||
# which would otherwise be propagated as this hook's exit code and read as a failure.
|
||||
exit 0
|
||||
if (Test-Path $target) { Remove-Item $target -Force }
|
||||
New-Item -ItemType Junction -Path $target -Target 'C:\dev\wwv\.planning' | Out-Null
|
||||
@@ -1,29 +1,7 @@
|
||||
param([string]$worktreePath)
|
||||
|
||||
# git-wt (Worktrunk) pre-remove hook.
|
||||
# Per the per-worktree isolation model, a worktree's .planning is a REAL isolated
|
||||
# directory (its phase history is archived by /branch-cleanup before removal, and the
|
||||
# directory itself is deleted along with the worktree by `git-wt remove`).
|
||||
#
|
||||
# This hook therefore ONLY cleans up a leftover JUNCTION from the old shared-link model.
|
||||
# It must NEVER recursively delete a real .planning directory -- doing so would destroy
|
||||
# phase history that /branch-cleanup is responsible for archiving.
|
||||
|
||||
# Convert Unix-style path (/c/dev/...) to Windows path (C:\dev\...) if needed
|
||||
if ($worktreePath -match '^/([a-zA-Z])/(.+)$') {
|
||||
$worktreePath = $matches[1].ToUpper() + ':/' + $matches[2]
|
||||
}
|
||||
$target = Join-Path $worktreePath '.planning'
|
||||
|
||||
if (Test-Path $target) {
|
||||
$item = Get-Item -LiteralPath $target -Force
|
||||
$isReparse = ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq [IO.FileAttributes]::ReparsePoint
|
||||
if ($isReparse) {
|
||||
# Old-model junction: remove only the reparse point (do not follow into the target).
|
||||
[System.IO.Directory]::Delete($target, $false)
|
||||
}
|
||||
# Real directory: leave it. git-wt remove deletes the worktree (and this dir) anyway;
|
||||
# /branch-cleanup is responsible for archiving its phase history first.
|
||||
}
|
||||
|
||||
exit 0
|
||||
if (Test-Path $target) { Remove-Item $target -Force }
|
||||
@@ -202,7 +202,40 @@ import { Plane } from "lucide-react";
|
||||
const iconUrl = createSvgIconUrl(Plane, { color: "#3b82f6" });
|
||||
```
|
||||
|
||||
### 1.5 Registration (3 Paths)
|
||||
### 1.5 Property Tag Helpers
|
||||
|
||||
Use these SDK helpers to wrap property values so the Intel panel renders them richly. Without the tag prefix, the panel falls back to plain text.
|
||||
|
||||
```ts
|
||||
import { dtProp, urlProp, imageProp, videoProp } from "@worldwideview/wwv-plugin-sdk";
|
||||
```
|
||||
|
||||
| Helper | Tag format stored | Panel renders as |
|
||||
|---|---|---|
|
||||
| `dtProp(iso)` | `"datetime:2026-06-01T05:00:00Z"` | Expandable row: local time (collapsed), UTC + relative (expanded) |
|
||||
| `urlProp(href)` | `"url:https://..."` | Clickable link with external icon |
|
||||
| `imageProp(src)` | `"image:https://..."` | Inline thumbnail |
|
||||
| `videoProp(href)` | `"video:https://..."` | "Watch" link with play icon |
|
||||
|
||||
All four helpers return `null` for empty, `null`, or `undefined` input — safe to call unconditionally.
|
||||
|
||||
**Usage pattern:**
|
||||
```ts
|
||||
properties: {
|
||||
// dates — pass ISO 8601 strings
|
||||
updated_at: dtProp(item.updated_at ?? null),
|
||||
// URLs
|
||||
source_url: urlProp(item.url ?? null),
|
||||
// images and video
|
||||
preview: imageProp(item.image_url ?? null),
|
||||
stream: videoProp(item.video_url ?? null),
|
||||
// plain values — no helper needed
|
||||
name: item.name,
|
||||
count: item.count,
|
||||
}
|
||||
```
|
||||
|
||||
### 1.6 Registration (3 Paths)
|
||||
|
||||
**A. Built-in (monorepo package):**
|
||||
|
||||
@@ -224,7 +257,7 @@ await pluginManager.registerPlugin(plugin);
|
||||
**C. Dynamic import (runtime):**
|
||||
For user-imported GeoJSON layers, call `pluginManager.loadFromManifest(manifest)` directly.
|
||||
|
||||
### 1.6 Build Configuration (Core Monorepo Packages Only)
|
||||
### 1.7 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:
|
||||
|
||||
@@ -652,6 +685,10 @@ Categories are **lowercase**: `"aviation"` not `"Aviation"`, `"natural-disaster"
|
||||
- [ ] **Frontend:** Added path alias in `tsconfig.json`
|
||||
- [ ] **Frontend:** Registered via `pluginRegistry` + `pluginManager` in `AppShell.tsx`
|
||||
- [ ] **Frontend:** `renderEntity()` doesn't mix point/billboard properties
|
||||
- [ ] **Frontend:** Date/time fields wrapped with `dtProp()`
|
||||
- [ ] **Frontend:** External links wrapped with `urlProp()`
|
||||
- [ ] **Frontend:** Image URLs wrapped with `imageProp()`
|
||||
- [ ] **Frontend:** Video/stream URLs wrapped with `videoProp()`
|
||||
- [ ] **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
|
||||
|
||||
@@ -1,15 +1,10 @@
|
||||
name: CI
|
||||
|
||||
# CLI-only changes are covered by cli.yml; skip the full app suite for them.
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths-ignore:
|
||||
- "packages/wwv-cli/**"
|
||||
pull_request:
|
||||
branches: [main]
|
||||
paths-ignore:
|
||||
- "packages/wwv-cli/**"
|
||||
|
||||
jobs:
|
||||
# Non-blocking dependency audit. Surfaces high / critical vulnerabilities
|
||||
|
||||
@@ -1,36 +0,0 @@
|
||||
name: CLI
|
||||
|
||||
# Scoped to the plugin CLI package only. Heavy app workflows (ci.yml,
|
||||
# playwright.yml, docker-publish.yml, ...) exclude this path, so a CLI-only
|
||||
# change runs just this fast build + test instead of the full suite.
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- "packages/wwv-cli/**"
|
||||
- ".github/workflows/cli.yml"
|
||||
pull_request:
|
||||
branches: [main]
|
||||
paths:
|
||||
- "packages/wwv-cli/**"
|
||||
- ".github/workflows/cli.yml"
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
build-and-test:
|
||||
name: Build & Test CLI
|
||||
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
|
||||
# `build` runs tsc — this also type-checks the CLI source.
|
||||
- run: pnpm --filter @worldwideview/wwv-cli build
|
||||
# Integration tests spawn the built CLI and assert the scaffolded tree.
|
||||
- run: pnpm --filter @worldwideview/wwv-cli test
|
||||
@@ -1,15 +1,10 @@
|
||||
name: Docker Image CI
|
||||
|
||||
# CLI-only changes are covered by cli.yml; skip the image build for them.
|
||||
on:
|
||||
push:
|
||||
branches: [ "main" ]
|
||||
paths-ignore:
|
||||
- "packages/wwv-cli/**"
|
||||
pull_request:
|
||||
branches: [ "main" ]
|
||||
paths-ignore:
|
||||
- "packages/wwv-cli/**"
|
||||
|
||||
env:
|
||||
REGISTRY: ghcr.io
|
||||
|
||||
@@ -1,14 +1,9 @@
|
||||
name: Playwright Tests
|
||||
# CLI-only changes are covered by cli.yml; skip browser E2E for them.
|
||||
on:
|
||||
push:
|
||||
branches: [ main, master ]
|
||||
paths-ignore:
|
||||
- "packages/wwv-cli/**"
|
||||
pull_request:
|
||||
branches: [ main, master ]
|
||||
paths-ignore:
|
||||
- "packages/wwv-cli/**"
|
||||
permissions:
|
||||
contents: read
|
||||
jobs:
|
||||
|
||||
@@ -3,8 +3,6 @@ name: Test Local Dev Environment
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths-ignore:
|
||||
- "packages/wwv-cli/**"
|
||||
pull_request:
|
||||
branches: [main]
|
||||
paths:
|
||||
|
||||
@@ -1,15 +1,10 @@
|
||||
name: Test Setup Scripts
|
||||
|
||||
# CLI-only changes are covered by cli.yml; skip setup-script tests for them.
|
||||
on:
|
||||
push:
|
||||
branches: [ "main" ]
|
||||
paths-ignore:
|
||||
- "packages/wwv-cli/**"
|
||||
pull_request:
|
||||
branches: [ "main" ]
|
||||
paths-ignore:
|
||||
- "packages/wwv-cli/**"
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "worldwideview",
|
||||
"version": "2.24.5",
|
||||
"version": "2.25.1",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"packageManager": "[email protected]",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@worldwideview/wwv-cli",
|
||||
"version": "1.3.1",
|
||||
"version": "1.2.0",
|
||||
"type": "module",
|
||||
"description": "WorldWideView CLI",
|
||||
"main": "dist/index.js",
|
||||
@@ -10,8 +10,7 @@
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"dev": "tsc --watch",
|
||||
"clean": "rm -rf dist",
|
||||
"test": "node --test \"test/**/*.test.mjs\""
|
||||
"clean": "rm -rf dist"
|
||||
},
|
||||
"dependencies": {
|
||||
"commander": "^14.0.3",
|
||||
|
||||
@@ -4,74 +4,29 @@ import fs from 'fs';
|
||||
import path from 'path';
|
||||
import prompts from 'prompts';
|
||||
|
||||
const VALID_CATEGORIES = ['aviation', 'maritime', 'space', 'weather', 'custom'];
|
||||
const VALID_ARCHITECTURES = ['polling', 'websocket'];
|
||||
const VALID_SEEDER_TIERS = ['community', 'private'];
|
||||
const VALID_RENDER_STYLES = ['billboard', 'model', 'point'];
|
||||
|
||||
interface CreateOptions {
|
||||
core?: boolean;
|
||||
displayName?: string;
|
||||
description?: string;
|
||||
category?: string;
|
||||
architecture?: string;
|
||||
seederTier?: string;
|
||||
renderStyle?: string;
|
||||
yes?: boolean;
|
||||
}
|
||||
|
||||
function assertChoice(label: string, value: string | undefined, valid: string[]): void {
|
||||
if (value !== undefined && !valid.includes(value)) {
|
||||
console.error(`Error: invalid --${label} "${value}". Valid values: ${valid.join(', ')}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
export const createCommand = new Command('create')
|
||||
.description('Scaffold a new WorldWideView plugin (flags skip the matching prompt; omit them for interactive mode)')
|
||||
.argument('[pluginId]', 'Unique kebab-case plugin ID (e.g. my-tracker)')
|
||||
.description('Interactively scaffold a new WorldWideView plugin')
|
||||
.option('-c, --core', 'Create inside packages instead of local-plugins (for core contributors)')
|
||||
.option('-n, --display-name <name>', 'Display name (e.g. "My Live Tracker")')
|
||||
.option('-d, --description <text>', 'Short description')
|
||||
.option('--category <category>', `One of: ${VALID_CATEGORIES.join(', ')}`)
|
||||
.option('--architecture <architecture>', `One of: ${VALID_ARCHITECTURES.join(', ')}`)
|
||||
.option('--seeder-tier <tier>', `One of: ${VALID_SEEDER_TIERS.join(', ')} (websocket only)`)
|
||||
.option('--render-style <style>', `One of: ${VALID_RENDER_STYLES.join(', ')}`)
|
||||
.option('-y, --yes', 'Non-interactive: fail instead of prompting for missing values')
|
||||
.action(async (pluginIdArg: string | undefined, options: CreateOptions) => {
|
||||
// Validate any flags supplied up front so we fail fast and consistently.
|
||||
assertChoice('category', options.category, VALID_CATEGORIES);
|
||||
assertChoice('architecture', options.architecture, VALID_ARCHITECTURES);
|
||||
assertChoice('seeder-tier', options.seederTier, VALID_SEEDER_TIERS);
|
||||
assertChoice('render-style', options.renderStyle, VALID_RENDER_STYLES);
|
||||
|
||||
// Build the prompt list, skipping any value already supplied via flag/arg.
|
||||
// In --yes mode we never prompt; missing required values are an error.
|
||||
const promptList: prompts.PromptObject[] = [];
|
||||
|
||||
if (!pluginIdArg) {
|
||||
promptList.push({
|
||||
.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',
|
||||
});
|
||||
}
|
||||
if (options.displayName === undefined) {
|
||||
promptList.push({
|
||||
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: pluginIdArg
|
||||
? pluginIdArg.replace(/-/g, ' ').replace(/\b\w/g, (l: string) => l.toUpperCase())
|
||||
: undefined,
|
||||
});
|
||||
}
|
||||
if (options.description === undefined) {
|
||||
promptList.push({ type: 'text', name: 'description', message: 'Enter a short description:' });
|
||||
}
|
||||
if (options.category === undefined) {
|
||||
promptList.push({
|
||||
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?',
|
||||
@@ -80,78 +35,46 @@ export const createCommand = new Command('create')
|
||||
{ title: 'Maritime (Ship icon)', value: 'maritime' },
|
||||
{ title: 'Space (Satellite icon)', value: 'space' },
|
||||
{ title: 'Weather (Cloud icon)', value: 'weather' },
|
||||
{ title: 'Custom (Box icon)', value: 'custom' },
|
||||
],
|
||||
});
|
||||
}
|
||||
if (options.architecture === undefined) {
|
||||
promptList.push({
|
||||
{ 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' },
|
||||
],
|
||||
});
|
||||
}
|
||||
if (options.seederTier === undefined) {
|
||||
promptList.push({
|
||||
// Only ask about seeder tier when architecture resolves to websocket.
|
||||
type: (_prev, values) => {
|
||||
const arch = options.architecture ?? values.architecture;
|
||||
return arch === 'websocket' ? 'select' : null;
|
||||
},
|
||||
{ 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' },
|
||||
],
|
||||
});
|
||||
}
|
||||
if (options.renderStyle === undefined) {
|
||||
promptList.push({
|
||||
{ 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 (options.yes && promptList.length > 0) {
|
||||
// Only count prompts that would actually fire. seederTier is irrelevant
|
||||
// unless the resolved architecture is websocket, so a polling plugin with
|
||||
// --yes must not be forced to supply it.
|
||||
const missing = promptList
|
||||
.map(p => p.name as string)
|
||||
.filter(name => (name === 'seederTier' ? options.architecture === 'websocket' : true));
|
||||
if (missing.length > 0) {
|
||||
console.error(`Error: --yes given but these required values are missing: ${missing.join(', ')}`);
|
||||
process.exit(1);
|
||||
{ title: 'Simple Point (High performance dots)', value: 'point' }
|
||||
]
|
||||
}
|
||||
}
|
||||
]);
|
||||
|
||||
const answers = promptList.length > 0 ? await prompts(promptList) : {};
|
||||
|
||||
// Merge flags/args (authoritative) over interactive answers.
|
||||
const pluginId: string | undefined = pluginIdArg ?? answers.pluginId;
|
||||
const displayName: string = options.displayName ?? answers.displayName ?? '';
|
||||
const description: string = options.description ?? answers.description ?? '';
|
||||
const category: string = options.category ?? answers.category;
|
||||
const architecture: string = options.architecture ?? answers.architecture;
|
||||
const seederTier: string | undefined = options.seederTier ?? answers.seederTier;
|
||||
const renderStyle: string = options.renderStyle ?? answers.renderStyle;
|
||||
|
||||
if (!pluginId) {
|
||||
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}`);
|
||||
|
||||
@@ -162,19 +85,21 @@ export const createCommand = new Command('create')
|
||||
|
||||
fs.mkdirSync(pluginDir, { recursive: true });
|
||||
|
||||
// Determine category icon
|
||||
const iconMap: Record<string, string> = {
|
||||
aviation: 'Plane',
|
||||
maritime: 'Ship',
|
||||
space: 'Satellite',
|
||||
weather: 'Cloud',
|
||||
custom: 'Box',
|
||||
custom: 'Box'
|
||||
};
|
||||
const defaultIcon = iconMap[category] || 'Box';
|
||||
|
||||
const streamUrlField = architecture === 'websocket'
|
||||
? `\n "streamUrl": "wss://dataenginev2.worldwideview.dev/stream",`
|
||||
// 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",
|
||||
@@ -206,6 +131,7 @@ export const createCommand = new Command('create')
|
||||
}
|
||||
`;
|
||||
|
||||
// index.ts boilerplate
|
||||
const renderBoilerplate = {
|
||||
billboard: `return {
|
||||
type: 'billboard',
|
||||
@@ -226,14 +152,14 @@ export const createCommand = new Command('create')
|
||||
size: 8,
|
||||
outlineColor: '#ffffff',
|
||||
outlineWidth: 2
|
||||
};`,
|
||||
};`
|
||||
}[renderStyle as string] || `return {};`;
|
||||
|
||||
const fetchBoilerplate = architecture === 'polling'
|
||||
const fetchBoilerplate = architecture === 'polling'
|
||||
? `\n async fetch(): Promise<GeoEntity[]> {
|
||||
// Implement REST polling logic here
|
||||
return [];
|
||||
}\n`
|
||||
}\n`
|
||||
: '';
|
||||
|
||||
const indexTsContent = `import { WorldPlugin, GeoEntity, CesiumEntityOptions } from '@worldwideview/wwv-plugin-sdk';
|
||||
@@ -269,75 +195,41 @@ ${fetchBoilerplate}
|
||||
|
||||
console.log(`\n✅ Successfully created plugin frontend at ${pluginDir}`);
|
||||
|
||||
// Generate seeder backend if requested. Matches the real community/private
|
||||
// seeder layout: local-seeders/<tier>/packages/<pluginId>/ with a tsup build
|
||||
// and a src/index.ts that exports the canonical { name, cron, fn } shape.
|
||||
// Generate seeder backend if requested
|
||||
if (architecture === 'websocket' && seederTier) {
|
||||
const seederDir = path.join(process.cwd(), 'local-seeders', seederTier, 'packages', pluginId);
|
||||
|
||||
if (fs.existsSync(seederDir)) {
|
||||
console.error(`Warning: Seeder directory ${seederDir} already exists. Skipping seeder scaffold.`);
|
||||
} else {
|
||||
fs.mkdirSync(path.join(seederDir, 'src'), { recursive: true });
|
||||
|
||||
const seederPackageJson = `{
|
||||
"name": "@wwv-seeders/${pluginId}",
|
||||
"version": "1.0.0",
|
||||
"main": "dist/index.mjs",
|
||||
"scripts": {
|
||||
"build": "tsup"
|
||||
},
|
||||
"dependencies": {
|
||||
"@worldwideview/seeder-sdk": "^1.0.0"
|
||||
}
|
||||
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);
|
||||
}
|
||||
`;
|
||||
|
||||
const tsupConfig = `import { defineConfig } from 'tsup';
|
||||
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
format: ['esm'],
|
||||
clean: true,
|
||||
shims: true,
|
||||
noExternal: [/@wwv-seeders\\/.*/],
|
||||
external: [/^(?!@wwv-seeders)[a-z@].*/],
|
||||
});
|
||||
`;
|
||||
|
||||
// The seeder's exported `name` MUST equal the frontend plugin id
|
||||
// (kebab-case). See ADR-0002 / data-engine-architecture.md section 6.
|
||||
const seederIndexTs = `import { setLiveSnapshot, fetchWithTimeout, withRetry } from '@worldwideview/seeder-sdk';
|
||||
|
||||
async function seed${pluginId.replace(/-/g, '')}() {
|
||||
// TODO: fetch from the real data source and map into GeoEntity-shaped items.
|
||||
const items: Array<{ id: string; lat: number; lon: number; name: string }> = [];
|
||||
|
||||
await setLiveSnapshot('${pluginId}', {
|
||||
source: '${pluginId}',
|
||||
fetchedAt: new Date().toISOString(),
|
||||
items,
|
||||
totalCount: items.length,
|
||||
}, 3600);
|
||||
}
|
||||
|
||||
export default {
|
||||
name: '${pluginId}', // MUST match the frontend plugin id exactly (kebab-case)
|
||||
cron: '*/15 * * * *',
|
||||
fn: seed${pluginId.replace(/-/g, '')},
|
||||
};
|
||||
`;
|
||||
|
||||
fs.writeFileSync(path.join(seederDir, 'package.json'), seederPackageJson);
|
||||
fs.writeFileSync(path.join(seederDir, 'tsup.config.ts'), tsupConfig);
|
||||
fs.writeFileSync(path.join(seederDir, 'src', 'index.ts'), seederIndexTs);
|
||||
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 \`src/index.ts\` in your plugin directory.
|
||||
${architecture === 'websocket' && seederTier ? `3. Edit \`src/index.ts\` in local-seeders/${seederTier}/packages/${pluginId}/, then \`pnpm build\` it.` : ''}
|
||||
2. Edit \`index.ts\` in your plugin directory.
|
||||
${architecture === 'websocket' ? '3. Edit `seeder.mjs` in your local-seeders directory.' : ''}
|
||||
`);
|
||||
});
|
||||
@@ -9,7 +9,7 @@ const program = new Command();
|
||||
program
|
||||
.name('wwv')
|
||||
.description('WorldWideView Plugin CLI')
|
||||
.version('1.3.1');
|
||||
.version('1.1.2');
|
||||
|
||||
program.addCommand(createCommand);
|
||||
program.addCommand(publishCommand);
|
||||
|
||||
@@ -1,219 +0,0 @@
|
||||
// Integration tests for `wwv create`.
|
||||
//
|
||||
// These spawn the *built* CLI (dist/index.js) into a throwaway temp directory
|
||||
// and assert the generated file tree. No mocking — this is the real scaffold
|
||||
// path agents and humans use. Run with: `node --test test/` (the CLI must be
|
||||
// built first; the cli.yml workflow runs `pnpm build` before this).
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import { mkdtempSync, readFileSync, existsSync, rmSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join, resolve } from 'node:path';
|
||||
|
||||
const CLI = resolve(import.meta.dirname, '..', 'dist', 'index.js');
|
||||
|
||||
function freshDir() {
|
||||
return mkdtempSync(join(tmpdir(), 'wwv-cli-test-'));
|
||||
}
|
||||
|
||||
function runCreate(cwd, args) {
|
||||
const res = spawnSync(process.execPath, [CLI, 'create', ...args], {
|
||||
cwd,
|
||||
encoding: 'utf8',
|
||||
// Empty stdin so a stray prompt (a bug) fails fast instead of hanging CI.
|
||||
input: '',
|
||||
});
|
||||
return { status: res.status, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
|
||||
}
|
||||
|
||||
function readPkg(dir, ...segments) {
|
||||
return JSON.parse(readFileSync(join(dir, ...segments), 'utf8'));
|
||||
}
|
||||
|
||||
function readText(dir, ...segments) {
|
||||
return readFileSync(join(dir, ...segments), 'utf8');
|
||||
}
|
||||
|
||||
// --- Happy-path plugin types -------------------------------------------------
|
||||
|
||||
test('polling plugin: frontend only, no seeder, no streamUrl, has fetch()', () => {
|
||||
const dir = freshDir();
|
||||
try {
|
||||
const r = runCreate(dir, [
|
||||
'poll-test', '-n', 'Poll Test', '-d', 'A polling plugin',
|
||||
'--category', 'custom', '--architecture', 'polling', '--render-style', 'point', '--yes',
|
||||
]);
|
||||
assert.equal(r.status, 0, r.stderr);
|
||||
|
||||
const pkg = readPkg(dir, 'local-plugins', 'wwv-plugin-poll-test', 'package.json');
|
||||
assert.equal(pkg.name, '@worldwideview/wwv-plugin-poll-test');
|
||||
assert.equal(pkg.worldwideview.pluginId, 'poll-test');
|
||||
assert.equal(pkg.worldwideview.category, 'custom');
|
||||
assert.equal(pkg.worldwideview.streamUrl, undefined, 'polling plugin must not declare streamUrl');
|
||||
|
||||
const idx = readText(dir, 'local-plugins', 'wwv-plugin-poll-test', 'src', 'index.ts');
|
||||
assert.match(idx, /id = 'poll-test'/);
|
||||
assert.match(idx, /getPollingInterval\(\): number \{\s*return 10000/);
|
||||
assert.match(idx, /async fetch\(/);
|
||||
assert.match(idx, /type: 'point'/);
|
||||
|
||||
assert.ok(!existsSync(join(dir, 'local-seeders')), 'polling plugin must not scaffold a seeder');
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test('websocket + community + billboard: seeder under community/packages, streamUrl, Plane icon', () => {
|
||||
const dir = freshDir();
|
||||
try {
|
||||
const r = runCreate(dir, [
|
||||
'ws-comm', '-n', 'WS Comm', '-d', 'desc',
|
||||
'--category', 'aviation', '--architecture', 'websocket', '--seeder-tier', 'community',
|
||||
'--render-style', 'billboard', '--yes',
|
||||
]);
|
||||
assert.equal(r.status, 0, r.stderr);
|
||||
|
||||
const pkg = readPkg(dir, 'local-plugins', 'wwv-plugin-ws-comm', 'package.json');
|
||||
assert.equal(pkg.worldwideview.icon, 'Plane');
|
||||
assert.ok(pkg.worldwideview.streamUrl, 'websocket plugin must declare a streamUrl');
|
||||
|
||||
const seederBase = join(dir, 'local-seeders', 'community', 'packages', 'ws-comm');
|
||||
assert.ok(existsSync(join(seederBase, 'package.json')), 'seeder package.json missing');
|
||||
assert.ok(existsSync(join(seederBase, 'tsup.config.ts')), 'seeder tsup.config.ts missing');
|
||||
|
||||
const seederPkg = readPkg(dir, 'local-seeders', 'community', 'packages', 'ws-comm', 'package.json');
|
||||
assert.equal(seederPkg.name, '@wwv-seeders/ws-comm');
|
||||
assert.equal(seederPkg.main, 'dist/index.mjs');
|
||||
|
||||
const seederIdx = readText(dir, 'local-seeders', 'community', 'packages', 'ws-comm', 'src', 'index.ts');
|
||||
assert.match(seederIdx, /name: 'ws-comm'/, "seeder name must equal the plugin id (ADR-0002)");
|
||||
assert.match(seederIdx, /cron:/);
|
||||
|
||||
const idx = readText(dir, 'local-plugins', 'wwv-plugin-ws-comm', 'src', 'index.ts');
|
||||
assert.match(idx, /getPollingInterval\(\): number \{\s*return 0;/);
|
||||
assert.match(idx, /type: 'billboard'/);
|
||||
assert.doesNotMatch(idx, /async fetch\(/, 'websocket plugin should not generate a fetch() stub');
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test('websocket + private + model: seeder under private/packages, Satellite icon, model render', () => {
|
||||
const dir = freshDir();
|
||||
try {
|
||||
const r = runCreate(dir, [
|
||||
'ws-priv', '-n', 'WS Priv', '-d', 'desc',
|
||||
'--category', 'space', '--architecture', 'websocket', '--seeder-tier', 'private',
|
||||
'--render-style', 'model', '--yes',
|
||||
]);
|
||||
assert.equal(r.status, 0, r.stderr);
|
||||
|
||||
assert.ok(
|
||||
existsSync(join(dir, 'local-seeders', 'private', 'packages', 'ws-priv', 'src', 'index.ts')),
|
||||
'private seeder must land under local-seeders/private/packages/',
|
||||
);
|
||||
const pkg = readPkg(dir, 'local-plugins', 'wwv-plugin-ws-priv', 'package.json');
|
||||
assert.equal(pkg.worldwideview.icon, 'Satellite');
|
||||
|
||||
const idx = readText(dir, 'local-plugins', 'wwv-plugin-ws-priv', 'src', 'index.ts');
|
||||
assert.match(idx, /modelUrl/, 'model render style should reference modelUrl');
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test('--core flag scaffolds into packages/ instead of local-plugins/', () => {
|
||||
const dir = freshDir();
|
||||
try {
|
||||
const r = runCreate(dir, [
|
||||
'core-test', '--core', '-n', 'Core', '-d', 'desc',
|
||||
'--category', 'custom', '--architecture', 'polling', '--render-style', 'point', '--yes',
|
||||
]);
|
||||
assert.equal(r.status, 0, r.stderr);
|
||||
assert.ok(existsSync(join(dir, 'packages', 'wwv-plugin-core-test', 'package.json')));
|
||||
assert.ok(!existsSync(join(dir, 'local-plugins', 'wwv-plugin-core-test')));
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test('multi-word id: kebab id preserved, class and seeder fn names strip dashes', () => {
|
||||
const dir = freshDir();
|
||||
try {
|
||||
const r = runCreate(dir, [
|
||||
'multi-word-plugin', '-n', 'Multi Word', '-d', 'desc',
|
||||
'--category', 'custom', '--architecture', 'websocket', '--seeder-tier', 'community',
|
||||
'--render-style', 'point', '--yes',
|
||||
]);
|
||||
assert.equal(r.status, 0, r.stderr);
|
||||
|
||||
const idx = readText(dir, 'local-plugins', 'wwv-plugin-multi-word-plugin', 'src', 'index.ts');
|
||||
assert.match(idx, /class multiwordpluginPlugin/);
|
||||
assert.match(idx, /id = 'multi-word-plugin'/);
|
||||
|
||||
const seederIdx = readText(dir, 'local-seeders', 'community', 'packages', 'multi-word-plugin', 'src', 'index.ts');
|
||||
assert.match(seederIdx, /name: 'multi-word-plugin'/);
|
||||
assert.match(seederIdx, /function seedmultiwordplugin\(/);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test('category icon mapping: maritime -> Ship, weather -> Cloud', () => {
|
||||
const dir = freshDir();
|
||||
try {
|
||||
const base = ['-d', 'desc', '--architecture', 'polling', '--render-style', 'point', '--yes'];
|
||||
assert.equal(runCreate(dir, ['sea', '-n', 'Sea', '--category', 'maritime', ...base]).status, 0);
|
||||
assert.equal(runCreate(dir, ['sky', '-n', 'Sky', '--category', 'weather', ...base]).status, 0);
|
||||
|
||||
assert.equal(readPkg(dir, 'local-plugins', 'wwv-plugin-sea', 'package.json').worldwideview.icon, 'Ship');
|
||||
assert.equal(readPkg(dir, 'local-plugins', 'wwv-plugin-sky', 'package.json').worldwideview.icon, 'Cloud');
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
// --- Failure / guard cases ---------------------------------------------------
|
||||
|
||||
test('--yes with a missing required value exits non-zero and creates nothing', () => {
|
||||
const dir = freshDir();
|
||||
try {
|
||||
const r = runCreate(dir, ['fail-test', '--architecture', 'websocket', '--yes']);
|
||||
assert.notEqual(r.status, 0, 'should fail when required values are missing');
|
||||
assert.match(r.stderr, /missing/i);
|
||||
assert.ok(!existsSync(join(dir, 'local-plugins', 'wwv-plugin-fail-test')), 'must not create a partial scaffold');
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test('invalid --category exits non-zero with a clear message', () => {
|
||||
const dir = freshDir();
|
||||
try {
|
||||
const r = runCreate(dir, [
|
||||
'bad-cat', '-n', 'x', '-d', 'y', '--category', 'nonsense',
|
||||
'--architecture', 'polling', '--render-style', 'point', '--yes',
|
||||
]);
|
||||
assert.notEqual(r.status, 0);
|
||||
assert.match(r.stderr, /invalid --category/i);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test('creating into an existing plugin directory exits non-zero', () => {
|
||||
const dir = freshDir();
|
||||
try {
|
||||
const args = [
|
||||
'dup-test', '-n', 'x', '-d', 'y', '--category', 'custom',
|
||||
'--architecture', 'polling', '--render-style', 'point', '--yes',
|
||||
];
|
||||
assert.equal(runCreate(dir, args).status, 0);
|
||||
const second = runCreate(dir, args);
|
||||
assert.notEqual(second.status, 0);
|
||||
assert.match(second.stderr, /already exists/i);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
@@ -52,6 +52,38 @@ export class MyPlugin implements WorldPlugin {
|
||||
}
|
||||
```
|
||||
|
||||
## Property Tag Helpers
|
||||
|
||||
Wrap entity property values with these helpers so the WorldWideView Intel panel renders them as rich UI elements instead of plain text.
|
||||
|
||||
```ts
|
||||
import { dtProp, urlProp, imageProp, videoProp } from "@worldwideview/wwv-plugin-sdk";
|
||||
```
|
||||
|
||||
| Helper | Wraps | Panel renders as |
|
||||
|---|---|---|
|
||||
| `dtProp(iso: string \| null)` | ISO 8601 date string | Expandable datetime row — local time collapsed, UTC + relative time expanded |
|
||||
| `urlProp(href: string \| null)` | Any URL | Clickable link with external-link icon |
|
||||
| `imageProp(src: string \| null)` | Image URL | Inline thumbnail |
|
||||
| `videoProp(href: string \| null)` | Video/stream URL | "Watch" link with play icon |
|
||||
|
||||
All helpers are **null-safe**: passing `null`, `undefined`, or `""` returns `null`, which the panel skips cleanly.
|
||||
|
||||
```ts
|
||||
// In your entity mapper:
|
||||
properties: {
|
||||
last_seen: dtProp(item.timestamp ?? null),
|
||||
source_url: urlProp(item.url ?? null),
|
||||
preview: imageProp(item.image_url ?? null),
|
||||
live_stream: videoProp(item.stream ?? null),
|
||||
// Plain values need no wrapper
|
||||
name: item.name,
|
||||
severity: item.severity,
|
||||
}
|
||||
```
|
||||
|
||||
Values without a tag prefix fall back to plain-text rendering, so existing plugins continue to work unchanged.
|
||||
|
||||
## Changelog
|
||||
|
||||
- **v1.0.3** — Added README with core interfaces and usage docs.
|
||||
|
||||
@@ -313,3 +313,45 @@ export * from "./viteGlobals";
|
||||
|
||||
// ─── Auth Contracts ──────────────────────────────────────────
|
||||
export * from "./auth-contracts";
|
||||
|
||||
// ─── Tagged Property Helpers ─────────────────────────────────
|
||||
/**
|
||||
* Wraps an ISO 8601 date string for rich rendering in the Intel panel.
|
||||
* The panel displays local time (collapsed) and UTC + relative time (expanded).
|
||||
* @param iso - ISO 8601 string (e.g. "2026-06-01T05:00:00Z"), or null/undefined
|
||||
* @returns Tagged string `"datetime:{iso}"`, or `null` if input is empty
|
||||
*/
|
||||
export function dtProp(iso: string | undefined | null): string | null {
|
||||
if (!iso) return null;
|
||||
return `datetime:${iso}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Wraps a URL for rich rendering in the Intel panel as a clickable external link.
|
||||
* @param href - Any URL string, or null/undefined
|
||||
* @returns Tagged string `"url:{href}"`, or `null` if input is empty
|
||||
*/
|
||||
export function urlProp(href: string | undefined | null): string | null {
|
||||
if (!href) return null;
|
||||
return `url:${href}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Wraps an image URL for rich rendering in the Intel panel as an inline thumbnail.
|
||||
* @param src - Image URL string, or null/undefined
|
||||
* @returns Tagged string `"image:{src}"`, or `null` if input is empty
|
||||
*/
|
||||
export function imageProp(src: string | undefined | null): string | null {
|
||||
if (!src) return null;
|
||||
return `image:${src}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Wraps a video or stream URL for rich rendering in the Intel panel as a "Watch" link.
|
||||
* @param href - Video or stream URL string, or null/undefined
|
||||
* @returns Tagged string `"video:{href}"`, or `null` if input is empty
|
||||
*/
|
||||
export function videoProp(href: string | undefined | null): string | null {
|
||||
if (!href) return null;
|
||||
return `video:${href}`;
|
||||
}
|
||||
Generated
+1149
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,66 @@
|
||||
import { useState } from "react";
|
||||
import { IntelPropertyRow } from "./IntelPropertyRow";
|
||||
|
||||
function formatLocal(iso: string): string {
|
||||
return new Date(iso).toLocaleString(undefined, {
|
||||
day: "numeric", month: "2-digit", year: "numeric",
|
||||
hour: "numeric", minute: "2-digit", hour12: true, timeZoneName: "short",
|
||||
});
|
||||
}
|
||||
|
||||
function formatUtc(iso: string): string {
|
||||
return new Date(iso).toISOString().slice(0, 16).replace("T", " ") + " UTC";
|
||||
}
|
||||
|
||||
function formatRelative(iso: string): string {
|
||||
const diff = new Date(iso).getTime() - Date.now();
|
||||
const abs = Math.abs(diff);
|
||||
const future = diff > 0;
|
||||
if (abs < 60_000) return "just now";
|
||||
if (abs < 3_600_000) {
|
||||
const n = Math.round(abs / 60_000);
|
||||
return future ? `in ${n}m` : `${n}m ago`;
|
||||
}
|
||||
if (abs < 86_400_000) {
|
||||
const n = Math.round(abs / 3_600_000);
|
||||
return future ? `in ${n}h` : `${n}h ago`;
|
||||
}
|
||||
const n = Math.round(abs / 86_400_000);
|
||||
return future ? `in ${n}d` : `${n}d ago`;
|
||||
}
|
||||
|
||||
interface DatetimePropertyRowProps {
|
||||
label: string;
|
||||
iso: string;
|
||||
classNamePrefix?: string;
|
||||
}
|
||||
|
||||
export function DatetimePropertyRow({ label, iso, classNamePrefix = "intel-panel" }: DatetimePropertyRowProps) {
|
||||
const [expanded, setExpanded] = useState(false);
|
||||
|
||||
if (expanded) {
|
||||
return (
|
||||
<IntelPropertyRow label={label} isColumn classNamePrefix={classNamePrefix}>
|
||||
<span
|
||||
style={{ cursor: "pointer", fontWeight: 600 }}
|
||||
onClick={() => setExpanded(false)}
|
||||
>
|
||||
{formatLocal(iso)}
|
||||
</span>
|
||||
<span style={{ opacity: 0.6, fontSize: "0.85em" }}>{formatUtc(iso)}</span>
|
||||
<span style={{ opacity: 0.6, fontSize: "0.85em" }}>{formatRelative(iso)}</span>
|
||||
</IntelPropertyRow>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<IntelPropertyRow label={label} classNamePrefix={classNamePrefix}>
|
||||
<span
|
||||
style={{ cursor: "pointer", textDecoration: "underline dotted" }}
|
||||
onClick={() => setExpanded(true)}
|
||||
>
|
||||
{formatLocal(iso)}
|
||||
</span>
|
||||
</IntelPropertyRow>
|
||||
);
|
||||
}
|
||||
@@ -11,6 +11,8 @@ import { ImageProperty } from './ImageProperty';
|
||||
import { UrlProperty } from './UrlProperty';
|
||||
import { LongTextProperty } from './LongTextProperty';
|
||||
import { IntelPropertyRow } from './IntelPropertyRow';
|
||||
import { DatetimePropertyRow } from "./DatetimePropertyRow";
|
||||
import { VideoProperty } from "./VideoProperty";
|
||||
|
||||
/**
|
||||
* @interface DynamicPropertiesRenderProps
|
||||
@@ -37,6 +39,52 @@ export function DynamicPropertiesRender({ entity, classNamePrefix = "intel-panel
|
||||
const label = key.replace(/_/g, " ");
|
||||
const stringValue = String(value);
|
||||
|
||||
// Tagged dispatch - explicit type prefix, checked before heuristics
|
||||
if (typeof value === "string") {
|
||||
if (value.startsWith("datetime:")) {
|
||||
return (
|
||||
<DatetimePropertyRow
|
||||
key={key}
|
||||
label={label}
|
||||
iso={value.slice(9)}
|
||||
classNamePrefix={classNamePrefix}
|
||||
/>
|
||||
);
|
||||
}
|
||||
if (value.startsWith("url:")) {
|
||||
return (
|
||||
<UrlProperty
|
||||
key={key}
|
||||
label={label}
|
||||
url={value.slice(4)}
|
||||
classNamePrefix={classNamePrefix}
|
||||
/>
|
||||
);
|
||||
}
|
||||
if (value.startsWith("image:")) {
|
||||
return (
|
||||
<ImageProperty
|
||||
key={key}
|
||||
label={label}
|
||||
imageUrl={value.slice(6)}
|
||||
entityId={entity.id}
|
||||
entityLabel={entity.label ?? ""}
|
||||
classNamePrefix={classNamePrefix}
|
||||
/>
|
||||
);
|
||||
}
|
||||
if (value.startsWith("video:")) {
|
||||
return (
|
||||
<VideoProperty
|
||||
key={key}
|
||||
label={label}
|
||||
href={value.slice(6)}
|
||||
classNamePrefix={classNamePrefix}
|
||||
/>
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// Identify property type
|
||||
const isImage = typeof value === "string" && key.toLowerCase().includes("image") && /^https?:\/\//i.test(value);
|
||||
const isUrl = !isImage && typeof value === "string" && /^https?:\/\//i.test(value);
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
import { PlayCircle } from "lucide-react";
|
||||
import { IntelPropertyRow } from "./IntelPropertyRow";
|
||||
|
||||
interface VideoPropertyProps {
|
||||
label: string;
|
||||
href: string;
|
||||
classNamePrefix?: string;
|
||||
}
|
||||
|
||||
export function VideoProperty({ label, href, classNamePrefix = "intel-panel" }: VideoPropertyProps) {
|
||||
return (
|
||||
<IntelPropertyRow label={label} classNamePrefix={classNamePrefix}>
|
||||
<a
|
||||
href={href}
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
style={{ display: "flex", alignItems: "center", gap: 4, color: "var(--accent-cyan)" }}
|
||||
>
|
||||
<PlayCircle size={14} />
|
||||
Watch
|
||||
</a>
|
||||
</IntelPropertyRow>
|
||||
);
|
||||
}
|
||||
Reference in new issue
Block a user