@junoflow/testkit 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @junoflow/testkit
+
+Test harness for [Juno](https://github.com/boivie/juno) integrations. It runs
+your handlers with the same `ctx` the sandbox builds, and **checks every
+crossing against your manifest**.
+
+```bash
+npm install --save-dev @junoflow/testkit
+```
+
+```ts
+import { harness } from '@junoflow/testkit';
+import manifest from '../manifest.json' with { type: 'json' };
+import integration from '../src/integration';
+
+const h = harness({ manifest, integration });
+
+test('notify posts to the API and returns the receipt', async () => {
+  h.credentials({ appToken: 'tok' });
+  h.http.post('https://api.pushover.net/1/messages.json', { receipt: 'r1' });
+
+  expect(await h.action('notify', { message: 'hi' })).toEqual({
+    receipt: 'r1',
+  });
+  expect(h.problems()).toEqual([]);
+});
+
+test('conforms to its manifest', () => {
+  expect(h.conformance()).toEqual([]);
+});
+```
+
+Runner-agnostic: plain functions and thrown `AssertionError`s, no runner
+imported. vitest is what the scaffold uses; `node:test` and jest work unchanged.
+
+## Why the manifest checking matters
+
+Juno checks the contract when it **runs** an integration, which is too late to
+be a test — an installer finds out instead. The harness moves that forward:
+
+| Crossing                     | Checked against                      |
+| ---------------------------- | ------------------------------------ |
+| action params in             | the action's `params` schema         |
+| action result out            | the action's `response` schema       |
+| `ctx.emit(name, …)`          | `events` — an undeclared name throws |
+| emitted payload              | the event's `payload` schema         |
+| webhook return value         | `{ status?, headers?, body? }`       |
+| `h.config` / `h.credentials` | the declared slot, and its kind      |
+
+The failure mode this catches is the one that actually bites installers: the
+manifest says one thing and the code does another.
+
+## API
+
+`harness({ manifest, integration })` returns:
+
+| Member                                 | Does                                                             |
+| -------------------------------------- | ---------------------------------------------------------------- |
+| `h.config(values)`                     | set non-credential slots (manifest defaults are already applied) |
+| `h.credentials(values)`                | set credential slots                                             |
+| `h.action(name, params)`               | run an action, returns its result                                |
+| `h.webhook(name, request?)`            | run a webhook; `request` defaults to `POST /` with an empty body |
+| `h.poll(name)`                         | run a poll                                                       |
+| `h.listen({ until, events, timeout })` | run the listener until the condition holds, then abort           |
+| `h.store`                              | the KV, as a plain `Map`                                         |
+| `h.problems()`                         | what `ctx.problems.report` recorded                              |
+| `h.emitted()`                          | `[{ event, payload }]`, in order                                 |
+| `h.logs()`                             | `[{ level, message, data }]`                                     |
+| `h.conformance()`                      | manifest-vs-module problems; `[]` when they agree                |
+| `h.http`                               | the request mock, below                                          |
+| `h.reset()`                            | clear recorded state, keeping config and credentials             |
+
+### `h.http`
+
+Replaces global `fetch` for the duration of a handler and restores it after,
+including when the handler throws.
+
+```ts
+h.http.post('https://api.example.com/send', { receipt: 'r1' }); // 200 JSON
+h.http.get(/\/status$/, { status: 503, json: { down: true } }); // RegExp matching
+h.http.post('https://api.example.com/send', (req) => ({ echoed: req.body }));
+
+h.http.requests; // every request a handler made, in order
+```
+
+An **unmatched request throws**, naming the URL and listing what is mocked. A
+test that silently reaches the real internet is the worst outcome here, so there
+is no passthrough mode.
+
+### `h.listen`
+
+```ts
+await h.listen({ events: 3 }); // until three events are emitted
+await h.listen({ until: (h) => h.store.get('cursor') === '42' });
+```
+
+After the condition holds, `ctx.signal` aborts and the harness waits for the
+listener to return. A listener that ignores its signal **fails the test** — in
+production it hangs the supervisor on shutdown instead.
+
+### `h.conformance()`
+
+Checks the manifest and the module against each other: every declared surface
+implemented, nothing undeclared exported, a listener exactly when events have no
+webhook or poll to produce them, and every schema compiling. Returns all
+problems rather than the first — "you declared six actions and implemented four"
+is one fix, not four runs.
+
+## What the harness is faithful about
+
+- `ctx.store` round-trips values through JSON, because the real store does. A
+  `Date` comes back as a string here exactly as it would in production.
+- Config defaults declared in the manifest are applied before your test runs,
+  because the runtime always supplies them.
+- `ctx.problems.report` upserts by key, as the server does.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@junoflow/testkit",
+  "version": "0.1.0",
+  "description": "Test harness for Juno integrations: runs your handlers with a real context and checks every crossing against your manifest.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boivie/juno.git",
+    "directory": "tools/npm/testkit"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "juno",
+    "junoflow",
+    "testing",
+    "integration"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "dependencies": {
+    "ajv": "^8.17.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "types": "./src/index.d.ts"
+}

package/src/assert.js

@@ -0,0 +1,19 @@
+import { AssertionError } from 'node:assert';
+
+/**
+ * The harness reports every violation as a thrown AssertionError and nothing
+ * else. That is what keeps it runner-agnostic: vitest, node:test and jest all
+ * render an AssertionError natively, and importing any one of them would make
+ * the package pick a runner for its users.
+ */
+export function fail(message, { actual, expected } = {}) {
+  throw new AssertionError({
+    message,
+    actual,
+    expected,
+    operator: 'juno-testkit',
+    stackStartFn: fail,
+  });
+}
+
+export { AssertionError };

package/src/conformance.js

@@ -0,0 +1,85 @@
+import { schemaError } from './schema.js';
+
+/** The only keys a default export may carry. */
+const SURFACES = ['actions', 'webhooks', 'polls', 'listener'];
+
+/**
+ * Checks the manifest and the module against each other and returns a list of
+ * problems, empty when they agree.
+ *
+ * It returns rather than throws so a test can render all of them at once:
+ * "you declared six actions and implemented four" is one fix, not four runs.
+ */
+export function conformance(manifest, integration) {
+  const problems = [];
+
+  for (const key of Object.keys(integration ?? {})) {
+    if (!SURFACES.includes(key)) {
+      problems.push(
+        `default export has an unknown key "${key}" (expected one of ${SURFACES.join(', ')})`
+      );
+    }
+  }
+
+  for (const [surface, kind] of [
+    ['actions', 'action'],
+    ['webhooks', 'webhook'],
+    ['polls', 'poll'],
+  ]) {
+    const declared = Object.keys(manifest[surface] ?? {});
+    const implemented = Object.keys(integration?.[surface] ?? {});
+
+    for (const name of declared) {
+      const impl = integration?.[surface]?.[name];
+      if (typeof impl !== 'function') {
+        problems.push(
+          `${kind} "${name}" is declared in manifest.json but not implemented`
+        );
+      }
+    }
+    for (const name of implemented) {
+      if (!declared.includes(name)) {
+        problems.push(
+          `${kind} "${name}" is implemented but not declared in manifest.json — Juno will never call it`
+        );
+      }
+    }
+  }
+
+  // A listener is expected exactly when events are declared with nothing else
+  // to produce them; the server derives it the same way.
+  const hasEvents = Object.keys(manifest.events ?? {}).length > 0;
+  const hasProducer =
+    Object.keys(manifest.webhooks ?? {}).length > 0 ||
+    Object.keys(manifest.polls ?? {}).length > 0;
+  const wantsListener = hasEvents && !hasProducer;
+  const hasListener = typeof integration?.listener === 'function';
+  if (wantsListener && !hasListener) {
+    problems.push(
+      'manifest.json declares events with no webhook or poll to produce them, so a listener is required, but the default export has none'
+    );
+  }
+  if (!wantsListener && hasListener) {
+    problems.push(
+      'the default export has a listener, but manifest.json declares no events for it to emit'
+    );
+  }
+
+  // Every schema has to compile: an invalid one would silently validate
+  // nothing here and be rejected on deploy.
+  for (const [name, action] of Object.entries(manifest.actions ?? {})) {
+    pushSchemaError(problems, `action "${name}" params`, action.params);
+    pushSchemaError(problems, `action "${name}" response`, action.response);
+  }
+  for (const [name, event] of Object.entries(manifest.events ?? {})) {
+    pushSchemaError(problems, `event "${name}" payload`, event.payload);
+  }
+
+  return problems;
+}
+
+function pushSchemaError(problems, what, schema) {
+  if (!schema) return;
+  const err = schemaError(schema);
+  if (err) problems.push(`${what} is not a valid JSON Schema: ${err}`);
+}

package/src/http.js

@@ -0,0 +1,115 @@
+import { fail } from './assert.js';
+
+/**
+ * A recorder that stands in for global fetch while a handler runs.
+ *
+ * It is a few dozen lines rather than a wrapper over undici's MockAgent
+ * because that is all this needs: the template should require no mocking
+ * library, and an unmatched request must fail loudly naming the URL — a
+ * silently-passing test against a real endpoint is the worst outcome here.
+ */
+export function createHttpMock() {
+  const routes = [];
+  const requests = [];
+
+  function on(method, url, response) {
+    routes.push({ method: method.toUpperCase(), url, response });
+    return api;
+  }
+
+  const api = {
+    get: (url, response) => on('GET', url, response),
+    post: (url, response) => on('POST', url, response),
+    put: (url, response) => on('PUT', url, response),
+    patch: (url, response) => on('PATCH', url, response),
+    delete: (url, response) => on('DELETE', url, response),
+    on,
+    /** Every request a handler made, in order, with its parsed body. */
+    requests,
+    reset() {
+      routes.length = 0;
+      requests.length = 0;
+      return api;
+    },
+  };
+
+  /** The fetch implementation installed while a handler runs. */
+  api.fetch = async (input, init = {}) => {
+    const url =
+      typeof input === 'string' ? input : (input?.url ?? String(input));
+    const method = (init.method ?? input?.method ?? 'GET').toUpperCase();
+    const record = {
+      method,
+      url,
+      headers: init.headers ?? {},
+      body: init.body ?? null,
+    };
+    requests.push(record);
+
+    const route = routes.find(
+      (r) => r.method === method && matches(r.url, url)
+    );
+    if (!route) {
+      const known =
+        routes.map((r) => `  ${r.method} ${r.url}`).join('\n') || '  (nothing)';
+      fail(
+        `unmocked request: ${method} ${url}\nMocked routes:\n${known}\n` +
+          `Add one with h.http.${method.toLowerCase()}(${JSON.stringify(url)}, { … }).`
+      );
+    }
+
+    const answer =
+      typeof route.response === 'function'
+        ? await route.response(record)
+        : route.response;
+    return toResponse(answer);
+  };
+
+  return api;
+}
+
+function matches(pattern, url) {
+  if (pattern instanceof RegExp) return pattern.test(url);
+  if (typeof pattern === 'function') return pattern(url);
+  return pattern === url;
+}
+
+/**
+ * Accepts the two shapes a test wants to write: a bare object (200 JSON, the
+ * overwhelmingly common case) or a full {status, headers, json|body}.
+ */
+function toResponse(answer) {
+  if (answer instanceof Response) return answer;
+  const isEnvelope =
+    answer !== null &&
+    typeof answer === 'object' &&
+    ('status' in answer ||
+      'json' in answer ||
+      'body' in answer ||
+      'headers' in answer);
+
+  const {
+    status = 200,
+    headers = {},
+    json,
+    body,
+  } = isEnvelope ? answer : { json: answer };
+  if (json !== undefined) {
+    return new Response(JSON.stringify(json), {
+      status,
+      headers: { 'content-type': 'application/json', ...headers },
+    });
+  }
+  return new Response(body ?? '', { status, headers });
+}
+
+/** Installs the mock as globalThis.fetch for the duration of fn. */
+export async function withFetch(fetchImpl, fn) {
+  const original = globalThis.fetch;
+  globalThis.fetch = fetchImpl;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = original;
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,158 @@
+// Type declarations for @junoflow/testkit.
+//
+// Hand-written rather than generated: the package is plain JavaScript so it can
+// be read and patched without a build step, and the surface is small enough
+// that a declaration file is cheaper than a toolchain. It is deliberately loose
+// about the manifest and the integration — an author's real types come from
+// their generated types/, and re-deriving them here would only be a second,
+// weaker copy.
+
+/**
+ * One config or credential slot, as declared in manifest.json.
+ *
+ * `type` is a plain string rather than the union
+ * `'string' | 'number' | 'boolean' | 'enum' | 'string[]'` on purpose: a test
+ * imports manifest.json, and a JSON import widens every literal to its base
+ * type, so the union would reject the author's own manifest. The server is
+ * where that vocabulary is enforced; the harness does not branch on it.
+ */
+export interface ManifestConfigSlot {
+  type: string;
+  title?: string;
+  description?: string;
+  docs_url?: string;
+  default?: unknown;
+  required?: boolean;
+  credential?: boolean;
+  enum?: string[];
+}
+
+/** The parsed contents of manifest.json. */
+export interface Manifest {
+  name: string;
+  description?: string;
+  config?: Record<string, ManifestConfigSlot>;
+  actions?: Record<
+    string,
+    { params?: object; response?: object; [k: string]: unknown }
+  >;
+  events?: Record<string, { payload?: object; [k: string]: unknown }>;
+  webhooks?: Record<string, unknown>;
+  polls?: Record<string, unknown>;
+  [k: string]: unknown;
+}
+
+/** The module's default export, as Juno loads it. */
+export interface IntegrationModule {
+  actions?: Record<string, (params: never, ctx: never) => unknown>;
+  webhooks?: Record<string, (req: never, ctx: never) => unknown>;
+  polls?: Record<string, (ctx: never) => unknown>;
+  listener?: (ctx: never) => unknown;
+}
+
+export interface WebhookRequestInit {
+  method?: string;
+  headers?: Record<string, string>;
+  query?: Record<string, string>;
+  /** A string is sent as-is; anything else is JSON.stringify'd. */
+  body?: unknown;
+  url?: string;
+}
+
+export interface WebhookResult {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: string;
+}
+
+export interface RecordedRequest {
+  method: string;
+  url: string;
+  headers: HeadersInit;
+  body: BodyInit | null;
+}
+
+/** A canned answer: a bare object is 200 JSON, the common case. */
+export type MockResponse =
+  | object
+  | Response
+  | {
+      status?: number;
+      headers?: Record<string, string>;
+      json?: unknown;
+      body?: string;
+    }
+  | ((req: RecordedRequest) => unknown | Promise<unknown>);
+
+export type UrlMatcher = string | RegExp | ((url: string) => boolean);
+
+export interface HttpMock {
+  get(url: UrlMatcher, response: MockResponse): HttpMock;
+  post(url: UrlMatcher, response: MockResponse): HttpMock;
+  put(url: UrlMatcher, response: MockResponse): HttpMock;
+  patch(url: UrlMatcher, response: MockResponse): HttpMock;
+  delete(url: UrlMatcher, response: MockResponse): HttpMock;
+  on(method: string, url: UrlMatcher, response: MockResponse): HttpMock;
+  /** Every request a handler made, in order. */
+  readonly requests: RecordedRequest[];
+  reset(): HttpMock;
+}
+
+export interface ReportedProblem {
+  key: string;
+  message: string;
+  severity: 'error' | 'warning';
+}
+
+export interface EmittedEvent {
+  event: string;
+  payload: unknown;
+}
+
+export interface LogEntry {
+  level: 'debug' | 'warn' | 'error';
+  message: string;
+  data?: unknown;
+}
+
+export interface ListenOptions {
+  /** Stop when this holds. Checked after every emit. */
+  until?: (h: Harness) => boolean;
+  /** Stop once this many events have been emitted. */
+  events?: number;
+  /** Milliseconds before giving up, default 1000. */
+  timeout?: number;
+}
+
+export interface Harness {
+  config(values: Record<string, unknown>): Harness;
+  credentials(values: Record<string, string>): Harness;
+  action(name: string, params?: unknown): Promise<unknown>;
+  webhook(
+    name: string,
+    request?: WebhookRequestInit
+  ): Promise<WebhookResult | void>;
+  poll(name: string): Promise<void>;
+  listen(options?: ListenOptions): Promise<void>;
+  /** The integration's KV, as an ordinary Map. */
+  readonly store: Map<string, unknown>;
+  problems(): ReportedProblem[];
+  emitted(): EmittedEvent[];
+  logs(): LogEntry[];
+  /** Manifest-vs-module problems; empty when they agree. */
+  conformance(): string[];
+  readonly http: HttpMock;
+  reset(): Harness;
+}
+
+export function harness(options: {
+  manifest: Manifest;
+  integration: IntegrationModule;
+}): Harness;
+
+export function conformance(
+  manifest: Manifest,
+  integration: IntegrationModule
+): string[];
+
+export { AssertionError } from 'node:assert';

package/src/index.js

@@ -0,0 +1,354 @@
+import { fail } from './assert.js';
+import { conformance } from './conformance.js';
+import { createHttpMock, withFetch } from './http.js';
+import { assertValid } from './schema.js';
+
+/** How long h.listen waits before aborting, when nothing else says. */
+const DEFAULT_LISTEN_TIMEOUT_MS = 1000;
+
+/**
+ * harness({ manifest, integration }) builds the same ctx the sandbox builds and
+ * validates every crossing against the manifest: params on the way in, results
+ * on the way out, emitted event names and payloads, webhook return shape.
+ *
+ * That validation is the point. Juno checks the contract when it *runs* an
+ * integration, which is too late to be a test — an installer finds out instead.
+ * Here, an undeclared event is a thrown assertion.
+ */
+export function harness({ manifest, integration } = {}) {
+  if (!manifest || typeof manifest !== 'object') {
+    fail('harness({ manifest, integration }): manifest is required');
+  }
+  if (!integration || typeof integration !== 'object') {
+    fail(
+      "harness({ manifest, integration }): integration is required — import your module's default export"
+    );
+  }
+
+  const state = {
+    // Non-credential slots start at their manifest defaults, exactly as the
+    // runtime supplies them: a defaulted slot is never absent at handler time,
+    // so a test that never called config() must still see the default.
+    config: defaultConfig(manifest),
+    credentials: {},
+    store: new Map(),
+    problems: [],
+    emitted: [],
+    logs: [],
+  };
+
+  const http = createHttpMock();
+  const ctx = buildContext(manifest, state);
+
+  const h = {
+    /** Merge values into ctx.config. Rejects a slot the manifest never declared. */
+    config(values = {}) {
+      assertSlots(manifest, values, false);
+      Object.assign(state.config, values);
+      return h;
+    },
+
+    /** Merge values into ctx.credentials. Rejects a non-credential slot. */
+    credentials(values = {}) {
+      assertSlots(manifest, values, true);
+      Object.assign(state.credentials, values);
+      return h;
+    },
+
+    async action(name, params) {
+      const declared = manifest.actions?.[name];
+      if (!declared) {
+        fail(
+          `action "${name}" is not declared in manifest.json (have: ${names(manifest.actions)})`
+        );
+      }
+      const handler = requireHandler(integration, 'actions', name, 'action');
+      assertValid(declared.params, params, `params for action "${name}"`);
+
+      const result = await withFetch(http.fetch, () => handler(params, ctx));
+      if (declared.response) {
+        assertValid(declared.response, result, `result of action "${name}"`);
+      }
+      return result;
+    },
+
+    async webhook(name, request = {}) {
+      if (!manifest.webhooks?.[name]) {
+        fail(
+          `webhook "${name}" is not declared in manifest.json (have: ${names(manifest.webhooks)})`
+        );
+      }
+      const handler = requireHandler(integration, 'webhooks', name, 'webhook');
+      const req = buildWebhookRequest(request);
+
+      const result = await withFetch(http.fetch, () =>
+        handler(req, emitting(ctx, manifest, state))
+      );
+      assertWebhookResponse(name, result);
+      return result;
+    },
+
+    async poll(name) {
+      if (!manifest.polls?.[name]) {
+        fail(
+          `poll "${name}" is not declared in manifest.json (have: ${names(manifest.polls)})`
+        );
+      }
+      const handler = requireHandler(integration, 'polls', name, 'poll');
+      const result = await withFetch(http.fetch, () =>
+        handler(emitting(ctx, manifest, state))
+      );
+      if (result !== undefined && result !== null) {
+        fail(
+          `poll "${name}" returned a value; a poll reports through ctx.emit and returns nothing`
+        );
+      }
+    },
+
+    /**
+     * Runs the listener until `until` holds, then aborts and waits for it to
+     * unwind. A listener that ignores its abort signal fails here rather than
+     * hanging a supervisor in production.
+     */
+    async listen({ until, events, timeout = DEFAULT_LISTEN_TIMEOUT_MS } = {}) {
+      if (typeof integration.listener !== 'function') {
+        fail('the default export has no listener function');
+      }
+      const controller = new AbortController();
+      const listenerCtx = {
+        ...emitting(ctx, manifest, state),
+        signal: controller.signal,
+      };
+
+      // The listener's own failure is captured rather than left to reject an
+      // unawaited promise; it is rethrown below, after the abort has had its
+      // chance to be the explanation.
+      let listenerError = null;
+      const done = withFetch(http.fetch, () =>
+        integration.listener(listenerCtx)
+      ).catch((err) => {
+        listenerError = err;
+      });
+
+      const settled = await waitFor(() => {
+        if (typeof until === 'function') return until(h);
+        if (typeof events === 'number') return state.emitted.length >= events;
+        return false;
+      }, timeout);
+      controller.abort();
+
+      const returned = await withTimeout(done, timeout);
+      if (listenerError && listenerError.name !== 'AbortError')
+        throw listenerError;
+      if (!returned) {
+        fail(
+          `the listener did not return within ${timeout}ms of ctx.signal aborting — ` +
+            'a listener that ignores its signal hangs the supervisor on shutdown'
+        );
+      }
+      if (
+        !settled &&
+        (typeof until === 'function' || typeof events === 'number')
+      ) {
+        fail(
+          `the listener's stop condition was not met within ${timeout}ms (emitted ${state.emitted.length} event(s))`
+        );
+      }
+    },
+
+    /** The integration's KV, as an ordinary Map. */
+    store: state.store,
+    /** Problems the handler reported through ctx.problems. */
+    problems: () => state.problems.slice(),
+    /** Events the handler put on the bus, in order. */
+    emitted: () => state.emitted.slice(),
+    /** Everything the handler logged, with its level. */
+    logs: () => state.logs.slice(),
+    /** Manifest-vs-module problems; empty when they agree. */
+    conformance: () => conformance(manifest, integration),
+    http,
+
+    /** Clears everything a handler recorded, keeping config and credentials. */
+    reset() {
+      state.problems.length = 0;
+      state.emitted.length = 0;
+      state.logs.length = 0;
+      state.store.clear();
+      http.reset();
+      return h;
+    },
+  };
+
+  return h;
+}
+
+/**
+ * The base context, matching what integration-entrypoint.ts builds. Handlers
+ * cannot tell the difference, which is the only way a test here means anything
+ * about how the code runs there.
+ */
+function buildContext(manifest, state) {
+  const log = (message, data) =>
+    state.logs.push({ level: 'debug', message, data });
+  log.warn = (message, data) =>
+    state.logs.push({ level: 'warn', message, data });
+  log.error = (message, data) =>
+    state.logs.push({ level: 'error', message, data });
+
+  return {
+    config: state.config,
+    credentials: state.credentials,
+    log,
+    store: {
+      async get(key) {
+        return state.store.has(key) ? state.store.get(key) : null;
+      },
+      async set(key, value) {
+        // The real store round-trips through JSON on the wire, so a Date or a
+        // Map would come back as something else. Failing here beats a test
+        // that passes on an object production never sees.
+        state.store.set(key, JSON.parse(JSON.stringify(value ?? null)));
+      },
+    },
+    problems: {
+      async report(key, message, opts = {}) {
+        const severity = opts.severity ?? 'error';
+        if (severity !== 'error' && severity !== 'warning') {
+          fail(
+            `ctx.problems.report severity must be "error" or "warning", got ${JSON.stringify(severity)}`
+          );
+        }
+        const existing = state.problems.find((p) => p.key === key);
+        if (existing) Object.assign(existing, { message, severity });
+        else state.problems.push({ key, message, severity });
+      },
+      async clear(key) {
+        const at = state.problems.findIndex((p) => p.key === key);
+        if (at >= 0) state.problems.splice(at, 1);
+      },
+    },
+  };
+}
+
+/** Adds ctx.emit, which every surface but an action has. */
+function emitting(baseCtx, manifest, state) {
+  return {
+    ...baseCtx,
+    async emit(event, payload) {
+      const declared = manifest.events?.[event];
+      if (!declared) {
+        fail(
+          `ctx.emit("${event}") — that event is not declared in manifest.json (have: ${names(manifest.events)}). ` +
+            'Juno rejects an undeclared event at runtime.'
+        );
+      }
+      assertValid(declared.payload, payload, `payload of event "${event}"`);
+      state.emitted.push({ event, payload });
+    },
+  };
+}
+
+function defaultConfig(manifest) {
+  const out = {};
+  for (const [name, slot] of Object.entries(manifest.config ?? {})) {
+    if (!slot.credential && slot.default !== undefined)
+      out[name] = slot.default;
+  }
+  return out;
+}
+
+/** Rejects a slot name the manifest never declared, or one of the wrong kind. */
+function assertSlots(manifest, values, wantCredential) {
+  const kind = wantCredential ? 'credential' : 'config';
+  for (const name of Object.keys(values)) {
+    const slot = manifest.config?.[name];
+    if (!slot) {
+      fail(
+        `"${name}" is not a config slot declared in manifest.json (have: ${names(manifest.config)})`
+      );
+    }
+    if (Boolean(slot.credential) !== wantCredential) {
+      const actual = slot.credential ? 'credential' : 'config';
+      fail(
+        `"${name}" is a ${actual} slot — set it with h.${actual === 'credential' ? 'credentials' : 'config'}(), not h.${kind === 'credential' ? 'credentials' : 'config'}()`
+      );
+    }
+  }
+}
+
+function requireHandler(integration, surface, name, kind) {
+  const handler = integration?.[surface]?.[name];
+  if (typeof handler !== 'function') {
+    fail(
+      `${kind} "${name}" is declared in manifest.json but the default export does not implement it`
+    );
+  }
+  return handler;
+}
+
+function buildWebhookRequest(request) {
+  return {
+    method: (request.method ?? 'POST').toUpperCase(),
+    headers: request.headers ?? {},
+    query: request.query ?? {},
+    body:
+      typeof request.body === 'string'
+        ? request.body
+        : JSON.stringify(request.body ?? ''),
+    url: request.url ?? '/',
+  };
+}
+
+/** A webhook returns nothing, or the {status, headers, body} control shape. */
+function assertWebhookResponse(name, result) {
+  if (result === undefined || result === null) return;
+  if (typeof result !== 'object') {
+    fail(
+      `webhook "${name}" returned ${typeof result}; return nothing, or { status?, headers?, body? }`
+    );
+  }
+  for (const key of Object.keys(result)) {
+    if (!['status', 'headers', 'body'].includes(key)) {
+      fail(
+        `webhook "${name}" returned an unknown key "${key}"; only status, headers and body are sent`
+      );
+    }
+  }
+  if ('status' in result && !Number.isInteger(result.status)) {
+    fail(
+      `webhook "${name}" returned a non-integer status: ${JSON.stringify(result.status)}`
+    );
+  }
+  if ('body' in result && typeof result.body !== 'string') {
+    fail(`webhook "${name}" returned a non-string body; serialize it yourself`);
+  }
+}
+
+function names(obj) {
+  const keys = Object.keys(obj ?? {});
+  return keys.length ? keys.join(', ') : '(none)';
+}
+
+/** Polls a condition, resolving true when it holds or false at the deadline. */
+async function waitFor(condition, timeout) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    if (condition()) return true;
+    await new Promise((r) => setTimeout(r, 5));
+  }
+  return condition();
+}
+
+/** Resolves true when promise settled within ms, false when it did not. */
+async function withTimeout(promise, ms) {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  const settled = await Promise.race([promise.then(() => true), timeout]);
+  clearTimeout(timer);
+  return settled;
+}
+
+export { conformance } from './conformance.js';
+export { AssertionError } from './assert.js';

package/src/schema.js

@@ -0,0 +1,54 @@
+import Ajv from 'ajv/dist/2020.js';
+
+import { fail } from './assert.js';
+
+// 2020-12 is what the server's compiler defaults to for a schema with no
+// $schema key, which every manifest schema is. strict:false because a manifest
+// may carry annotation keywords (title, examples) that mean nothing to a
+// validator and must not be an error.
+const ajv = new Ajv({ strict: false, allErrors: true });
+
+const cache = new Map();
+
+/** Compiles and caches a validator. Throws when the schema itself is bad. */
+export function compile(schema) {
+  const key = JSON.stringify(schema);
+  let validate = cache.get(key);
+  if (!validate) {
+    validate = ajv.compile(schema);
+    cache.set(key, validate);
+  }
+  return validate;
+}
+
+/**
+ * Checks a value against a manifest schema and throws an assertion naming what
+ * is wrong. This is the layer that catches the failure mode that actually bites
+ * an installer: the manifest says one thing and the code does another. Nothing
+ * checks it in production, so it has to be checked here.
+ */
+export function assertValid(schema, value, what) {
+  if (!schema) return value; // nothing declared, nothing to check
+  const validate = compile(schema);
+  if (validate(value)) return value;
+  const detail = (validate.errors ?? [])
+    .map((e) => `  ${e.instancePath || '(root)'} ${e.message}`)
+    .join('\n');
+  fail(
+    `${what} does not match the schema declared in manifest.json:\n${detail}`,
+    {
+      actual: value,
+      expected: schema,
+    }
+  );
+}
+
+/** Reports whether a schema compiles, for conformance(). */
+export function schemaError(schema) {
+  try {
+    compile(schema);
+    return null;
+  } catch (err) {
+    return err.message;
+  }
+}