@junoflow/testkit 0.1.4 → 0.3.0

package/README.md

@@ -52,10 +52,13 @@ plain form works.
 | `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.schedule(name, event?)`             | run a schedule handler                                                   |
+| `h.hook(name)`                         | run a declared lifecycle hook (e.g. `activated`)                         |
 | `h.listen({ until, events, timeout })` | run the listener until the condition holds, then abort                   |
 | `h.store`                              | the KV, as a plain `Map` (`get`/`set`/`delete` all land here)            |
 | `h.findings()`                         | what `ctx.findings` asserted, as `{slug, key, severity, text, standing}` |
+| `h.states()`                           | values `ctx.states.publish` has sent, keyed by local name                |
+| `h.status()`                           | the last `ctx.status.set` report, or `null` if it never reported         |
 | `h.emitted()`                          | `[{ event, payload }]`, in order                                         |
 | `h.logs()`                             | `[{ level, message, data }]`                                             |
 | `h.conformance()`                      | manifest-vs-module problems; `[]` when they agree                        |
@@ -98,10 +101,13 @@ 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` function exactly when the
-manifest declares a `listener` section, and every schema compiling. Returns all
-problems rather than the first — "you declared six actions and implemented four"
-is one fix, not four runs.
+implemented (actions, webhooks, schedules, hooks), nothing undeclared exported,
+a `listener` function exactly when the manifest declares a `listener` section,
+every hook name inside Juno's closed vocabulary, and every schema compiling.
+`states` is a manifest declaration, not a handler surface, so it plays no part
+here — see [`h.states()`](#hstates) instead. Returns all problems rather than
+the first — "you declared six actions and implemented four" is one fix, not four
+runs.
 
 ### `h.findings()`
 
@@ -125,6 +131,51 @@ handler retracted stays in the list with `standing: false`; one that was never
 open records nothing at all, so `expect(h.findings()).toEqual([])` is the
 success-path assertion for a handler written with `set()`.
 
+### `h.states()`
+
+```ts
+await h.schedule('refresh');
+expect(h.states()).toEqual({ workday: true, 'day-kind': 'workday' });
+```
+
+`ctx.states.publish(values)` is on the base context, so an action, webhook,
+schedule or hook can all call it. `h.states()` is the current picture — a second
+publish of the same name overwrites, it does not accumulate — keyed by the local
+name the handler used, not the `<install>:<name>` id Juno scopes it to on the
+wire. An undeclared name **fails the test**, the same way an undeclared finding
+or event does.
+
+### `h.status()`
+
+```ts
+await h.schedule('fetchForecast');
+expect(h.status()).toEqual({
+  summary: '2.4 °C, cloudy — 96 intervals to 2026-09-27',
+  details: { intervals: 96 },
+});
+```
+
+`ctx.status.set` is on the base context, like `ctx.states.publish`. The report
+is replaced on every write, so `h.status()` is the last one sent, and `null`
+when the handler never reported. That is a result worth asserting too: an
+integration with nothing to say should leave the status absent. `details` is
+left out when the report had none or had an empty map. A report Juno would
+reject **fails the test**: an empty or multi-line summary, a summary longer than
+200 characters, or a detail that is not a string, number or boolean. The error
+names the key.
+
+### `h.hook(name)`
+
+```ts
+await h.hook('activated');
+```
+
+Runs a declared lifecycle hook with the same context a schedule gets. An
+undeclared hook, or one whose handler returns a value, **fails the test** — "a
+hook reports through ctx and returns nothing" is what production says too.
+`h.conformance()` also rejects a hook name outside Juno's closed vocabulary
+(today, only `activated`), which is the check that catches a typo before deploy.
+
 ## What the harness is faithful about
 
 - `ctx.store` round-trips values through JSON, because the real store does. A
@@ -133,6 +184,8 @@ success-path assertion for a handler written with `set()`.
   because the runtime always supplies them.
 - `ctx.findings` refreshes in place on `(slug, key)`, as the store does, and
   rejects a name the manifest does not declare, as the host does.
+- `ctx.status.set` details round-trip through JSON before validation, as they do
+  on the wire, so a `NaN` shows up as `null` and is rejected there as well.
 - A required slot must be set before a handler runs. An install cannot start
   with one empty, so a handler never sees one — a test that skipped
   `h.credentials(...)` would be green for a state production forbids, with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoflow/testkit",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Test harness for Juno integrations",
   "license": "MIT",
   "repository": {

package/src/conformance.js

@@ -1,7 +1,22 @@
 import { schemaError } from './schema.js';
 
-/** The only keys a default export may carry. */
-const SURFACES = ['actions', 'webhooks', 'polls', 'listener'];
+/**
+ * The only keys a default export may carry. `states` is deliberately absent:
+ * it is a manifest declaration published through ctx.states.publish, not a
+ * map of handlers, so it never appears here and never enters the
+ * declared/implemented pairing loop below the way actions/webhooks/schedules/
+ * hooks do.
+ */
+const SURFACES = ['actions', 'webhooks', 'schedules', 'listener', 'hooks'];
+
+/**
+ * The lifecycle moments the host knows how to reach — mirrors
+ * manifest.HookNames in internal/manifest/manifest.go. A hook name is not
+ * author-chosen, unlike a webhook's or a schedule's: an unrecognised one could
+ * only ever be a handler that never runs, which is exactly the typo this check
+ * catches before deploy.
+ */
+const HOOK_NAMES = ['activated'];
 
 /**
  * Checks the manifest and the module against each other and returns a list of
@@ -24,7 +39,8 @@ export function conformance(manifest, integration) {
   for (const [surface, kind] of [
     ['actions', 'action'],
     ['webhooks', 'webhook'],
-    ['polls', 'poll'],
+    ['schedules', 'schedule'],
+    ['hooks', 'hook'],
   ]) {
     const declared = Object.keys(manifest[surface] ?? {});
     const implemented = Object.keys(integration?.[surface] ?? {});
@@ -63,6 +79,14 @@ export function conformance(manifest, integration) {
     );
   }
 
+  for (const name of Object.keys(manifest.hooks ?? {})) {
+    if (!HOOK_NAMES.includes(name)) {
+      problems.push(
+        `hook "${name}" is not a lifecycle moment Juno knows; available: ${HOOK_NAMES.join(', ')}`
+      );
+    }
+  }
+
   // 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 ?? {})) {

package/src/index.d.ts

@@ -42,16 +42,49 @@ export interface Manifest {
     { title?: string; severity?: string; ttl?: string; [k: string]: unknown }
   >;
   webhooks?: Record<string, unknown>;
-  polls?: Record<string, unknown>;
+  schedules?: Record<string, unknown>;
+  /**
+   * Scalar levels this integration publishes with ctx.states.publish. Keyed
+   * by the local name; the host scopes it to `<install>:<name>`.
+   */
+  states?: Record<
+    string,
+    {
+      type?: string;
+      name?: string;
+      description?: string;
+      keywords?: string[];
+      values?: string[];
+      min?: number;
+      max?: number;
+      step?: number;
+      unit?: string;
+      [k: string]: unknown;
+    }
+  >;
+  /** Lifecycle hooks, from the closed vocabulary Juno defines — today, `activated`. */
+  hooks?: Record<
+    string,
+    { description?: string; timeout?: string; [k: string]: unknown }
+  >;
   [k: string]: unknown;
 }
 
+/** The occurrence a schedule handler runs for. */
+export interface ScheduleEvent {
+  /** ISO 8601. May be in the past after a coalesced catch-up. */
+  scheduled_at: string;
+  /** ISO 8601. */
+  fired_at: string;
+}
+
 /** 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>;
+  schedules?: Record<string, (event: ScheduleEvent, ctx: never) => unknown>;
   listener?: (ctx: never) => unknown;
+  hooks?: Record<string, (ctx: never) => unknown>;
 }
 
 export interface WebhookRequestInit {
@@ -121,6 +154,13 @@ export interface RecordedFinding {
   standing: boolean;
 }
 
+/** The install's status report, as ctx.status.set last replaced it. */
+export interface RecordedStatus {
+  summary: string;
+  /** Absent when the report carried none, or an empty map. */
+  details?: Record<string, string | number | boolean>;
+}
+
 export interface EmittedEvent {
   event: string;
   payload: unknown;
@@ -149,11 +189,17 @@ export interface Harness {
     name: string,
     request?: WebhookRequestInit
   ): Promise<WebhookResult | void>;
-  poll(name: string): Promise<void>;
+  schedule(name: string, event?: ScheduleEvent): Promise<void>;
+  /** Runs a declared lifecycle hook (e.g. `activated`) with the same context a schedule gets. */
+  hook(name: string): Promise<void>;
   listen(options?: ListenOptions): Promise<void>;
   /** The integration's KV, as an ordinary Map. */
   readonly store: Map<string, unknown>;
   findings(): RecordedFinding[];
+  /** Values ctx.states.publish has sent so far, keyed by local name. */
+  states(): Record<string, unknown>;
+  /** The last ctx.status.set report, or null when the handler never reported. */
+  status(): RecordedStatus | null;
   emitted(): EmittedEvent[];
   logs(): LogEntry[];
   /** Manifest-vs-module problems; empty when they agree. */

package/src/index.js

@@ -35,6 +35,13 @@ export function harness({ manifest, integration } = {}) {
     findings: [],
     emitted: [],
     logs: [],
+    // Values ctx.states.publish sent, keyed by local name. A Map so a second
+    // publish of the same name overwrites rather than accumulates — h.states()
+    // is the current picture, not a log.
+    publishedStates: new Map(),
+    // The last ctx.status.set report, or null before the first. One slot, not
+    // a list: the host replaces the report on every write.
+    status: null,
     // ctx.signal for every surface but the listener, which brings its own.
     // Never aborted here: the host aborts it on a timeout or a shutdown, and a
     // test has neither.
@@ -94,20 +101,46 @@ export function harness({ manifest, integration } = {}) {
       return result;
     },
 
-    async poll(name) {
-      if (!manifest.polls?.[name]) {
+    async schedule(name, event) {
+      if (!manifest.schedules?.[name]) {
         fail(
-          `poll "${name}" is not declared in manifest.json (have: ${names(manifest.polls)})`
+          `schedule "${name}" is not declared in manifest.json (have: ${names(manifest.schedules)})`
         );
       }
-      const handler = requireHandler(integration, 'polls', name, 'poll');
+      const handler = requireHandler(
+        integration,
+        'schedules',
+        name,
+        'schedule'
+      );
+      assertRequiredSlots(manifest, state);
+      const now = new Date().toISOString();
+      const ev = event ?? { scheduled_at: now, fired_at: now };
+      const result = await withFetch(http.fetch, () =>
+        handler(ev, emitting(ctx, manifest, state))
+      );
+      if (result !== undefined && result !== null) {
+        fail(
+          `schedule "${name}" returned a value; a schedule reports through ctx.emit and returns nothing`
+        );
+      }
+    },
+
+    /** Runs a declared lifecycle hook (e.g. `activated`) with the same context a schedule gets. */
+    async hook(name) {
+      if (!manifest.hooks?.[name]) {
+        fail(
+          `hook "${name}" is not declared in manifest.json (have: ${names(manifest.hooks)})`
+        );
+      }
+      const handler = requireHandler(integration, 'hooks', name, 'hook');
       assertRequiredSlots(manifest, state);
       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`
+          `hook "${name}" returned a value; a hook reports through ctx and returns nothing`
         );
       }
     },
@@ -174,6 +207,17 @@ export function harness({ manifest, integration } = {}) {
      * nothing, exactly as the host no-ops it.
      */
     findings: () => state.findings.map((f) => ({ ...f })),
+    /** Values ctx.states.publish has sent so far, keyed by local name. */
+    states: () => Object.fromEntries(state.publishedStates),
+    /**
+     * The last report ctx.status.set sent, or null when the handler never
+     * reported — absence is a legitimate outcome, not an empty report.
+     */
+    status: () =>
+      state.status && {
+        ...state.status,
+        ...(state.status.details && { details: { ...state.status.details } }),
+      },
     /** Events the handler put on the bus, in order. */
     emitted: () => state.emitted.slice(),
     /** Everything the handler logged, with its level. */
@@ -187,6 +231,8 @@ export function harness({ manifest, integration } = {}) {
       state.findings.length = 0;
       state.emitted.length = 0;
       state.logs.length = 0;
+      state.publishedStates.clear();
+      state.status = null;
       state.store.clear();
       http.reset();
       return h;
@@ -247,6 +293,16 @@ function buildContext(manifest, state) {
         return setFinding(manifest, state, slug, standing === true, opts);
       },
     },
+    states: {
+      async publish(values) {
+        publishStates(manifest, state, values);
+      },
+    },
+    status: {
+      async set(report) {
+        setStatus(state, report);
+      },
+    },
   };
 }
 
@@ -297,6 +353,75 @@ function setFinding(manifest, state, slug, standing, opts) {
   return { opened: true, cleared: false };
 }
 
+/**
+ * The one call behind ctx.states.publish. Every name is checked against the
+ * manifest before any is recorded — a batch is all-or-nothing, mirroring
+ * PublishOwned's one lock hold, so a test can never observe a partial
+ * publish. The name is checked for the same reason emit's and a finding's
+ * slug are: Juno rejects an undeclared state at runtime, and finding that out
+ * from an installer is not a test.
+ */
+function publishStates(manifest, state, values) {
+  for (const name of Object.keys(values ?? {})) {
+    if (!manifest.states?.[name]) {
+      fail(
+        `ctx.states.publish — "${name}" is not declared in manifest.json (have: ${names(manifest.states)}). ` +
+          'Juno rejects an undeclared state at runtime.'
+      );
+    }
+  }
+  for (const [name, value] of Object.entries(values ?? {})) {
+    state.publishedStates.set(name, value);
+  }
+}
+
+/** The longest summary the host accepts, in characters (registry.MaxStatusSummary). */
+const MAX_STATUS_SUMMARY = 200;
+
+/**
+ * The one call behind ctx.status.set, applying the checks registry.ValidateStatus
+ * applies: a non-empty one-line summary of at most 200 characters, and details
+ * whose values are all scalars. Details round-trip through JSON first, as they
+ * do on the wire — a NaN arrives as null and is rejected there too. An empty
+ * details map is stored as none, the way the host writes NULL for it.
+ */
+function setStatus(state, report) {
+  const summary = report?.summary;
+  if (typeof summary !== 'string' || summary.trim() === '') {
+    fail('ctx.status.set — status summary is required');
+  }
+  if (/[\r\n]/.test(summary)) {
+    fail(
+      'ctx.status.set — status summary must be one line; put the rest in details'
+    );
+  }
+  // Counted in code points, as the host counts runes.
+  const length = [...summary].length;
+  if (length > MAX_STATUS_SUMMARY) {
+    fail(
+      `ctx.status.set — status summary is ${length} characters, the limit is ${MAX_STATUS_SUMMARY}; put the rest in details`
+    );
+  }
+  const details =
+    report.details == null ? {} : JSON.parse(JSON.stringify(report.details));
+  for (const [key, value] of Object.entries(details)) {
+    if (!['string', 'number', 'boolean'].includes(typeof value)) {
+      fail(
+        `ctx.status.set — status detail ${JSON.stringify(key)} must be a string, number or boolean, got ${describeJSON(value)}`
+      );
+    }
+  }
+  state.status = Object.keys(details).length
+    ? { summary, details }
+    : { summary };
+}
+
+function describeJSON(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return typeof value === 'object' ? 'an object' : typeof value;
+}
+
 /** Adds ctx.emit, which every surface but an action has. */
 function emitting(baseCtx, manifest, state) {
   return {
@@ -377,18 +502,31 @@ function requireHandler(integration, surface, name, kind) {
 }
 
 function buildWebhookRequest(request) {
+  const body =
+    typeof request.body === 'string'
+      ? request.body
+      : JSON.stringify(request.body ?? '');
   return {
     method: (request.method ?? 'POST').toUpperCase(),
     headers: request.headers ?? {},
     query: request.query ?? {},
-    body:
-      typeof request.body === 'string'
-        ? request.body
-        : JSON.stringify(request.body ?? ''),
+    body,
+    json: parseJSONOrNull(body),
     url: request.url ?? '/',
   };
 }
 
+// The host's rule (cmd/control-plane readWebhookRequest): whatever parses is
+// parsed, whatever does not is null — content-type is not consulted.
+function parseJSONOrNull(body) {
+  if (body === '') return null;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+
 /** A webhook returns nothing, or the {status, headers, body} control shape. */
 function assertWebhookResponse(name, result) {
   if (result === undefined || result === null) return;