Compare commits

...
Author SHA1 Message Date
Antigravity AI 96b8a444aa docs(rules): add close-context-gaps AI meta-directive to AGENTS.md
When missing/wrong/undocumented context causes an error, a long struggle, or
slow understanding, agents must fix the doc/context (or add a guardrail) at its
source, or ask the user to; in autonomous mode, log the gap to revisit. Codifies
the lesson from the seeder ctx.setLiveSnapshot incident for all contributors.
2026-06-05 00:22:23 +12:00
Antigravity AI 03ae14ad53 docs(rules): add seeder authoring contract to data-engine-architecture rule
Adds section 8 documenting how to write a seeder: the auto-discovery model,
the three module shapes (interval+fetch, cron+fn, init), the { redis }-only
ctx, and publishing via @worldwideview/seeder-sdk. Includes good/bad examples
contrasting the ctx.setLiveSnapshot trap (which caused a silent CI failure)
against the two correct shapes. This rule auto-loads on local-seeders/** edits.
2026-06-05 00:13:01 +12:00
Silvertakana f447bd7e72 fix(ci): stub seeder interval+fetch + drop redundant compose mount (#239)
Companion to wwv-data-engine fix/ci-stub-interval-fetch. The source-of-truth
stub (docker/ci/stub-seeder) used cron+fn and called ctx.setLiveSnapshot,
which the seeder ctx ({ redis }) does not expose — the snapshot never landed.
Switch to interval+fetch (return the array; scheduler auto-wraps + stores it).

Also remove the plugin-CI compose's ./stub-seeder volume mount and the stale
'Known foundation gap (deferred)' comment: the stub is now baked into the :ci
image at /app/seeders/stub, so the compose needs no host path and a consumer
repo can run it with only this YAML.
2026-06-04 23:58:20 +12:00
Silvertakana a833cf4790 fix(ci-probe): subscribe to pluginId on /stream + safe stub + plugin-CI auth bypass (#238) 2026-06-04 23:40:08 +12:00
7 changed files with 129 additions and 30 deletions

No files matched your search

+57
View File
@@ -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>
+1
View File
@@ -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.
---
+10 -14
View File
@@ -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")
@@ -69,9 +63,11 @@ services:
DB_PATH: /tmp/engine.db
# Stub seeder reads the target plugin id from this env var
STUB_PLUGIN_ID: ${PLUGIN_ID}
volumes:
# Mount only the stub seeder — no other seeders to avoid contamination
- ./stub-seeder:/app/seeders/community/stub-seeder:ro
WWV_SKIP_WS_AUTH: "true"
NODE_ENV: ci
# 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
+19 -14
View File
@@ -7,10 +7,14 @@
// fine in CI. Do NOT copy this pattern into real seeders.
const pluginId = process.env.STUB_PLUGIN_ID;
if (!pluginId) {
console.error("[stub-seeder] STUB_PLUGIN_ID env var is required");
process.exit(1);
}
// 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();
@@ -38,13 +42,14 @@ function makeEntities() {
];
}
export default {
name: pluginId,
// Run immediately and every 10s — CI doesn't wait for cron schedules
cron: "*/10 * * * * *",
fn: async (ctx) => {
const entities = makeEntities();
await ctx.setLiveSnapshot(pluginId, entities, 300);
console.log(`[stub-seeder] emitted ${entities.length} entities for ${pluginId}`);
},
};
export default pluginId
? {
name: pluginId,
interval: 10000,
fetch: async () => {
const entities = makeEntities();
console.log(`[stub-seeder] emitting ${entities.length} entities for ${pluginId}`);
return entities;
},
}
: {};
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "worldwideview",
"version": "2.48.19",
"version": "2.48.23",
"private": true,
"type": "module",
"packageManager": "[email protected]",
+36
View File
@@ -0,0 +1,36 @@
import { describe, it, expect, afterEach } from "vitest";
import { WebSocketServer } from "ws";
import { probeWs } from "./ws.js";
let server: WebSocketServer | undefined;
afterEach(() => { server?.close(); server = undefined; });
function startEngine(opts: { pluginId: string; requireSubscribe: boolean }) {
server = new WebSocketServer({ port: 0 });
server.on("connection", (sock) => {
sock.send(JSON.stringify({ type: "welcome", engine: "test", plugins: [opts.pluginId] }));
const send = () =>
sock.send(JSON.stringify({ type: "data", pluginId: opts.pluginId, payload: [{ id: "x" }] }));
if (!opts.requireSubscribe) { setInterval(send, 20); return; }
sock.on("message", (raw) => {
const msg = JSON.parse(raw.toString());
if (msg.action === "subscribe" && msg.pluginId === opts.pluginId) send();
});
});
const addr = server.address();
const port = typeof addr === "object" && addr ? addr.port : 0;
return `ws://127.0.0.1:${port}/stream`;
}
describe("probeWs", () => {
it("receives data from a subscribe-required engine (sends subscribe frame)", async () => {
const url = startEngine({ pluginId: "stub", requireSubscribe: true });
const ok = await probeWs({ name: "stub", wsUrl: url, timeoutMs: 3000 });
expect(ok).toBe(true);
});
it("times out (false) when the plugin never produces data", async () => {
const url = startEngine({ pluginId: "other", requireSubscribe: true });
const ok = await probeWs({ name: "stub", wsUrl: url, timeoutMs: 800 });
expect(ok).toBe(false);
});
});
+5 -1
View File
@@ -31,7 +31,11 @@ export async function probeWs(opts: {
}, opts.timeoutMs);
ws.on("open", () => {
console.log(`[ws] connected to ${opts.wsUrl}, waiting for pluginId="${opts.name}"`);
// The engine is subscribe-required: it only broadcasts a plugin's data to
// connections that have subscribed to it (websocket.ts broadcastPluginData).
// Auth is bypassed in CI via WWV_SKIP_WS_AUTH=true, so no auth frame is sent.
ws.send(JSON.stringify({ action: "subscribe", pluginId: opts.name }));
console.log(`[ws] connected to ${opts.wsUrl}, subscribed to pluginId="${opts.name}"`);
});
ws.on("message", (raw) => {