Compare commits
6
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ed4bb97d10 | ||
|
|
ff03d6dd3e | ||
|
|
610b379860 | ||
|
|
9a5adb832e | ||
|
|
f447bd7e72 | ||
|
|
a833cf4790 |
No files matched your search
@@ -89,3 +89,60 @@ This means:
|
||||
|
||||
> [!CAUTION]
|
||||
> The most common silent bug: seeder sends `{ items: [...] }` (an object), frontend plugin omits `mapWebsocketPayload`. Data arrives but WsClient drops it with a console warning. The globe stays empty. Always implement `mapWebsocketPayload` for any plugin whose seeder sends an object payload.
|
||||
|
||||
## 8. Seeder Authoring Contract — the module shape
|
||||
|
||||
§7 covers what a seeder **sends**. This covers how you **write** one. The engine
|
||||
auto-discovers a seeder by scanning `SEEDERS_DIR` for any folder with
|
||||
`dist/index.mjs` and importing its **default export**. The seeder's `id` is the
|
||||
**folder name**, not the `name` field. You never call a register function — the
|
||||
authoritative reference is `wwv-data-engine/README.md` → "Authoring a Seeder".
|
||||
|
||||
The default export is `{ name }` plus **one** of these shapes:
|
||||
|
||||
| Shape | You provide | How data is published |
|
||||
|---|---|---|
|
||||
| `interval` + `fetch(ctx)` | `fetch` **returns** the array | scheduler wraps + stores + broadcasts it for you |
|
||||
| `cron` + `fn(ctx)` | `fn` publishes itself | `import { setLiveSnapshot } from '@worldwideview/seeder-sdk'` and call it |
|
||||
| `init(ctx)` | a persistent listener | publish via the SDK as push data arrives |
|
||||
|
||||
**The trap (this caused a real, silent CI failure):** `ctx` is **only `{ redis }`**.
|
||||
There is no `ctx.setLiveSnapshot`. Reaching for it throws at runtime and the
|
||||
snapshot never lands. Publish helpers come from `@worldwideview/seeder-sdk`, not
|
||||
from `ctx`. The engine now types `ctx` as `SeederContext { redis }`, so this is a
|
||||
compile error for any typed seeder — but `.mjs` seeders without type-checking get
|
||||
no such safety net, so know the contract.
|
||||
|
||||
<bad-example>
|
||||
```ts
|
||||
// cron + fn reaching for a method that does not exist on ctx
|
||||
export default {
|
||||
name: "earthquakes",
|
||||
cron: "0 * * * *",
|
||||
fn: async (ctx) => {
|
||||
await ctx.setLiveSnapshot("earthquakes", items, 3600); // ❌ not a function — dies silently
|
||||
},
|
||||
};
|
||||
```
|
||||
</bad-example>
|
||||
|
||||
<good-example>
|
||||
```ts
|
||||
// Option A — cron + fn: publish via the SDK (dominant idiom)
|
||||
import { setLiveSnapshot } from "@worldwideview/seeder-sdk";
|
||||
export default {
|
||||
name: "earthquakes",
|
||||
cron: "0 * * * *",
|
||||
fn: async () => {
|
||||
await setLiveSnapshot("earthquakes", { source: "earthquakes", fetchedAt: new Date().toISOString(), items, totalCount: items.length }, 3600);
|
||||
},
|
||||
};
|
||||
|
||||
// Option B — interval + fetch: just return the array, scheduler does the rest
|
||||
export default {
|
||||
name: "earthquakes",
|
||||
interval: 60_000,
|
||||
fetch: async () => items, // ✅ no publishing call needed
|
||||
};
|
||||
```
|
||||
</good-example>
|
||||
@@ -0,0 +1,93 @@
|
||||
# Trigger model: merge to main with a version bump in the relevant package.json is the
|
||||
# intended signal. This workflow checks npm for the exact version before publishing, so
|
||||
# re-running on an already-published version is safe and idempotent.
|
||||
#
|
||||
# Auth: a single npm granular token scoped to @worldwideview/*, stored as the
|
||||
# org-level GitHub secret NPM_TOKEN. One secret covers every @worldwideview package
|
||||
# (these libs + all wwv-plugins), so no per-package setup is needed. `actions/setup-node`
|
||||
# (with registry-url) writes an .npmrc that reads NODE_AUTH_TOKEN. We still request
|
||||
# `id-token: write` and pass `--provenance` so npm records a signed build-provenance
|
||||
# attestation (provenance works with token auth; it does NOT require per-package config).
|
||||
#
|
||||
# Publish tool: we use `npm publish` (not `pnpm publish`). Correct ONLY while these packages
|
||||
# have no `workspace:*` dependencies (npm does not rewrite the workspace: protocol). The 3
|
||||
# packages here have none (sdk -> react peer; libs -> sdk peer via a semver range). If any
|
||||
# package later adds a `workspace:*` dependency, switch its publish step to
|
||||
# `pnpm publish --no-git-checks`.
|
||||
|
||||
name: Publish Packages to npm
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
# Serialize runs so two fast-follow merges can't both pass the version-check and then
|
||||
# race to publish the same version (npm would 403 the loser). Never cancel an in-flight
|
||||
# publish.
|
||||
concurrency:
|
||||
group: publish-packages
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: ubuntu-latest
|
||||
# id-token: write is for build-provenance attestation (not auth); scope to this job.
|
||||
permissions:
|
||||
contents: read
|
||||
id-token: write
|
||||
# Auth for every npm publish step in this job (setup-node reads NODE_AUTH_TOKEN).
|
||||
env:
|
||||
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
|
||||
- uses: pnpm/action-setup@v6
|
||||
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 20
|
||||
registry-url: https://registry.npmjs.org
|
||||
cache: pnpm
|
||||
|
||||
- name: Install dependencies
|
||||
run: pnpm install --frozen-lockfile
|
||||
|
||||
- name: Build wwv-plugin-sdk
|
||||
run: pnpm --filter @worldwideview/wwv-plugin-sdk run build
|
||||
|
||||
- name: Publish @worldwideview/wwv-plugin-sdk
|
||||
run: |
|
||||
LOCAL_VERSION=$(node -p "require('./packages/wwv-plugin-sdk/package.json').version")
|
||||
# Equality check (not exit-code): only skip when that EXACT version is already on
|
||||
# npm. An unpublished-yet-existing package returns empty here -> we publish. --silent
|
||||
# keeps npm notices off stdout so the comparison stays clean.
|
||||
NPM_VERSION=$(npm view "@worldwideview/wwv-plugin-sdk@${LOCAL_VERSION}" version --silent 2>/dev/null || true)
|
||||
if [ "$NPM_VERSION" = "$LOCAL_VERSION" ]; then
|
||||
echo "@worldwideview/wwv-plugin-sdk@${LOCAL_VERSION} already published — skipping"
|
||||
else
|
||||
echo "Publishing @worldwideview/wwv-plugin-sdk@${LOCAL_VERSION}"
|
||||
npm publish packages/wwv-plugin-sdk --provenance --access public
|
||||
fi
|
||||
|
||||
- name: Publish @worldwideview/wwv-lib-incidents
|
||||
run: |
|
||||
LOCAL_VERSION=$(node -p "require('./packages/wwv-lib-incidents/package.json').version")
|
||||
NPM_VERSION=$(npm view "@worldwideview/wwv-lib-incidents@${LOCAL_VERSION}" version --silent 2>/dev/null || true)
|
||||
if [ "$NPM_VERSION" = "$LOCAL_VERSION" ]; then
|
||||
echo "@worldwideview/wwv-lib-incidents@${LOCAL_VERSION} already published — skipping"
|
||||
else
|
||||
echo "Publishing @worldwideview/wwv-lib-incidents@${LOCAL_VERSION}"
|
||||
npm publish packages/wwv-lib-incidents --provenance --access public
|
||||
fi
|
||||
|
||||
- name: Publish @worldwideview/wwv-lib-aviation
|
||||
run: |
|
||||
LOCAL_VERSION=$(node -p "require('./packages/wwv-lib-aviation/package.json').version")
|
||||
NPM_VERSION=$(npm view "@worldwideview/wwv-lib-aviation@${LOCAL_VERSION}" version --silent 2>/dev/null || true)
|
||||
if [ "$NPM_VERSION" = "$LOCAL_VERSION" ]; then
|
||||
echo "@worldwideview/wwv-lib-aviation@${LOCAL_VERSION} already published — skipping"
|
||||
else
|
||||
echo "Publishing @worldwideview/wwv-lib-aviation@${LOCAL_VERSION}"
|
||||
npm publish packages/wwv-lib-aviation --provenance --access public
|
||||
fi
|
||||
@@ -1,38 +0,0 @@
|
||||
name: Publish Plugin to NPM
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "wwv-plugin-*-v*" # e.g. wwv-plugin-aviation-v1.0.1
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
id-token: write # Required for OIDC trusted publishing (no NPM_TOKEN needed)
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 20
|
||||
registry-url: "https://registry.npmjs.org"
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Detect package name from tag
|
||||
id: pkg
|
||||
run: |
|
||||
TAG="${{ github.ref_name }}"
|
||||
# Strips the -vX.Y.Z suffix: "wwv-plugin-aviation-v1.0.1" → "wwv-plugin-aviation"
|
||||
PKG=$(echo "$TAG" | sed 's/-v[0-9].*//')
|
||||
echo "package=$PKG" >> $GITHUB_OUTPUT
|
||||
echo "Publishing: $PKG"
|
||||
|
||||
- name: Build package
|
||||
run: npm run build -w packages/${{ steps.pkg.outputs.package }}
|
||||
|
||||
- name: Publish to NPM (OIDC)
|
||||
run: npm publish packages/${{ steps.pkg.outputs.package }} --access public --provenance
|
||||
@@ -60,6 +60,7 @@ Agents MUST respect these at all times:
|
||||
> - **MUST** require explicit user authorization before any state-changing action that isn't simple/safe.
|
||||
> - **MUST** ask clarifying questions rather than assume when requirements are unclear.
|
||||
> - **MUST** update `.agents/rules/` files immediately whenever an architectural shift invalidates them.
|
||||
> - **MUST** close context gaps: when missing/wrong/undocumented context made you err, struggle, or go slow, fix the relevant doc/context (or add a type/guardrail) at its source — or ask the user to update it when it depends on their knowledge. In autonomous mode, log the gap to revisit later. Never fix only the symptom and leave the trap armed for the next contributor.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -18,18 +18,12 @@
|
||||
# Reuse the pattern from worldwideview/tests/global.setup.ts. DB migrations
|
||||
# are handled automatically by the wwv-app entrypoint at container start.
|
||||
#
|
||||
# ─── Known foundation gap (deferred) ───
|
||||
# ─── Stub seeder source ───
|
||||
#
|
||||
# The stub-seeder is mounted via `./stub-seeder:/app/seeders/community/stub-seeder`
|
||||
# below — a path RELATIVE to this compose file. When a consumer repo downloads
|
||||
# only this YAML, that path resolves to nothing. The clean fix is to bake the
|
||||
# stub-seeder into the `wwv-data-engine:ci` image at /app/seeders/community/__ci-stub__/
|
||||
# so the compose only needs to set STUB_PLUGIN_ID. That requires a coordinated
|
||||
# Dockerfile change in the wwv-data-engine repo — tracked as the next session's
|
||||
# first task.
|
||||
#
|
||||
# Until then, this compose only works when the worldwideview source tree
|
||||
# (with docker/ci/stub-seeder/) is the working directory.
|
||||
# The stub seeder is baked into the `wwv-data-engine:ci` image at
|
||||
# /app/seeders/stub (see wwv-data-engine/Dockerfile.ci). The compose only needs
|
||||
# to set STUB_PLUGIN_ID — no volume mount, so a consumer repo can download just
|
||||
# this YAML and run it without the worldwideview source tree present.
|
||||
#
|
||||
# Expected env vars from consuming workflow:
|
||||
# PLUGIN_ID — kebab-case id of the plugin under test (e.g. "aviation")
|
||||
@@ -71,9 +65,9 @@ services:
|
||||
STUB_PLUGIN_ID: ${PLUGIN_ID}
|
||||
WWV_SKIP_WS_AUTH: "true"
|
||||
NODE_ENV: ci
|
||||
volumes:
|
||||
# Mount only the stub seeder — no other seeders to avoid contamination
|
||||
- ./stub-seeder:/app/seeders/community/stub-seeder:ro
|
||||
# No volume mount: the stub seeder is baked into the :ci image at
|
||||
# /app/seeders/stub, so the engine discovers it as id "stub" with no host
|
||||
# path dependency.
|
||||
depends_on:
|
||||
wwv-redis:
|
||||
condition: service_healthy
|
||||
|
||||
Vendored
+9
-4
@@ -10,6 +10,11 @@ const pluginId = process.env.STUB_PLUGIN_ID;
|
||||
// When unconfigured (e.g. seeder-CI, where this stub is baked into the shared
|
||||
// :ci image but unused), export a nameless module so the seeder-loader skips
|
||||
// it instead of crashing the engine.
|
||||
//
|
||||
// Uses the interval+fetch seeder contract: fetch() RETURNS the array and the
|
||||
// scheduler auto-wraps it into a snapshot stored under the seeder id. The
|
||||
// cron+fn contract would require the engine-internal setLiveSnapshot, which is
|
||||
// NOT exposed on the seeder ctx (ctx is only { redis }).
|
||||
|
||||
function makeEntities() {
|
||||
const now = new Date().toISOString();
|
||||
@@ -40,11 +45,11 @@ function makeEntities() {
|
||||
export default pluginId
|
||||
? {
|
||||
name: pluginId,
|
||||
cron: "*/10 * * * * *",
|
||||
fn: async (ctx) => {
|
||||
interval: 10000,
|
||||
fetch: async () => {
|
||||
const entities = makeEntities();
|
||||
await ctx.setLiveSnapshot(pluginId, entities, 300);
|
||||
console.log(`[stub-seeder] emitted ${entities.length} entities for ${pluginId}`);
|
||||
console.log(`[stub-seeder] emitting ${entities.length} entities for ${pluginId}`);
|
||||
return entities;
|
||||
},
|
||||
}
|
||||
: {};
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "worldwideview",
|
||||
"version": "2.48.20",
|
||||
"version": "2.48.24",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"packageManager": "[email protected]",
|
||||
|
||||
Reference in new issue
Block a user