@junoflow/testkit 0.1.3 → 0.1.5

package/README.md

@@ -52,10 +52,12 @@ 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.emitted()`                          | `[{ event, payload }]`, in order                                         |
 | `h.logs()`                             | `[{ level, message, data }]`                                             |
 | `h.conformance()`                      | manifest-vs-module problems; `[]` when they agree                        |
@@ -98,10 +100,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 +130,32 @@ 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.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoflow/testkit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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 {
@@ -149,11 +182,15 @@ 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>;
   emitted(): EmittedEvent[];
   logs(): LogEntry[];
   /** Manifest-vs-module problems; empty when they agree. */

package/src/index.js

@@ -35,6 +35,10 @@ 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(),
     // 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 +98,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 +204,8 @@ 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),
     /** Events the handler put on the bus, in order. */
     emitted: () => state.emitted.slice(),
     /** Everything the handler logged, with its level. */
@@ -187,6 +219,7 @@ export function harness({ manifest, integration } = {}) {
       state.findings.length = 0;
       state.emitted.length = 0;
       state.logs.length = 0;
+      state.publishedStates.clear();
       state.store.clear();
       http.reset();
       return h;
@@ -247,6 +280,11 @@ function buildContext(manifest, state) {
         return setFinding(manifest, state, slug, standing === true, opts);
       },
     },
+    states: {
+      async publish(values) {
+        publishStates(manifest, state, values);
+      },
+    },
   };
 }
 
@@ -297,6 +335,28 @@ 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);
+  }
+}
+
 /** Adds ctx.emit, which every surface but an action has. */
 function emitting(baseCtx, manifest, state) {
   return {