Compare commits

...
Author SHA1 Message Date
Antigravity AI 7936990385 docs(agent): make plugin-implementer use the CLI correctly
Phase 2 now gives two explicit, copy-paste invocations — polling (no
--seeder-tier) and websocket (with --seeder-tier) — instead of one combined
example that wrongly showed --seeder-tier for every plugin. Adds the
build-CLI-first step, the >= 1.3.1 requirement (the version that fixed the
polling+--yes guard), and a note that a non-zero CLI exit is a hard stop, not
a cue to scaffold by hand.

Phase 4 no longer tells the agent to create the seeder files from scratch:
the websocket scaffold already emits package.json + tsup.config.ts +
src/index.ts, so Phase 4 is reframed as implementing the generated stub. The
reference snippets are kept as the target shape to verify against.
2026-05-29 20:11:49 +12:00
Silvertakana e9a908840d fix(cli): polling plugins with --yes no longer require --seeder-tier (#210)
The --yes guard counted the conditionally-skipped seederTier prompt as a
missing required value, so `create <id> --architecture polling ... --yes`
failed even though seeders only apply to websocket plugins. The guard now
only requires seederTier when the resolved architecture is websocket.

This bug shipped in 1.3.0 and was missed in manual UAT (the polling case
was exercised interactively, not with --yes). The new test suite caught it.

Also in this change:
- Add packages/wwv-cli/test/create.test.mjs: 9 integration tests that spawn
  the built CLI into temp dirs and assert the scaffolded tree (polling vs
  websocket, community vs private seeder tier, billboard/model/point render,
  --core, kebab-id naming, icon mapping, and the --yes / invalid-flag /
  duplicate-dir failure guards). Uses Node's built-in test runner, no new deps.
- Add .github/workflows/cli.yml: path-scoped to packages/wwv-cli, runs
  build (tsc) + the integration tests. Fast versus the full app suite.
- Add paths-ignore for packages/wwv-cli to the heavy app workflows (ci,
  playwright, docker-publish, test-setup-scripts, test-local-dev push) so a
  CLI-only change runs just cli.yml instead of the whole suite.
- Bump CLI to 1.3.1 and add a test script.
2026-05-29 20:08:42 +12:00
Silvertakana a2917536e4 feat(cli): accept flags for non-interactive plugin scaffolding (#209)
The 'wwv create' command was fully interactive (prompts-only) and the
plugin-implementer agent's documented '--local' flag did not exist, so
agents fell back to slow manual scaffolding.

- Add a positional [pluginId] arg plus a flag for every prompt
  (--display-name, --description, --category, --architecture,
  --seeder-tier, --render-style) and a --yes guard that fails fast
  instead of hanging when a required value is missing. Any omitted
  flag still prompts, so interactive use is unchanged.
- Fix seeder output to the real community/private layout:
  local-seeders/<tier>/packages/<name>/{package.json,tsup.config.ts,
  src/index.ts}, exporting the canonical { name, cron, fn } shape with
  name === plugin id (kebab-case) per ADR-0002. Previously it wrote a
  bare seeder.mjs to the wrong path with an unusable context.emit stub.
- Update plugin-implementer.md: drop the bogus --local flag, document
  the flag-based invocation and the correct seeder location, and note
  the CLI build step for fresh worktrees.
- Bump CLI to 1.3.0 and fix the stale hardcoded --version string.
2026-05-29 19:29:30 +12:00
Silvertakana 41c42c0ca1 fix(worktree): make git-wt link-planning hook create real isolated .planning (#207)
The link_planning pre-start hook created a JUNCTION from each new worktree's
.planning to the shared root, which caused GSD phase bleed across simultaneous
worktree sessions. Rewrite it to create a REAL isolated .planning directory
(phases/debug/surveys + config.json + WORKSPACE/STATE/SHARED-DOCS manifests),
idempotently: preserve an existing real dir, only replace a leftover junction.

Update unlink-planning (pre-remove) to remove only a leftover junction and never
recurse into a real dir; phase history is archived by /branch-cleanup before removal.

Closes the gap flagged in WORKSPACE-OPTIMIZATION-BACKLOG.md. Verified with an
18-check harness (fresh create, idempotency, junction replacement, unlink behavior).
2026-05-29 17:09:15 +12:00
13 changed files with 689 additions and 85 deletions

No files matched your search

+50 -7
View File
@@ -28,14 +28,55 @@ If any are missing, ask the user or tell them to run plugin-researcher first.
## Phase 2 — Scaffold ## Phase 2 — Scaffold
From the project root (`C:\dev\wwv\worldwideview`): 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):
```bash ```bash
node packages/wwv-cli/dist/index.js create <name> --local 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
pnpm install pnpm install
``` ```
This creates `local-plugins/wwv-plugin-<name>/`. Verify it exists before proceeding. 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.
**NEVER:** **NEVER:**
- Scaffold manually (always use the CLI) - Scaffold manually (always use the CLI)
@@ -116,13 +157,15 @@ export class MyPlugin implements WorldPlugin {
--- ---
## Phase 4 — Implement the Seeder (skip for static plugins) ## Phase 4 — Implement the Seeder (skip for static / polling-only plugins)
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. 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.
### Create `local-seeders/community/packages/<name>/` 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.
**`package.json`:** ### Generated layout: `local-seeders/<tier>/packages/<name>/`
**`package.json`** (CLI-generated — only adjust `dependencies` for what your seeder imports):
```json ```json
{ {
"name": "@wwv-seeders/<name>", "name": "@wwv-seeders/<name>",
+155 -2
View File
@@ -1,8 +1,161 @@
param([string]$worktreePath) 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 # Convert Unix-style path (/c/dev/...) to Windows path (C:\dev\...) if needed
if ($worktreePath -match '^/([a-zA-Z])/(.+)$') { if ($worktreePath -match '^/([a-zA-Z])/(.+)$') {
$worktreePath = $matches[1].ToUpper() + ':/' + $matches[2] $worktreePath = $matches[1].ToUpper() + ':/' + $matches[2]
} }
$sharedRoot = 'C:\dev\wwv\.planning'
$target = Join-Path $worktreePath '.planning' $target = Join-Path $worktreePath '.planning'
if (Test-Path $target) { Remove-Item $target -Force }
New-Item -ItemType Junction -Path $target -Target 'C:\dev\wwv\.planning' | Out-Null # 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
+23 -1
View File
@@ -1,7 +1,29 @@
param([string]$worktreePath) 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 # Convert Unix-style path (/c/dev/...) to Windows path (C:\dev\...) if needed
if ($worktreePath -match '^/([a-zA-Z])/(.+)$') { if ($worktreePath -match '^/([a-zA-Z])/(.+)$') {
$worktreePath = $matches[1].ToUpper() + ':/' + $matches[2] $worktreePath = $matches[1].ToUpper() + ':/' + $matches[2]
} }
$target = Join-Path $worktreePath '.planning' $target = Join-Path $worktreePath '.planning'
if (Test-Path $target) { Remove-Item $target -Force }
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
+5
View File
@@ -1,10 +1,15 @@
name: CI name: CI
# CLI-only changes are covered by cli.yml; skip the full app suite for them.
on: on:
push: push:
branches: [main] branches: [main]
paths-ignore:
- "packages/wwv-cli/**"
pull_request: pull_request:
branches: [main] branches: [main]
paths-ignore:
- "packages/wwv-cli/**"
jobs: jobs:
# Non-blocking dependency audit. Surfaces high / critical vulnerabilities # Non-blocking dependency audit. Surfaces high / critical vulnerabilities
+36
View File
@@ -0,0 +1,36 @@
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
+5
View File
@@ -1,10 +1,15 @@
name: Docker Image CI name: Docker Image CI
# CLI-only changes are covered by cli.yml; skip the image build for them.
on: on:
push: push:
branches: [ "main" ] branches: [ "main" ]
paths-ignore:
- "packages/wwv-cli/**"
pull_request: pull_request:
branches: [ "main" ] branches: [ "main" ]
paths-ignore:
- "packages/wwv-cli/**"
env: env:
REGISTRY: ghcr.io REGISTRY: ghcr.io
+5
View File
@@ -1,9 +1,14 @@
name: Playwright Tests name: Playwright Tests
# CLI-only changes are covered by cli.yml; skip browser E2E for them.
on: on:
push: push:
branches: [ main, master ] branches: [ main, master ]
paths-ignore:
- "packages/wwv-cli/**"
pull_request: pull_request:
branches: [ main, master ] branches: [ main, master ]
paths-ignore:
- "packages/wwv-cli/**"
permissions: permissions:
contents: read contents: read
jobs: jobs:
+2
View File
@@ -3,6 +3,8 @@ name: Test Local Dev Environment
on: on:
push: push:
branches: [main] branches: [main]
paths-ignore:
- "packages/wwv-cli/**"
pull_request: pull_request:
branches: [main] branches: [main]
paths: paths:
+5
View File
@@ -1,10 +1,15 @@
name: Test Setup Scripts name: Test Setup Scripts
# CLI-only changes are covered by cli.yml; skip setup-script tests for them.
on: on:
push: push:
branches: [ "main" ] branches: [ "main" ]
paths-ignore:
- "packages/wwv-cli/**"
pull_request: pull_request:
branches: [ "main" ] branches: [ "main" ]
paths-ignore:
- "packages/wwv-cli/**"
permissions: permissions:
contents: read contents: read
+3 -2
View File
@@ -1,6 +1,6 @@
{ {
"name": "@worldwideview/wwv-cli", "name": "@worldwideview/wwv-cli",
"version": "1.2.0", "version": "1.3.1",
"type": "module", "type": "module",
"description": "WorldWideView CLI", "description": "WorldWideView CLI",
"main": "dist/index.js", "main": "dist/index.js",
@@ -10,7 +10,8 @@
"scripts": { "scripts": {
"build": "tsc", "build": "tsc",
"dev": "tsc --watch", "dev": "tsc --watch",
"clean": "rm -rf dist" "clean": "rm -rf dist",
"test": "node --test \"test/**/*.test.mjs\""
}, },
"dependencies": { "dependencies": {
"commander": "^14.0.3", "commander": "^14.0.3",
+180 -72
View File
@@ -4,29 +4,74 @@ import fs from 'fs';
import path from 'path'; import path from 'path';
import prompts from 'prompts'; 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') export const createCommand = new Command('create')
.description('Interactively scaffold a new WorldWideView plugin') .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)')
.option('-c, --core', 'Create inside packages instead of local-plugins (for core contributors)') .option('-c, --core', 'Create inside packages instead of local-plugins (for core contributors)')
.action(async (options) => { .option('-n, --display-name <name>', 'Display name (e.g. "My Live Tracker")')
const response = await prompts([ .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({
type: 'text', type: 'text',
name: 'pluginId', name: 'pluginId',
message: 'What is the unique ID for your plugin? (e.g. my-tracker)', message: 'What is the unique ID for your plugin? (e.g. my-tracker)',
validate: value => value.length > 0 ? true : 'Plugin ID is required' validate: value => value.length > 0 ? true : 'Plugin ID is required',
}, });
{ }
if (options.displayName === undefined) {
promptList.push({
type: 'text', type: 'text',
name: 'displayName', name: 'displayName',
message: 'What is the display name? (e.g. My Live Tracker)', 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()) initial: pluginIdArg
}, ? pluginIdArg.replace(/-/g, ' ').replace(/\b\w/g, (l: string) => l.toUpperCase())
{ : undefined,
type: 'text', });
name: 'description', }
message: 'Enter a short description:' if (options.description === undefined) {
}, promptList.push({ type: 'text', name: 'description', message: 'Enter a short description:' });
{ }
if (options.category === undefined) {
promptList.push({
type: 'select', type: 'select',
name: 'category', name: 'category',
message: 'Which category does this plugin belong to?', message: 'Which category does this plugin belong to?',
@@ -35,46 +80,78 @@ export const createCommand = new Command('create')
{ title: 'Maritime (Ship icon)', value: 'maritime' }, { title: 'Maritime (Ship icon)', value: 'maritime' },
{ title: 'Space (Satellite icon)', value: 'space' }, { title: 'Space (Satellite icon)', value: 'space' },
{ title: 'Weather (Cloud icon)', value: 'weather' }, { title: 'Weather (Cloud icon)', value: 'weather' },
{ title: 'Custom (Box icon)', value: 'custom' } { title: 'Custom (Box icon)', value: 'custom' },
] ],
}, });
{ }
if (options.architecture === undefined) {
promptList.push({
type: 'select', type: 'select',
name: 'architecture', name: 'architecture',
message: 'How will your plugin receive data?', message: 'How will your plugin receive data?',
choices: [ choices: [
{ title: 'REST Polling / Static Data (Frontend only)', value: 'polling' }, { title: 'REST Polling / Static Data (Frontend only)', value: 'polling' },
{ title: 'Real-Time WebSockets (Generates backend seeder)', value: 'websocket' } { title: 'Real-Time WebSockets (Generates backend seeder)', value: 'websocket' },
] ],
}, });
{ }
type: (prev: string) => prev === 'websocket' ? 'select' : null, 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;
},
name: 'seederTier', name: 'seederTier',
message: 'Which tier should your backend seeder belong to?', message: 'Which tier should your backend seeder belong to?',
choices: [ choices: [
{ title: 'Community (Open data, shared)', value: 'community' }, { title: 'Community (Open data, shared)', value: 'community' },
{ title: 'Private (Requires API keys, restricted)', value: 'private' } { title: 'Private (Requires API keys, restricted)', value: 'private' },
] ],
}, });
{ }
if (options.renderStyle === undefined) {
promptList.push({
type: 'select', type: 'select',
name: 'renderStyle', name: 'renderStyle',
message: 'How should entities be rendered on the 3D globe?', message: 'How should entities be rendered on the 3D globe?',
choices: [ choices: [
{ title: '2D Billboard (Great for static icons)', value: 'billboard' }, { title: '2D Billboard (Great for static icons)', value: 'billboard' },
{ title: '3D Model with LOD (Transitions 2D to 3D)', value: 'model' }, { title: '3D Model with LOD (Transitions 2D to 3D)', value: 'model' },
{ title: 'Simple Point (High performance dots)', value: 'point' } { title: 'Simple Point (High performance dots)', value: 'point' },
] ],
} });
]); }
if (!response.pluginId) { 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);
}
}
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) {
console.log('Plugin creation cancelled.'); console.log('Plugin creation cancelled.');
return; return;
} }
const { pluginId, displayName, description, category, architecture, seederTier, renderStyle } = response;
const targetBaseDir = options.core ? 'packages' : 'local-plugins'; const targetBaseDir = options.core ? 'packages' : 'local-plugins';
const pluginDir = path.join(process.cwd(), targetBaseDir, `wwv-plugin-${pluginId}`); const pluginDir = path.join(process.cwd(), targetBaseDir, `wwv-plugin-${pluginId}`);
@@ -85,21 +162,19 @@ export const createCommand = new Command('create')
fs.mkdirSync(pluginDir, { recursive: true }); fs.mkdirSync(pluginDir, { recursive: true });
// Determine category icon
const iconMap: Record<string, string> = { const iconMap: Record<string, string> = {
aviation: 'Plane', aviation: 'Plane',
maritime: 'Ship', maritime: 'Ship',
space: 'Satellite', space: 'Satellite',
weather: 'Cloud', weather: 'Cloud',
custom: 'Box' custom: 'Box',
}; };
const defaultIcon = iconMap[category] || 'Box'; const defaultIcon = iconMap[category] || 'Box';
// Package.json boilerplate const streamUrlField = architecture === 'websocket'
const streamUrlField = architecture === 'websocket' ? `\n "streamUrl": "wss://dataenginev2.worldwideview.dev/stream",`
? `\n "streamUrl": "wss://dataenginev2.worldwideview.dev/stream",`
: ''; : '';
const packageJsonContent = `{ const packageJsonContent = `{
"name": "@worldwideview/wwv-plugin-${pluginId}", "name": "@worldwideview/wwv-plugin-${pluginId}",
"version": "1.0.0", "version": "1.0.0",
@@ -131,7 +206,6 @@ export const createCommand = new Command('create')
} }
`; `;
// index.ts boilerplate
const renderBoilerplate = { const renderBoilerplate = {
billboard: `return { billboard: `return {
type: 'billboard', type: 'billboard',
@@ -152,14 +226,14 @@ export const createCommand = new Command('create')
size: 8, size: 8,
outlineColor: '#ffffff', outlineColor: '#ffffff',
outlineWidth: 2 outlineWidth: 2
};` };`,
}[renderStyle as string] || `return {};`; }[renderStyle as string] || `return {};`;
const fetchBoilerplate = architecture === 'polling' const fetchBoilerplate = architecture === 'polling'
? `\n async fetch(): Promise<GeoEntity[]> { ? `\n async fetch(): Promise<GeoEntity[]> {
// Implement REST polling logic here // Implement REST polling logic here
return []; return [];
}\n` }\n`
: ''; : '';
const indexTsContent = `import { WorldPlugin, GeoEntity, CesiumEntityOptions } from '@worldwideview/wwv-plugin-sdk'; const indexTsContent = `import { WorldPlugin, GeoEntity, CesiumEntityOptions } from '@worldwideview/wwv-plugin-sdk';
@@ -195,41 +269,75 @@ ${fetchBoilerplate}
console.log(`\n✅ Successfully created plugin frontend at ${pluginDir}`); console.log(`\n✅ Successfully created plugin frontend at ${pluginDir}`);
// Generate seeder backend if requested // 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.
if (architecture === 'websocket' && seederTier) { if (architecture === 'websocket' && seederTier) {
const seederDir = path.join(process.cwd(), 'local-seeders', seederTier, pluginId); const seederDir = path.join(process.cwd(), 'local-seeders', seederTier, 'packages', pluginId);
if (!fs.existsSync(seederDir)) { if (fs.existsSync(seederDir)) {
fs.mkdirSync(seederDir, { recursive: true }); console.error(`Warning: Seeder directory ${seederDir} already exists. Skipping seeder scaffold.`);
} else {
const seederContent = `// WWV Data Engine Seeder for ${pluginId} fs.mkdirSync(path.join(seederDir, 'src'), { recursive: true });
export default async function run(context) {
console.log('Starting ${displayName} seeder...'); const seederPackageJson = `{
"name": "@wwv-seeders/${pluginId}",
// Example: Emit a mock entity to the engine "version": "1.0.0",
setInterval(() => { "main": "dist/index.mjs",
context.emit({ "scripts": {
id: '${pluginId}-mock-1', "build": "tsup"
lat: 0, },
lng: 0, "dependencies": {
alt: 10000, "@worldwideview/seeder-sdk": "^1.0.0"
heading: 0, }
velocity: 250,
properties: {
status: 'active'
}
});
}, 1000);
} }
`; `;
fs.writeFileSync(path.join(seederDir, 'seeder.mjs'), seederContent);
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);
console.log(`✅ Successfully created plugin seeder at ${seederDir}`); console.log(`✅ Successfully created plugin seeder at ${seederDir}`);
} }
} }
console.log(`\nNext steps: console.log(`\nNext steps:
1. Run \`pnpm install\` from the project root. 1. Run \`pnpm install\` from the project root.
2. Edit \`index.ts\` in your plugin directory. 2. Edit \`src/index.ts\` in your plugin directory.
${architecture === 'websocket' ? '3. Edit `seeder.mjs` in your local-seeders directory.' : ''} ${architecture === 'websocket' && seederTier ? `3. Edit \`src/index.ts\` in local-seeders/${seederTier}/packages/${pluginId}/, then \`pnpm build\` it.` : ''}
`); `);
}); });
+1 -1
View File
@@ -9,7 +9,7 @@ const program = new Command();
program program
.name('wwv') .name('wwv')
.description('WorldWideView Plugin CLI') .description('WorldWideView Plugin CLI')
.version('1.1.2'); .version('1.3.1');
program.addCommand(createCommand); program.addCommand(createCommand);
program.addCommand(publishCommand); program.addCommand(publishCommand);
+219
View File
@@ -0,0 +1,219 @@
// 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 });
}
});