Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
7936990385 | ||
|
|
e9a908840d |
No files matched your search
@@ -28,32 +28,55 @@ If any are missing, ask the user or tell them to run plugin-researcher first.
|
||||
|
||||
## 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
|
||||
# Build the CLI first if dist/ is missing (dist is gitignored; fresh worktrees lack it):
|
||||
# pnpm --filter @worldwideview/wwv-cli build
|
||||
#
|
||||
# The CLI accepts flags for every prompt. Pass them all + --yes for a fully
|
||||
# non-interactive scaffold (omit any flag to be prompted for just that value):
|
||||
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|websocket> \
|
||||
--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
|
||||
```
|
||||
|
||||
This creates `local-plugins/wwv-plugin-<name>/`. With `--architecture websocket` it also
|
||||
creates the seeder at `local-seeders/<tier>/packages/<name>/` (correct community/private
|
||||
layout: `package.json` + `tsup.config.ts` + `src/index.ts`). Verify both exist 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.
|
||||
|
||||
> The CLI scaffolds the seeder into `local-seeders/<tier>/packages/<name>/` already —
|
||||
> no post-CLI move is required. (Older CLI versions dropped a bare `seeder.mjs` at
|
||||
> `local-seeders/<tier>/<name>/`; if you ever see that, the CLI is out of date — rebuild it.)
|
||||
> 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:**
|
||||
- Scaffold manually (always use the CLI)
|
||||
@@ -134,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
|
||||
{
|
||||
"name": "@wwv-seeders/<name>",
|
||||
|
||||
@@ -1,10 +1,15 @@
|
||||
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
|
||||
|
||||
@@ -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
|
||||
@@ -1,10 +1,15 @@
|
||||
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,9 +1,14 @@
|
||||
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,6 +3,8 @@ name: Test Local Dev Environment
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths-ignore:
|
||||
- "packages/wwv-cli/**"
|
||||
pull_request:
|
||||
branches: [main]
|
||||
paths:
|
||||
|
||||
@@ -1,10 +1,15 @@
|
||||
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,6 +1,6 @@
|
||||
{
|
||||
"name": "@worldwideview/wwv-cli",
|
||||
"version": "1.3.0",
|
||||
"version": "1.3.1",
|
||||
"type": "module",
|
||||
"description": "WorldWideView CLI",
|
||||
"main": "dist/index.js",
|
||||
@@ -10,7 +10,8 @@
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"dev": "tsc --watch",
|
||||
"clean": "rm -rf dist"
|
||||
"clean": "rm -rf dist",
|
||||
"test": "node --test \"test/**/*.test.mjs\""
|
||||
},
|
||||
"dependencies": {
|
||||
"commander": "^14.0.3",
|
||||
|
||||
@@ -124,9 +124,16 @@ export const createCommand = new Command('create')
|
||||
}
|
||||
|
||||
if (options.yes && promptList.length > 0) {
|
||||
const missing = promptList.map(p => p.name).join(', ');
|
||||
console.error(`Error: --yes given but these required values are missing: ${missing}`);
|
||||
process.exit(1);
|
||||
// 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) : {};
|
||||
|
||||
@@ -9,7 +9,7 @@ const program = new Command();
|
||||
program
|
||||
.name('wwv')
|
||||
.description('WorldWideView Plugin CLI')
|
||||
.version('1.3.0');
|
||||
.version('1.3.1');
|
||||
|
||||
program.addCommand(createCommand);
|
||||
program.addCommand(publishCommand);
|
||||
|
||||
@@ -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 });
|
||||
}
|
||||
});
|
||||
Reference in new issue
Block a user